react-i18n

在 React 19 应用（Vite/CRA，而非 Next.js）中实现 react-i18next：`useTranslation()` Hook 的用法、TypeScript Selector API（i18next ≥25.4）以实现类型安全的翻译键、用于代码分割的命名空间组织、使用 ICU MessageFormat 的复数规则、插值（变量、日期、数字、货币）、延迟加载翻译，以及浏览器/URL/ Cookie 语言检测。

还涵盖 React 19 Suspense 集成、用于在翻译中嵌入 JSX 的 Trans 组件、RTL 语言支持、缺失键的回退策略，以及 i18n 单元测试设置。本技能明确适用于不使用 Next.js 的 React 应用——Next.js App Router 国际化请使用 nextjs-i18n，Astro 请使用 astro-i18n。

React 19 的 react-i18next

Agent 工作流（必需）

在进行任何实现之前，必须并行启动 3 个 Agent，每个调用一次 Agent，并设置 name：

1. fuse-ai-pilot:explore-codebase - 分析现有的 i18n 设置和翻译模式
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 react-i18next/i18next 文档
3. mcp__context7__query-docs - 检查 TypeScript Selector API 和 React 19 Suspense 模式

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

必需：SOLID 原则

始终应用 solid-react 技能中的 SOLID 原则。

→ 完整规则请参阅 ../solid-react/SKILL.md

关键规则：

• 源文件不得超过 FUSE_SOLID_MAX_LINES，内聚性降低时应按职责拆分
• 接口位于 modules/[feature]/src/interfaces/
• 所有导出项都必须编写 JSDoc
• 组件中不得包含业务逻辑

---

核心 Hook

Hook	用途	指南
useTranslation()	访问翻译和 i18n 实例	references/i18next-basics.md
useTranslation(ns)	加载指定命名空间	references/namespaces.md
useTranslation([ns])	加载多个命名空间	references/namespaces.md

→ 详细用法请参阅 references/i18next-basics.md

---

关键软件包

软件包	用途	大小
i18next	核心库	~40KB
react-i18next	React 绑定	~12KB
i18next-http-backend	延迟加载	~5KB
i18next-browser-languagedetector	自动检测	~8KB

---

主要功能

TypeScript Selector API（i18next ≥25.4）

提供自动补全的类型安全翻译。 → 请参阅 references/typescript-types.md

命名空间

按功能组织翻译，以便进行代码分割。 → 请参阅 references/namespaces.md

复数规则

基于数量的规则，支持 ICU MessageFormat。 → 请参阅 references/pluralization.md

插值

格式化变量、日期、数字和货币。 → 请参阅 references/interpolation.md

延迟加载

按需加载每个路由的翻译。 → 请参阅 references/lazy-loading.md

语言检测

自动检测浏览器、URL、Cookie 和 localStorage 中的语言。 → 请参阅 references/language-detection.md

React 19 集成

Suspense、useTransition、并发渲染。 → 请参阅 references/react-19-integration.md

Trans 组件

在翻译中嵌入 JSX 元素。 → 请参阅 references/trans-component.md

测试

为单元测试模拟 i18n。 → 请参阅 references/testing.md

RTL 支持

支持从右向左书写的语言（阿拉伯语、希伯来语）。 → 请参阅 references/rtl-support.md

回退策略

妥善处理缺失的键。 → 请参阅 references/fallback-strategies.md

---

模板

模板	使用场景
templates/basic-setup.md	配置 React 19
templates/language-switcher.md	下拉组件
templates/typed-translations.md	TypeScript Selector API
templates/form-validation-i18n.md	翻译表单错误
templates/lazy-loading-routes.md	按路由加载
templates/date-number-formatter.md	Intl 格式化
templates/plural-interpolation.md	基于计数的消息
templates/trans-component-examples.md	翻译中的 JSX
templates/testing-i18n.md	单元测试设置

---

模块化架构（SOLID）

src/
├── modules/cores/i18n/
│   ├── src/
│   │   ├── interfaces/
│   │   │   └── i18n.interface.ts
│   │   ├── services/
│   │   │   └── i18n.service.ts
│   │   ├── hooks/
│   │   │   └── useLanguage.ts
│   │   └── config/
│   │       └── i18n.config.ts
│   ├── components/
│   │   └── LanguageSwitcher.tsx
│   └── locales/
│       ├── en/
│       │   └── translation.json
│       └── es/
│           └── translation.json
└── main.tsx

---

最佳实践

1. Suspense：使用 <Suspense> 包裹应用，以处理加载状态
2. 命名空间：每个功能／模块使用一个命名空间
3. TypeScript：使用 Selector API 实现类型安全的键
4. 延迟加载：按需加载命名空间
5. 检测：配置语言检测顺序
6. 回退：始终设置 fallbackLng

---

禁止事项（反模式）

• ❌ 硬编码字符串 → 使用 t('key')
• ❌ 不使用 Suspense → 导致加载闪烁
• ❌ 将所有翻译放在一个文件中 → 使用命名空间
• ❌ 不设置回退语言 → 界面无法正常显示
• ❌ 字符串拼接 → 使用插值 {{var}}
• ❌ 手动管理语言状态 → 使用 i18n.changeLanguage()