名称：软件本地化描述：React、Vue、Angular、Next.js 和 Node.js 的生产级 i18n/l10n 模式。涵盖库选择（i18next/react-i18next、FormatJS/react-intl、next-intl、vue-i18n、@angular/localize、Lingui、typesafe-i18n）、ICU 消息格式、RTL 支持、本地路由/检测、TMS 集成、字符串提取和 CI/CD 翻译工作流。用于在代码库中设置或调试本地化时使用。

软件本地化 - 快速参考

现代 Web 应用程序中国际化（i18n）和本地化（l10n）的生产模式。涵盖库选择、翻译管理、ICU 消息格式、RTL 支持和 CI/CD 工作流。

快照（2026-01）：i18next 25.x、react-i18next 16.x、react-intl 8.x、vue-i18n 11.x、next-intl 4.x、@angular/localize 21.x。始终在目标仓库中验证当前版本（参见货币检查协议）。

权威参考：

快速参考

任务	工具/库	命令	何时使用
React i18n	react-i18next	`npm i i18next react-i18next`	大多数 React 应用，灵活性高
React i18n（ICU）	react-intl（FormatJS）	`npm i react-intl`	ICU 优先的消息目录 + 工具链
Vue i18n	vue-i18n	`npm i vue-i18n`	Vue 3 应用
Angular i18n	@angular/localize	`ng add @angular/localize`	Angular 应用
Next.js i18n	next-intl	`npm i next-intl`	Next.js App Router
最小化捆绑包	LinguiJS	`npm i @lingui/core @lingui/react`	捆绑包大小关键应用
类型安全	typesafe-i18n	`npm i typesafe-i18n`	TypeScript 优先项目
字符串提取	i18next-parser	`npx i18next-parser`	从代码中提取键
ICU 检查	@formatjs/cli	`npx formatjs extract`	验证 ICU 消息

决策树：库选择

项目需求：
    │
    ├─ React/Next.js 项目？
    │   ├─ ICU 优先的消息目录 + FormatJS 工具链？
    │   │   └─ react-intl（FormatJS）
    │   │
    │   ├─ 灵活性、插件、懒加载？
    │   │   └─ react-i18next
    │   │
    │   ├─ 捆绑包大小关键？
    │   │   └─ LinguiJS（ICU 语法）
    │   │
    │   └─ TypeScript 优先，编译时安全？
    │       └─ typesafe-i18n
    │
    ├─ Vue/Nuxt 项目？
    │   └─ vue-i18n（Composition API）
    │
    ├─ Angular 项目？
    │   ├─ 内置解决方案优先？
    │   │   └─ @angular/localize（官方，AOT 支持）
    │   │
    │   └─ 需要 i18next 生态系统？
    │       └─ angular-i18next（包装器）
    │
    └─ 框架无关 / Node.js？
        └─ i18next 核心（通用）

库比较

库	ICU 支持	懒加载	TypeScript	最适合
react-i18next	插件/可选	原生	良好	灵活，流行的 React 选择
react-intl	原生	手动	良好	ICU 优先的目录 + 工具链
LinguiJS	原生	原生	优秀	捆绑包敏感的应用
typesafe-i18n	有限	手动	优秀	编译时键安全
vue-i18n	原生	原生	良好	Vue 3 应用
@angular/localize	原生	AOT	原生	Angular 应用

核心概念

字符编码（关键）

始终使用 UTF-8 贯穿整个技术栈以防止文本损坏：

必过要求：UTF-8 无处不在
- 数据库：utf8mb4（MySQL）或 UTF-8（PostgreSQL）
- HTML：<meta charset="UTF-8">
- HTTP 头部：Content-Type: text/html; charset=utf-8
- 文件编码：将所有源文件保存为 UTF-8
- API 响应：JSON 使用 UTF-8 编码

UTF-8 支持所有 Unicode 字符，包括表情符号、数学符号和所有语言脚本。编码不一致会导致：损坏字符（�）、带重音名字的搜索失败以及国际输入被拒绝。

翻译键模式

// 扁平键（简单）
"welcome": "欢迎使用我们的应用"
"user.greeting": "你好，{name}"

// 嵌套键（组织化）
{
  "user": {
    "greeting": "你好，{name}",
    "profile": {
      "title": "您的个人资料"
    }
  }
}

// 命名空间分离（可扩展）
// common.json、auth.json、dashboard.json

ICU 消息格式要点

// 简单插值
"你好，{name}！"

// 复数化
"{count, plural, one {# 项} other {# 项}}"

