i18n国际化配置实操→60分钟极速搞定跨境多语言App

同学们，各位跨境实战精英们，大家好！

在咱们跨境出海的航程中，产品要走向全球，本地化是绕不过去的关键一环。一个多语言支持的App，不仅能大大提升用户体验，更能帮助我们快速打开新的市场。今天，咱们就来聊聊如何在React应用中，高效地实现国际化（i18n），特别是借助i18next这个强大的工具。

这次教程的灵感，来源于一位巴西的优秀开发者Aryclenio Xavier Barros分享的示例项目，他为i18next的应用打了个好样。新媒网跨境在吸收他精髓的基础上，结合咱们国内跨境团队的实战需求，特别加入了与翻译管理系统整合的环节，力求让大家学了就能用，用了就有效！

ReactJS应用里，为什么选择i18n？

ReactJS作为前端开发界的“明星”，人气那是相当高，也正因为如此，它周边生态工具非常丰富。在国际化领域，大家常用的主要就是i18next和雅虎（外媒）的react-intl。它们各有千秋，但在我看来，i18next的灵活性和社区支持，让它在咱们跨境业务场景中，显得更加得心应手。今天，我就手把手带大家把i18next集成到你的ReactJS应用里。

第一步：搭建基础项目

好，话不多说，咱们先从零开始，用TypeScript搭建一个React示例应用。打开你的命令行工具，敲入这段命令：

yarn create react-app simplelocalize-i18next-example --template typescript

这条命令会帮你创建一个名叫simplelocalize-i18next-example的React项目，并且预设了TypeScript模板。

第二步：安装核心依赖

项目搭好了，接下来就是请出咱们今天的主角i18next以及它的“好帮手”们。这些依赖包，是咱们实现多语言功能的基础。

如果你习惯用NPM：

npm install --save react-i18next i18next i18next-http-backend i18next-browser-languagedetector axios

如果你更喜欢用Yarn：

yarn add react-i18next i18next i18next-http-backend i18next-browser-languagedetector axios

简单解释一下：

react-i18next：i18next和React结合的桥梁。
i18next：核心库，负责翻译逻辑。
i18next-http-backend：从外部文件或API加载翻译资源的插件。
i18next-browser-languagedetector：自动检测用户浏览器语言的插件。
axios：用于发送HTTP请求，比如自动保存缺失翻译键值。

好了，依赖到位，咱们可以准备正式配置了！

第三步：配置i18next

这一步是核心！我们会在项目根目录下创建一个i18n.ts文件，把i18next的所有配置都放进去。然后，在index.ts里简单引入它，就能让整个应用具备国际化能力。

请看i18n.ts文件的配置代码：

import i18n from 'i18next'
import Backend from 'i18next-http-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
import { initReactI18next } from 'react-i18next'
import axios from "axios";

const isProductionCode = process.env.NODE_ENV === 'production';
const fallbackLanguage = 'en'
const projectToken = "XXXXXXXXXXXXXX"; // YOUR PROJECT TOKEN
const apiKey = "XXXXXXXXXXXXXX"; // YOUR API KEY
const apiBaseUrl = "https://api.simplelocalize.io/api";
const cdnBaseUrl = "https://cdn.simplelocalize.io";
const environment = "_latest"; // or "_production"
const loadPath = `${cdnBaseUrl}/${projectToken}/${environment}/{{lng}}`;
const loadPathWithNamespaces = `${cdnBaseUrl}/${projectToken}/${environment}/{{lng}}/{{ns}}`;
const configuration = {
    headers: {
        'X-SimpleLocalize-Token': apiKey
    }
};

const createTranslationKeys = async (requestBody: any) =>
    axios.post(`${apiBaseUrl}/v1/translation-keys/bulk`, requestBody, configuration)

const updateTranslations = async (requestBody: any) =>
    axios.patch(`${apiBaseUrl}/v2/translations/bulk`, requestBody, configuration)

const missing: any[] = [];

const saveMissing = async () => {
    if (missing.length === 0 || isProductionCode) {
        return;
    }
    console.info(`Saving ${missing.length} missing translation keys`);

    const translationKeys = missing.map((element) => ({
        key: element.translationKey,
        namespace: element.namespace,
    }));
    await createTranslationKeys({translationKeys})
        .catch((error) => console.error(`Error during creating translation keys: ${error}`));

    const translations = missing.map((element) => ({
        key: element.translationKey,
        namespace: element.namespace,
        language: element.language,
        text: element.fallbackValue,
    }));
    await updateTranslations({translations})
        .catch((error) => console.error(`Error during updating translations: ${error}`));

    missing.length = 0;
}

