Gatsby多语言站避坑指南→省80%时间→成功率翻倍！

各位跨境圈的朋友们，大家下午好！作为一名在跨境实战中摸爬滚打多年的老兵，我深知咱们出海卖家，最头疼的往往不是产品本身，而是如何真正地“入乡随俗”，把咱们的品牌和商品，用当地人听得懂、喜欢看的方式呈现出来。特别是面对全球市场，一个多语言的网站，那简直是标配，是咱们品牌走向世界的第一步。新媒网跨境获悉，一个设计精良、本地化到位的多语言网站，能显著提升用户体验和转化率。

今天，咱们就来手把手，聊聊如何利用GatsbyJS这个前端利器，打造一个高效、优雅的多语言落地页。别看技术名词听起来唬人，跟着我的节奏，一步步拆解下来，你会发现，其实没那么复杂。

准备工作：搭积木前先备料

首先，咱们得有个Gatsby项目的基础。如果你还没搭起来，可以先找个教程快速初始化一个。今天我们直接从“让网站说多种语言”这个核心任务开始。原作者给大家准备了一个模板项目，大家也可以参考。

安装核心依赖

要做国际化，react-intl这个库是行业里的“老大哥”了，它和Gatsby的插件体系配合得天衣无缝。咱们先把它请进门。

如果你用npm：

npm install --save react-intl

如果你用Yarn：

yarn add react react-intl

搭建国际化（i18n）配置框架

为了让咱们的语言配置清晰明了，咱们先在src目录下建一个i18n.js文件，把所有和语言相关的配置都集中在这里。

const languages = ['en', 'pl', 'es']; // 定义支持的语言，这里以英文、波兰语、西班牙语为例
const defaultLanguage = 'en'; // 设定默认语言为英文

exports.defaultLanguage = defaultLanguage;
exports.languages = languages;

这段代码很简单，就告诉咱们的程序，网站支持哪些语言，以及默认是哪一种。这是后续所有逻辑的基础。

核心工具函数：导航小助手

接下来，我们需要一些“小助手”函数，来帮咱们处理多语言页面间的跳转和语言识别。在src目录下新建一个linkUtils.js文件。

import {defaultLanguage, languages} from "./i18n";

// 获取翻译后的路径
const getTranslatedPath = (pathname, to) => {
    const currentPageLanguage = getCurrentPageLanguage(pathname); // 获取当前页面语言
    let languagePath = '';

    const isDefaultLanguage = defaultLanguage === currentPageLanguage; // 判断是否为默认语言

    if (!isDefaultLanguage) { // 如果不是默认语言，路径前缀加上语言标识
        languagePath = '/' + currentPageLanguage
    }

    let outputPath = `${languagePath}${to}`; // 拼接最终路径

    const hasTrailingSlash = outputPath.endsWith("/"); // 检查是否有斜杠结尾

    if (!hasTrailingSlash) { // 确保路径以斜杠结尾，这是Gatsby的常见实践
        outputPath += "/";
    }

    return outputPath;
}

// 获取当前页面语言
const getCurrentPageLanguage = (pathname) => {
    const pathElements = pathname.split("/"); // 将路径按斜杠分割

    for (let element of pathElements) {
        for (let language of languages) {
            if (element === language) { // 遍历路径元素，匹配已定义的语言
                return language;
            }
        }
    }

    return defaultLanguage; // 如果没找到，就返回默认语言
};

export {getTranslatedPath, getCurrentPageLanguage};

getTranslatedPath函数：它的职责是，当你从一个英文页面跳转到另一个英文页面时，它能确保目标页的链接仍然是英文路径（比如/about）；如果你在一个波兰语页面，想去关于我们，它会自动生成/pl/about这样的路径。这样就能保证用户在浏览时，始终停留在自己选择的语言环境里，体验感一流。
getCurrentPageLanguage函数：这个就更直接了，它能从当前页面的URL路径中，“揪出”当前的语言是什么，比如看到/pl/就知道是波兰语。

自定义链接组件：让跳转更智能

