使用i18next进行React本地化

为全球受众构建React应用程序需要稳健的国际化（i18n）策略。react-i18next是最流行的React本地化库，建立在经过实战检验的i18next框架之上。本指南将引导您完成本地化React应用程序所需的一切——从初始设置到使用AI驱动的翻译实现生产就绪的自动化。

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

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

钩子优先的API - useTranslation()钩子提供了简洁、地道的React集成，并在语言更改时自动重新渲染。
丰富的生态系统 - 用于语言检测、HTTP后端、缓存等的插件。无需重新发明轮子即可扩展功能。
JSON格式翻译 - 使用标准的JSON格式文件，易于编辑、版本控制以及与翻译工具和AI服务集成。
命名空间支持 - 将翻译组织成逻辑组（身份验证、仪表板、错误），以实现更好的可维护性和延迟加载。
服务器端渲染与Next.js就绪 - 与服务器端渲染、React服务器组件和Next.js应用路由器无缝协作。
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配置文件。这确保了在您的用户界面渲染之前加载翻译：

// 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钩子和用于带有JSX的富文本的Trans组件。

useTranslation钩子

useTranslation钩子是在函数组件中访问翻译的最常见方式。它提供了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复数规则自动处理复数形式。传递一个计数参数，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进行服务器端渲染

对于使用应用路由器的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格式文件
考虑将i18next-resources-to-backend或next-intl作为复杂Next.js设置的替代方案

利用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命令行界面进行翻译
AI为所有目标语言生成上下文准确的翻译
将翻译后的JSON格式文件放入您的locales/目录并部署

使用ai-l10n命令行界面自动化翻译

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应用程序提供了完整、生产就绪的本地化解决方案。凭借基于钩子的API、命名空间支持、TypeScript集成和服务器端渲染兼容性，它处理了您的应用程序可能具有的每一个国际化需求。

将react-i18next与l10n.dev的AI驱动翻译相结合，消除翻译瓶颈。在几秒钟内翻译您的JSON格式文件，与您的CI/CD管道集成，并充满信心地在全球范围内发布。

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