setInterval(async () => {
    await saveMissing();
}, 30_000); // decreasing this value may lead to the API rate limit

i18n
    .use(Backend)
    .use(LanguageDetector)
    .use (initReactI18next)
    .init({
        fallbackLng: fallbackLanguage,
        backend: {
            loadPath: loadPath, // or loadPathWithNamespaces, if you use namespaces
        },
        saveMissing: !isProductionCode,
        defaultNS: "", // you can set default namespace here
        missingKeyHandler: async (languages, namespace, translationKey, fallbackValue) => {
            console.debug(`[${namespace}][${translationKey}] not available in Translation Hosting`);
            missing.push({
                translationKey: translationKey,
                namespace: namespace ?? "",
                language: languages[0] ?? fallbackLanguage,
                fallbackValue: fallbackValue ?? ""
            });
        }
    })

export default i18n;

关于`loadPath`变量

这里有个非常实用的技巧，也是咱们跨境团队提高效率的关键！你会看到代码里有projectToken和apiKey，它们是用来连接像SimpleLocalize.io这样的在线翻译管理平台的。

为了让翻译资源能够动态加载，你需要在一个专业的翻译管理平台（比如SimpleLocalize.io）上创建一个项目。项目创建成功后，你就能拿到你的projectToken和apiKey。这个loadPath变量就是告诉i18next，去哪里加载你的多语言翻译文件。对于咱们这个演示项目，你可以先用示例中的loadPath。

自动创建缺失翻译键

代码里，我们把saveMissing属性设置为!isProductionCode，这意味着在开发环境下，如果i18next找不到某个翻译键，它会自动调用missingKeyHandler函数。这个函数会把缺失的翻译键和默认值收集起来，并通过axios请求发送到SimpleLocalize.io平台上。

新媒网跨境认为，这个功能对于快速迭代的跨境产品来说非常重要！它可以大大减少开发人员和翻译人员之间的沟通成本，确保不会有遗漏的翻译项，提升工作效率。

另外，请大家注意setInterval那里，它每30秒尝试保存一次缺失的翻译键。这里有个风险前瞻：如果你把这个间隔时间设置得太短，可能会触发API的请求频率限制，导致请求失败。所以，在实际项目中，要根据你所使用的翻译管理平台的API策略来调整。

启用i18next

配置好了i18n.ts，最后一步就是把它引入到咱们应用的入口文件index.ts里。就这么简单一句代码：import './i18n';

引入后的index.ts文件应该长这样：

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import './i18n'; // 重点在这里！引入i18next配置

ReactDOM.render(
  <React.StrictMode>
    <Suspense fallback={<div>Loading...</div>}>
      <App />
    </Suspense>
  </React.StrictMode>,
  document.getElementById('root')
);

到这里，i18next库就成功集成到你的应用中了！是不是感觉离全球用户又近了一步？

在应用中使用翻译

配置完成了，现在咱们就来真正用起来！在一个简单的网页中展示多语言内容。

引入`useTranslation` Hook

在你的React组件里，你需要引入useTranslation这个Hook。它能让你轻松访问i18next提供的翻译功能和语言切换能力。

import {useTranslation} from "react-i18next";

function App () {
    const {t, i18n} = useTranslation ();
    //...

这里，t是一个函数，你可以用它来根据给定的键加载相应的翻译文本。而i18n对象则包含了语言切换等更高级的控制功能。

在代码中使用`t`函数

t函数的使用非常直观和简洁：

t("USE_BUTTONS_BELOW")

在JSX（HTML部分）中，它会像这样被渲染：

<p>{t("USE_BUTTONS_BELOW")}</p>

切换语言

现在，咱们来给应用加上语言切换功能。这里我用几个简单的按钮来演示，没有加任何花哨的CSS样式，咱们只关注核心功能。我为英语、西班牙语和波兰语各添加了一个按钮。

import React from "react";
import "./App.css";
import { useTranslation } from "react-i18next";

function App() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <p>
        {t("USE_BUTTONS_BELOW")}
      </p>
      <button onClick={() => i18n.changeLanguage("en")}>English</button>
      <button onClick={() => i18n.changeLanguage("es")}>Spanish</button>
      <button onClick={() => i18n.changeLanguage("pl")}>Polish</button>
    </div>
  );
}

export default App;

你只需要调用i18n.changeLanguage()方法，传入目标语言的代码，i18next就会自动加载并切换显示相应的语言内容。