为了让用户在咱们网站里畅游时，能始终保持他们选择的语言，我们需要一个定制版的<a>标签。新建一个文件，比如LinkTranslated.js。

import React from "react";
import {Location} from '@reach/router'; // 引入路由位置信息
import {getCurrentPageLanguage, getTranslatedPath} from "./linkUtils";

const LinkTranslated = ({children = [], className = "", href = "/"}) => {
    return (
        <Location>
            {locationProps => {
                const {pathname = ""} = locationProps.location; // 从路由中获取当前路径
                return <a className={className} href={getTranslatedPath(pathname, href)} hrefLang={getCurrentPageLanguage(pathname)} >
                    {children}
                </a>;
            }}
        </Location>
    );
};

export default LinkTranslated;

现在，咱们就可以像用普通的HTML <a>标签一样使用LinkTranslated了。你只需要传入基础的href属性，它就会自动转换成带有当前语言前缀的链接。这里还用到了hrefLang属性，这在SEO优化中非常重要，它能告诉搜索引擎这个链接指向的页面是什么语言的，有助于提高咱们网站在不同语言搜索结果中的排名。

IntlProvider包装器：语言切换的核心

接下来，咱们创建一个组件，它将作为所有多语言页面的“语言提供者”。新建SimpleLocalize.js文件。

import React from "react";
import {IntlProvider} from "react-intl";

function SimpleLocalize(props) {
    const language = props.pageContext.language; // 获取当前页面的语言
    const messages = props.pageContext.messages; // 获取当前页面的翻译文本

    return (
        <IntlProvider locale={language} messages={messages}>
            {props.children}
        </IntlProvider>
    );
}

export default SimpleLocalize;

这个SimpleLocalize组件的妙处在于，它帮咱们简化了在每个页面上使用IntlProvider的繁琐。它会从Gatsby的页面上下文（pageContext）中获取当前页面的语言和对应的翻译文本，然后把这些信息提供给页面中的所有react-intl组件，比如FormattedMessage。

翻译文本：网站的“灵魂”

咱们需要一个JSON文件来存放所有的翻译文本。在项目根目录下新建i18n-translations.json。

{
  "en" : {
    "welcome-on-our-website" : "Welcome on our multi-language website",
    "hello-world" : "Hello World!",
    "about-us" : "About us",
    "learn-more-about-us" : "Learn more about us",
    "homepage" : "Homepage"
  },
  "pl" : {
    "welcome-on-our-website" : "Witamy na naszej wielojęzycznej stronie internetowej",
    "hello-world" : "Witaj Świecie!",
    "about-us" : "O nas",
    "learn-more-about-us" : "Dowiedz się więcej o nas",
    "homepage" : "Strona główna"
  },
  "es" : {
    "welcome-on-our-website" : "Bienvenido a nuestro sitio web multilingüe",
    "hello-world" : "Hola, mundo.",
    "about-us" : "Sobre nosotros",
    "learn-more-about-us" : "Más información sobre nosotros",
    "homepage" : "Página web"
  }
}

这里就是咱们网站里所有文本的“翻译字典”了。每个语言下面对应着一系列的键值对，键是咱们在代码里使用的标识符（比如welcome-on-our-website），值就是对应的翻译内容。

新媒网跨境认为，随着咱们业务规模的扩大和支持语言的增多，手动管理这样一个庞大的JSON文件会变得越来越困难，甚至可能出现错误。这时候，专业的翻译管理工具或者AI辅助翻译平台，比如SimpleLocalize、或者结合OpenAI ChatGPT、DeepL、Google Translate等主流AI翻译工具，就能大大提升效率，减少人工成本。他们能够帮助咱们自动上传、下载翻译文本，甚至进行初步的机器翻译，让咱们的本地化工作事半功倍。

配置多语言页面生成：Gatsby的魔术

这是整个多语言网站搭建的“魔法核心”！咱们需要编辑gatsby-node.js配置文件，并覆写onCreatePage函数。