// 选择（性别、类别）
"{gender, select, male {他} female {她} other {他们}} 喜欢了你的帖子"

// 数字格式化
"价格：{price, number, currency}"

// 日期格式化
"发布于：{date, date, medium}"

本地检测策略

优先级顺序：
1. 用户偏好（存储在个人资料/localStorage 中）
2. URL 参数或路径（/en/about，?lang=de）
3. Cookie（NEXT_LOCALE、i18next）
4. Accept-Language 头部
5. 默认本地回退

references/framework-guides.md - React、Vue、Angular、Next.js 实现
references/icu-message-format.md - 复数化、选择、格式化
references/translation-workflows.md - TMS、CI/CD、字符串提取
references/rtl-support.md - 从右到左语言支持
references/locale-handling.md - 日期、数字、货币

模板（生产级入门）

assets/react-i18next-setup.md - React + i18next 完整设置
assets/vue-i18n-setup.md - Vue 3 + vue-i18n 设置
assets/nextjs-i18n-setup.md - Next.js App Router i18n 设置

数据

data/sources.json - 60+ 精选外部参考

常见模式

命名空间组织

locales/
├── en/
│   ├── common.json      # 共享：按钮、错误、导航
│   ├── auth.json        # 登录、注册、密码
│   ├── dashboard.json   # 仪表板特定
│   └── validation.json  # 表单验证消息
├── de/
│   └── ...（相同结构）
└── ar/
    └── ...（相同结构）

懒加载（性能）

// i18next：按需加载命名空间
i18n.loadNamespaces('dashboard').then(() => {
  // 仪表板翻译现在可用
});

// React Suspense 集成
<Suspense fallback={<加载中 />}>
  <仪表板 />
</Suspense>

TypeScript 集成

// resources.d.ts - 类型安全的键
import common from './locales/en/common.json';

declare module 'i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common';
    resources: {
      common: typeof common;
    };
  }
}

// 现在 t('不存在') 会显示 TypeScript 错误

避免的反模式

反模式	问题	修复
硬编码字符串	不可翻译	提取所有面向用户的文本
字符串拼接	破坏翻译上下文	使用插值 `{name}`
手动复数化	对许多语言错误	使用 ICU 复数规则
内联样式用于 RTL	不具扩展性	使用 CSS 逻辑属性
仅在 URL 中存储本地	导航时丢失	同时持久化到 cookie/存储
无回退本地	缺失键显示空白文本	始终设置 `fallbackLng`
提前加载所有本地	初始加载慢	按命名空间/本地懒加载

操作清单

初始设置

必需：基于决策树选择 i18n 库
必需：设置翻译目录结构
必需：配置回退本地链
必需：设置本地检测策略
必需：为翻译键添加 TypeScript 类型
必需：为命名空间配置懒加载

翻译工作流

必需：设置字符串提取（i18next-parser、formatjs、Lingui）
必需：需要时集成 TMS（Phrase、Lokalise、Crowdin、Locize）
必需：配置 CI/CD 进行翻译同步
必需：设置翻译审查流程（词汇表 + 风格指南 + QA 门控）
必需：在开发中添加缺失键检测

RTL 支持

必需：使用 CSS 逻辑属性（margin-inline-start）
必需：为 RTL 本地设置 dir="rtl"
必需：使用真实 RTL 内容测试（阿拉伯语、希伯来语）
必需：处理混合字符串中的双向文本（BiDi）
必需：适当镜像方向性图标和图像

测试

必需：测试复数化，使用 0、1、2、5、21（语言特定）
必需：测试每个本地的日期/数字/货币格式化
必需：测试关键屏幕/组件中的 RTL 布局
必需：测试缺失翻译键处理（仅开发警告）
必需：测试本地切换和持久化（cookie/存储/url）

货币检查协议

当推荐库、版本或工具时，验证目标生态系统和项目约束下的当前状态。优先使用包注册表和发布说明，而非过时的硬编码数字。

包版本（Node/npm）

npm view i18next version
npm view react-i18next version
npm view react-intl version
npm view vue-i18n version
npm view next-intl version
npm view @angular/localize version
npm view @lingui/core version
npm view typesafe-i18n version

“X 是否仍推荐？”检查

检查项目的最后发布日期、开放问题和维护活动（GitHub 发布/问题）。
检查框架兼容性（Next.js App Router/RSC、React 19、Vue 3、Angular 当前主版本）。
对于捆绑包担忧，在实际应用中用捆绑包分析器测量，而不是依赖发布的大小声明。

软件本地化 software-localisation