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 的 i18n 请使用 nextjs-i18n，Astro 请使用 astro-i18n。

React 19 的 react-i18next

Agent 工作流（强制）

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

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

关键规则：

• 文件少于 100 行（达到 90 行时拆分）
• 接口放在 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 → 导致加载闪烁
• ❌ 将所有翻译放在一个文件中 → 使用命名空间
• ❌ 不设置回退语言 → 导致 UI 异常
• ❌ 拼接字符串 → 使用插值 {{var}}
• ❌ 手动管理语言状态 → 使用 i18n.changeLanguage()