React 本地化与 i18next

为全球用户构建 React 应用需要一套稳健的国际化（i18n）策略。react-i18next 是最受欢迎的 React 本地化库，它构建于久经考验的 i18next 框架之上。本指南将带您了解本地化 React 应用所需的一切——从初始设置到利用 AI 驱动的翻译实现生产级的自动化。

为什么选择 react-i18next 进行 React 本地化？

react-i18next 是 React 国际化的事实标准，受到全球数千个生产级应用的信赖。以下是开发者选择它的原因：

Hooks 优先的 API - useTranslation() Hook 提供了简洁、地道的 React 集成，并在语言更改时自动重新渲染。
丰富的生态系统 - 提供用于语言检测、HTTP 后端、缓存等功能的插件。无需重复造轮子即可扩展功能。
JSON 翻译格式 - 使用标准的 JSON 文件，易于编辑、版本控制，并能与翻译工具和 AI 服务集成。
命名空间支持 - 将翻译组织成逻辑组（如 auth、dashboard、errors），以实现更好的可维护性和懒加载。
支持 SSR 和 Next.js - 与服务端渲染、React 服务端组件以及 Next.js App Router 无缝协作。
TypeScript 支持 - 为翻译键提供完整的类型安全支持，具备自动补全功能，并在编译时捕获缺失的键。

安装

安装 react-i18next 和核心 i18next 库：

npm install react-i18next i18next

可选插件

这些热门插件通过自动语言检测和懒加载翻译来增强您的 i18next 设置：

# Language detector (auto-detects user language)
npm install i18next-browser-languagedetector

# HTTP backend (load translations from server)
npm install i18next-http-backend

翻译 JSON 文件格式

react-i18next 使用嵌套的 JSON 文件进行翻译。键支持点符号、{{变量}} 插值以及内置的复数形式：

// locales/en/translation.json
{
  "welcome": {
    "title": "Welcome to our platform",
    "greeting": "Hello, {{name}}!",
    "description": "Explore features and get started."
  },
  "nav": {
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "logout": "Log out"
  },
  "cart": {
    "empty": "Your cart is empty",
    "item_one": "{{count}} item in your cart",
    "item_other": "{{count}} items in your cart",
    "checkout": "Proceed to checkout"
  }
}

嵌套键 - 按层级组织翻译（例如 welcome.title, nav.home），以保持结构清晰。
插值 - 使用 {{variableName}} 语法实现运行时动态值的插入。
复数形式 - 添加 _one 和 _other 后缀（或针对复杂语言添加 _zero, _two, _few, _many）以自动处理复数。
上下文 - 在需要时使用 _male, _female 后缀进行性别相关的翻译。

配置 i18next

i18next 支持两种主要的翻译加载方式：HTTP 后端（懒加载）和捆绑资源。请根据应用需求进行选择。

HTTP 后端（大型应用推荐）

按需从服务器的 JSON 文件加载翻译。这能保持初始包体积较小，非常适合拥有多种语言或大型翻译文件的应用：

// src/i18n/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ja", "es"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false, // React already escapes by default
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator", "htmlTag"],
      caches: ["localStorage"],
    },
  });

export default i18n;

捆绑资源（简单方案）

将翻译直接导入到包中。最适合小型应用，或当您需要立即使用翻译而无需网络请求时：

// src/i18n/i18n.ts — Bundled approach (no HTTP backend)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import en from "../locales/en/translation.json";
import fr from "../locales/fr/translation.json";
import de from "../locales/de/translation.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false,
    },
    resources: {
      en: { translation: en },
      fr: { translation: fr },
      de: { translation: de },
    },
  });

export default i18n;

在应用中初始化

在渲染任何组件之前，在应用的入口点导入 i18n 配置文件。这可确保在 UI 渲染前加载好翻译：

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n/i18n"; // Initialize i18next before rendering

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

翻译 React 组件

react-i18next 提供了两种主要的 API 来翻译组件：用于程序化访问的 useTranslation Hook，以及用于 JSX 富文本的 Trans 组件。

useTranslation Hook

useTranslation Hook 是在函数式组件中访问翻译的最常用方式。它提供 t() 函数，并在语言更改时自动重新渲染：

import { useTranslation } from "react-i18next";

function WelcomeBanner() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("welcome.title")}</h1>
      <p>{t("welcome.greeting", { name: "Alice" })}</p>
      <p>{t("welcome.description")}</p>
    </div>
  );
}

用于富文本的 Trans 组件

当翻译内容包含 HTML 或 JSX 元素（如加粗、链接等）时，请使用 Trans 组件。它能在翻译中保留您的 React 组件树：