const messages = require("./i18n-translations.json") // 导入翻译文本
const {languages, defaultLanguage} = require("./src/i18n"); // 导入语言配置

exports.onCreatePage = async ({page, actions}) => {
    const {createPage, deletePage} = actions;

    return new Promise((resolve) => {
        let path = page.path; // 获取原始页面路径

        deletePage(page); // 核心操作：先删除Gatsby默认创建的页面

        for (let language of languages) { // 遍历所有支持的语言
            const isDefaultLanguage = language === defaultLanguage; // 判断是否是默认语言

            // 为非默认语言的页面路径添加语言前缀
            if (!isDefaultLanguage) {
                path = '/' + language + page.path;
            } else {
                // 默认语言的路径需要重置回原始路径，否则会受上一次循环影响
                path = page.path;
            }

            const pageForLanguage = Object.assign({}, page, {
                originalPath: page.path, // 记录原始路径
                path: path, // 设置新路径
                context: { // 将语言和对应翻译文本添加到页面上下文
                    language,
                    messages: messages[language]
                }
            });

            createPage(pageForLanguage) // 基于新的路径和上下文，创建多语言页面
        }

        resolve()
    })
};

这里面发生了不少事情，咱们来捋一捋：

导入配置和翻译：咱们把之前定义的i18n-translations.json和i18n.js都引进来。
删除原始页面：Gatsby默认会根据src/pages下的文件创建页面。但现在咱们要自己控制，所以先用deletePage把Gatsby默认生成的页面“撤销”掉。
循环生成多语言页面：接着，咱们遍历i18n.js里定义的所有语言。
路径处理：对于非默认语言，咱们会在原始页面路径前面加上语言标识符，比如/about会变成/pl/about。而默认语言，就保持原样。这里要特别注意，每次循环开始时，需要确保path变量是基于当前的page.path来重新构建的，否则可能会出现路径错误。
注入上下文：最关键的一步！咱们通过context把当前语言（language）和这个语言对应的翻译文本（messages）注入到每个新生成的页面里。这样，每个页面就能“知道”自己是哪个语言版本的，并且能拿到自己专属的翻译内容。
创建新页面：最后，用createPage基于新的路径和上下文，生成我们想要的多语言页面。

通过这样的设置，Gatsby会在构建时，为咱们的每个页面都生成多个语言版本，大大减轻了咱们手动创建和管理多语言页面的工作量。

创建首个多语言页面：首页

现在，咱们可以在src/pages目录下创建index.js文件，来设计咱们的首页了。

import React from "react";
import {FormattedMessage} from "react-intl"; // 引入翻译组件
import LinkTranslated from "../LinkTranslated"; // 引入自定义链接组件
import SimpleLocalize from "../SimpleLocalize"; // 引入语言提供器

function IndexPage(props) {
    return (
        <SimpleLocalize {...props}>
            <h1>
                <FormattedMessage id="hello-world" defaultMessage="Hello World!" /> {/* 使用FormattedMessage显示翻译内容 */}
            </h1>
            <p>
                <FormattedMessage id="welcome-on-our-website" defaultMessage="Welcome on our multi-language website" />
            </p>
            <LinkTranslated className="btn btn-link" href="/about" >
                <FormattedMessage id="learn-more-about-us" defaultMessage="Learn more about us" />
            </LinkTranslated>
            <ul>
                <li><a href="/">English (Default)</a></li>
                <li><a href="/pl/">Polish</a></li>
                <li><a href="/es/">Spanish</a></li>
            </ul>
        </SimpleLocalize>
    );
}

export default IndexPage

在这里，SimpleLocalize组件会为页面提供IntlProvider和intl对象，让咱们的FormattedMessage组件能够正常工作。FormattedMessage组件非常方便，你只需要传入一个id（对应i18n-translations.json中的键），它就会自动显示对应语言的文本。如果找不到id，它还会显示defaultMessage，确保不会出现空白。

创建第二个多语言页面：关于我们

同样地，在src/pages目录下创建about.js文件。

