
React 国际化完整指南
从零到多语言:在 React 应用中设置 i18n,再利用 AI 自动翻译。
安装软件包
您需要三个软件包:react-i18next(React 绑定)、i18next(核心库),以及用于自动检测语言的可选软件包 i18next-browser-languagedetector。
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend配置 i18n 实例
创建 i18n 配置文件,使用默认语言、翻译资源和插件链初始化 i18next。必须在任何组件渲染前,于应用入口点导入此文件。
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import Backend from 'i18next-http-backend';
i18n
.use(Backend)
.use(LanguageDetector)
.use(initReactI18next) // Must come before .init()
.init({
fallbackLng: 'en',
debug: process.env.NODE_ENV === 'development',
interpolation: {
escapeValue: false, // React already escapes
},
backend: {
loadPath: '/locales/{{lng}}/{{ns}}.json',
},
});
export default i18n;使用 I18nextProvider 包装应用
在应用根目录导入 i18n 配置文件,并使用 I18nextProvider 包装组件树。否则,useTranslation() 会返回原始键而非译文。
import React, { Suspense } from 'react';
import ReactDOM from 'react-dom/client';
import { I18nextProvider } from 'react-i18next';
import i18n from './i18n'; // Import your config
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<Suspense fallback={<div>Loading...</div>}>
<I18nextProvider i18n={i18n}>
<App />
</I18nextProvider>
</Suspense>
</React.StrictMode>
);创建翻译文件
为每种语言创建一个 JSON 文件。使用嵌套键按功能或页面组织字符串,并将源语言(通常是英语)作为单一可信源。
// public/locales/en/translation.json
{
"nav": {
"home": "Home",
"about": "About",
"settings": "Settings"
},
"greeting": "Hello, {{name}}!",
"cart": {
"itemCount_one": "{{count}} item",
"itemCount_other": "{{count}} items"
}
}
// public/locales/de/translation.json
{
"nav": {
"home": "Startseite",
"about": "Über uns",
"settings": "Einstellungen"
},
"greeting": "Hallo, {{name}}!",
"cart": {
"itemCount_one": "{{count}} Artikel",
"itemCount_other": "{{count}} Artikel"
}
}在组件中使用译文
在任何组件中调用 useTranslation() 获取 t() 函数。它可用于简单字符串、插值变量,以及通过 Trans 组件嵌入 JSX 的译文。
import { useTranslation } from 'react-i18next';
function Greeting({ userName }: { userName: string }) {
const { t } = useTranslation();
return (
<div>
<h1>{t('greeting', { name: userName })}</h1>
<nav>
<a href="/">{t('nav.home')}</a>
<a href="/about">{t('nav.about')}</a>
</nav>
</div>
);
}import { Trans, useTranslation } from 'react-i18next';
// For JSX inside translations:
// "terms": "By signing up, you agree to our <link>Terms</link>."
function SignUp() {
const { t } = useTranslation();
return (
<Trans i18nKey="terms" components={{
link: <a href="/terms" className="underline" />
}} />
);
}处理复数和变量
i18next 按 CLDR 规则而非简单的单数/复数处理。阿拉伯语有 6 种形式(zero、one、two、few、many、other),日语只有 1 种(other)。请在翻译文件中定义所有必需形式,i18next 会自动选择正确形式。
// English: 2 forms (one, other)
{
"itemCount_one": "{{count}} item",
"itemCount_other": "{{count}} items"
}
// Arabic: 6 forms (zero, one, two, few, many, other)
{
"itemCount_zero": "لا عناصر",
"itemCount_one": "عنصر واحد",
"itemCount_two": "عنصران",
"itemCount_few": "{{count}} عناصر",
"itemCount_many": "{{count}} عنصرًا",
"itemCount_other": "{{count}} عنصر"
}
// Japanese: 1 form (other)
{
"itemCount_other": "{{count}}個のアイテム"
}添加语言切换与检测
构建调用 i18n.changeLanguage() 的语言选择器,并结合浏览器语言检测器,在首次访问时自动检测用户的首选语言,随后保存用户的明确选择。
import { useTranslation } from 'react-i18next';
const LANGUAGES = [
{ code: 'en', label: 'English' },
{ code: 'de', label: 'Deutsch' },
{ code: 'ja', label: '日本語' },
{ code: 'es', label: 'Español' },
];
function LanguageSwitcher() {
const { i18n } = useTranslation();
return (
<select
value={i18n.language}
onChange={(e) => i18n.changeLanguage(e.target.value)}
>
{LANGUAGES.map(({ code, label }) => (
<option key={code} value={code}>{label}</option>
))}
</select>
);
}自动翻译
完成 i18n 设置后,使用 AI 翻译本地化文件。在 IDE 中让 AI 助手翻译源文件,或在 CI/CD 管线中使用 i18n Agent CLI。
# In your IDE, ask your AI assistant:
> Translate public/locales/en/translation.json to German, Japanese, and Spanish
✓ de/translation.json created (1.2s)
✓ ja/translation.json created (1.5s)
✓ es/translation.json created (1.1s)
# Or use the CLI in CI/CD:
npx i18n-agent translate public/locales/en/translation.json --lang de,ja,es自动保证翻译质量
常见问题
译文显示原始键
缺少回退时发生 Suspense 错误
SSR 水合不匹配
翻译键没有自动补全
推荐的文件结构
my-react-app/
├── public/
│ └── locales/
│ ├── en/
│ │ ├── translation.json # Default namespace
│ │ ├── common.json # Shared strings
│ │ └── dashboard.json # Feature namespace
│ ├── de/
│ │ ├── translation.json
│ │ ├── common.json
│ │ └── dashboard.json
│ └── ja/
│ └── ...
├── src/
│ ├── i18n.ts # i18n configuration
│ ├── main.tsx # App entry with Provider
│ ├── App.tsx
│ └── components/
│ └── LanguageSwitcher.tsx
└── package.json立即试用 i18n Agent
将翻译文件拖放到此处
JSON, YAML, PO, XML, CSV, Markdown, Properties
或点击选择文件
目标语言