import { Trans } from "react-i18next";

function RichTextExample() {
  return (
    <p>
      <Trans i18nKey="richText.welcome">
        Welcome to <strong>our platform</strong>.
        Visit your <a href="/dashboard">dashboard</a> to get started.
      </Trans>
    </p>
  );
}

// In the translation file:
// "richText.welcome": "Welcome to <1>our platform</1>. Visit your <3>dashboard</3> to get started."

处理复数形式

i18next 根据每种语言的 ICU 复数规则自动处理复数形式。传入 count 参数，i18next 将选择正确的复数形式：

// In translation JSON:
// "cart.item_one": "{{count}} item in your cart"
// "cart.item_other": "{{count}} items in your cart"

import { useTranslation } from "react-i18next";

function CartSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation();

  return (
    <p>{t("cart.item", { count: itemCount })}</p>
  );
}

// itemCount=0 → "0 items in your cart"
// itemCount=1 → "1 item in your cart"
// itemCount=5 → "5 items in your cart"

为英语翻译键添加 _one 和 _other 后缀
对于具有复杂复数规则的语言（如阿拉伯语、波兰语、俄语），根据需要添加 _zero, _two, _few, _many 后缀
i18next 会根据目标语言的 CLDR 复数规则自动选择正确的形式

使用命名空间进行组织

命名空间允许您按功能或领域将翻译拆分为独立的文件。这提高了可维护性并支持翻译包的懒加载：

// src/i18n/i18n.ts
i18n.init({
  defaultNS: "common",
  ns: ["common", "dashboard", "auth", "errors"],
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
  },
});

// Usage in components:
import { useTranslation } from "react-i18next";

function DashboardPage() {
  // Load specific namespace
  const { t } = useTranslation("dashboard");

  return <h1>{t("title")}</h1>;
}

function LoginForm() {
  // Load multiple namespaces
  const { t } = useTranslation(["auth", "common"]);

  return (
    <form>
      <h2>{t("auth:login.title")}</h2>
      <button>{t("common:submit")}</button>
    </form>
  );
}

动态语言切换

react-i18next 使语言切换变得无缝。调用 i18n.changeLanguage()，所有使用 useTranslation 的组件都会自动以新语言重新渲染：

import { useTranslation } from "react-i18next";

const LANGUAGES = [
  { code: "en", label: "English" },
  { code: "fr", label: "Français" },
  { code: "de", label: "Deutsch" },
  { code: "ja", label: "日本語" },
  { code: "es", label: "Español" },
];

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

React Suspense 与懒加载

react-i18next 与 React Suspense 集成，以优雅地处理异步翻译加载。使用 HTTP 后端时，Suspense 在获取翻译期间提供了简洁的加载状态：

import { Suspense } from "react";
import { useTranslation } from "react-i18next";

// i18next supports React Suspense for async translation loading
function App() {
  return (
    <Suspense fallback={<div>Loading translations...</div>}>
      <MainContent />
    </Suspense>
  );
}

function MainContent() {
  const { t, ready } = useTranslation();

  // With Suspense, 'ready' is always true here
  return <h1>{t("welcome.title")}</h1>;
}

TypeScript 类型安全的翻译键

i18next 支持完整的 TypeScript 集成。通过扩展 i18next 模块，您可以获得所有翻译键的自动补全和编译时检查，从而防止拼写错误和翻译缺失：

// src/i18n/types.ts
import "i18next";
import translation from "../locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof translation;
    };
  }
}

// Now t() calls are fully type-safe:
// t("welcome.title")       ✅ Autocomplete works
// t("welcome.greeting")    ✅ Valid key
// t("invalid.key")         ❌ TypeScript error

类型安全的键适用于 useTranslation、Trans 组件以及所有 i18next API。缺失或拼写错误的键会在您的 IDE 中被标记为 TypeScript 错误。

Next.js 服务端渲染

对于使用 App Router 的 Next.js 应用，您可以在服务端和客户端组件中使用 i18next。为服务端翻译创建一个独立的 i18next 实例，以避免在请求之间共享状态：

// next-i18next.config.js (Next.js App Router)
// For Next.js 13+ with App Router, use next-intl or i18next directly

// src/i18n/server.ts
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";

export async function getServerTranslation(lng: string) {
  const i18nInstance = createInstance();
  await i18nInstance.use(initReactI18next).init({
    lng,
    fallbackLng: "en",
    resources: {
      [lng]: {
        translation: (await import(`../locales/${lng}/translation.json`)).default,
      },
    },
  });
  return i18nInstance;
}