import React from "react";
import SimpleLocalize from "../SimpleLocalize";
import {FormattedMessage} from "react-intl";
import LinkTranslated from "../LinkTranslated";

function AboutPage(props) {
    return (
        <SimpleLocalize {...props}>
            <h1>
                <FormattedMessage id="about-us" defaultMessage="About us" />
            </h1>
            <LinkTranslated className="btn btn-link" href="/" >
                <FormattedMessage id="homepage" defaultMessage="Homepage" />
            </LinkTranslated>
        </SimpleLocalize>
    );
}

export default AboutPage;

原理和首页完全一致，用FormattedMessage来显示“关于我们”的标题，用LinkTranslated来提供返回首页的多语言链接。

成果展示

现在，激动人心的时刻到了！在你的项目根目录运行npm run develop，你就能看到一个活生生的多语言Gatsby项目了。
Multi-language Gatsby project example

完整的代码示例大家可以在原作者的GitHub仓库中找到：github.com/simplelocalize/multi-language-gatsby-example。

翻译文本提取与自动化

Uploading extracted translation keys to translation editor

在GitHub仓库中，你还会发现package.json里有一些额外的脚本。为了进一步提高效率，咱们通常会利用工具自动化提取代码中的翻译键（ID）。这里，作者使用了@formatjs/cli作为开发依赖来完成这项工作。

## npm
npm install --save-dev @formatjs/cli

## yarn
yarn add -D @formatjs/cli

安装好之后，就可以运行作者预设的脚本了：

npm run extract脚本：它会扫描咱们所有的FormattedMessage组件，把其中用到的id（翻译键）都提取出来，生成一个i18n-extracted.json文件。这样就不用手动去收集翻译键了。
npm run sync脚本：这个脚本更进一步，它会利用simplelocalize-cli这样的工具，将提取出来的翻译键上传到翻译管理平台，然后从平台下载最新的、已经翻译好的文本，更新到咱们的i18n-translations.json文件中。实现了翻译流程的自动化。

小贴士： 一旦你修改了JSON翻译文件，GatsbyJS可能不会立即显示更新。这时候，你可能需要重启GatsbyJS服务。如果重启后仍然没有生效，可以尝试先运行npm run clean清除缓存，再运行npm run develop。

翻译文本管理与AI赋能

在专业的翻译管理工具中，咱们可以像这样集中管理所有的翻译字符串。
Manage your translation strings in Translation Editor

通过这些平台，你可以轻松地添加更多语言，并且利用OpenAI ChatGPT、DeepL或Google Translate等AI工具进行自动翻译。这大大加快了本地化的速度，让咱们的网站能够迅速覆盖全球更多语种的用户。

风险前瞻与时效提醒：

技术更新快：GatsbyJS和react-intl这类前端框架和库都在持续迭代更新。本教程基于当前（2025年）的稳定版本，但请大家在实际操作中，务必关注官方文档，及时更新依赖，以确保项目稳定性和安全性。
SEO合规性：正确使用hrefLang属性对多语言网站的SEO至关重要。同时，针对不同国家和地区的隐私政策（如欧盟的GDPR、美国加州的CCPA等），咱们在收集和处理用户数据时，也要确保网站内容和技术实现符合当地法规要求，避免潜在的法律风险。
性能优化：多语言网站意味着更多的内容和可能更多的请求。在构建过程中，要关注网站的加载速度和响应性能，尤其是在服务器部署和CDN选择上，确保全球用户都能获得流畅的访问体验。

总而言之，一个配置得当、本地化充分的多语言网站，加上合理使用的hrefLang属性，不仅能大幅提升用户体验，还能在搜索引擎中获得更高的排名，为咱们跨境业务在全球市场赢得先机！希望今天的分享能给大家带来实实在在的帮助。

新媒网（公号: 新媒网跨境发布），是一个专业的跨境电商、游戏、支付、贸易和广告社区平台，为百万跨境人传递最新的海外淘金精准资讯情报。

本文来源：新媒网 https://nmedialink.com/posts/gatsby-multisite-avoid-pitfalls-save-80-time.html