// In a Server Component:
export default async function Page({ params }: { params: { lng: string } }) {
  const i18n = await getServerTranslation(params.lng);
  const t = i18n.t.bind(i18n);

  return <h1>{t("welcome.title")}</h1>;
}

在服务端为每个请求创建一个新的 i18next 实例，以防止用户之间的状态泄漏
在服务端和客户端渲染中使用相同的翻译 JSON 文件
对于复杂的 Next.js 设置，考虑使用 i18next-resources-to-backend 或 next-intl 作为替代方案

利用 AI 加速翻译

设置好 react-i18next 只是成功了一半——您仍然需要为每种目标语言提供高质量的翻译。手动翻译数十个 JSON 文件既缓慢、昂贵又容易出错。AI 驱动的翻译改变了这一局面。

为什么为 React i18next 选择 l10n.dev？

l10n.dev 是专为开发者本地化工作流构建的。它能原生理解您的 JSON 翻译文件，并生成听起来自然、而非机器生成的翻译：

原生 JSON 支持 — 上传您的 translation.json 并获取格式完美、可直接使用的 JSON 文件
上下文感知 AI — 理解您的应用领域，在不同语言中保持技术术语和品牌语调的一致性
插值安全 — 保留 {{变量}}、复数后缀（_one, _other）以及嵌套键结构
批量翻译 — 在几秒钟内同时翻译成 10 多种语言
CI/CD 集成 — 使用 ai-l10n npm 包将翻译自动化作为构建流水线的一部分

AI 翻译工作流

用英语（或您的基础语言）编写源 translation.json
上传到 l10n.dev 或运行 ai-l10n CLI 进行翻译
AI 为所有目标语言生成上下文准确的翻译
将翻译后的 JSON 文件放入您的 locales/ 目录并部署

使用 ai-l10n CLI 自动化翻译

ai-l10n npm 包将 AI 翻译直接集成到您的开发工作流中。通过命令行翻译您的 JSON 文件：

# Install the l10n.dev CLI
npm install ai-l10n

# Translate your JSON files to multiple languages at once
npx ai-l10n translate src/locales/en/translation.json \
  --languages fr,de,ja,es,ko,zh-CN

构建集成

将翻译自动化添加到您的构建流水线，确保翻译始终保持最新：

package.json 脚本

{
  "scripts": {
    "translate": "ai-l10n translate src/locales/en/translation.json --languages fr,de,ja,es,ko --update",
    "pretranslate": "npm run translate",
    "dev": "vite",
    "build": "npm run translate && vite build"
  }
}

Makefile

LANGUAGES = fr,de,ja,es,ko,zh-CN

translate:
	npx ai-l10n translate src/locales/en/translation.json --languages $(LANGUAGES) --update

dev: translate
	npx vite

build: translate
	npx vite build

有关 CI/CD 集成和自动化的更多详细信息，请参阅我们的本地化自动化指南

用于 JSON 翻译的 VS Code 扩展

直接在 VS Code 中翻译您的 React i18next JSON 文件。l10n.dev 扩展让您无需离开编辑器即可翻译文件：

l10n.dev — i18n JSON 文件的 AI 翻译

右键点击任何 JSON 翻译文件，即可将其立即翻译成多种语言。支持嵌套键、插值和复数形式。

工作原理

从 VS Code 市场安装 l10n.dev 扩展
打开您的源 translation.json 文件
右键点击并选择 'Translate with l10n.dev'
选择您的目标语言并立即获取翻译后的文件

立即开始本地化您的 React 应用

现在，您已拥有使用 react-i18next 构建完全本地化 React 应用所需的一切。结合 i18next 成熟的生态系统与 AI 驱动的翻译，快速以任何语言发布您的应用。

立即翻译 JSON 文件

获取 VS Code 扩展

了解 AI 翻译

了解为何 AI 驱动的翻译比传统方法更适合 i18n 文件

探索 API

将 AI 本地化直接集成到您的 CI/CD 流程中

使用集成工具

通过我们的扩展和插件将 AI 本地化引入您的工作流

react-i18next 为 React 应用提供了完整的、生产级的本地化解决方案。凭借基于 Hooks 的 API、命名空间支持、TypeScript 集成和 SSR 兼容性，它能处理您应用可能有的所有 i18n 需求。

将 react-i18next 与 l10n.dev 的 AI 驱动翻译相结合，消除翻译瓶颈。在几秒钟内翻译您的 JSON 文件，集成到您的 CI/CD 流水线中，并自信地走向全球。

我们的使命是使软件本地化变得快速、实惠且对开发者友好。立即尝试 l10n.dev，看看 AI 如何改变您的 React 本地化工作流。