# 软件本地化 - 快速参考现代 Web 应用程序中国际化 (i18n) 和本地化 (l10n) 的生产模式。涵盖库选择、翻译管理、ICU 消息格式、RTL 支持和 CI/CD 工作流程。 **快照 (2026-02)**：i18next 25.x、react-i18next 16.x、react-intl 8.x、vue-i18n 11.x、next-intl 4.x、@angular/localize 21.x。始终验证目标存储库中的当前版本（请参阅货币检查协议）。 **权威参考文献**： * [i18next 文档]() * [FormatJS/react-intl]() * [ICU消息格式]() * [MDN 国际 API]() ## 快速参考任务|工具/库 |命令 |何时使用 ---|---|---|--- 反应 i18n |反应-i18next | `npm i i18next 反应-i18next` |大多数 React 应用程序，灵活性 React i18n (ICU) |反应国际（FormatJS）| `npm 我反应国际` | ICU-优先消息目录+工具 Vue i18n | vue-i18n | `npm 我 vue-i18n` | Vue 3 应用程序角度 i18n | @角度/本地化 | `ng 添加 @Angular/localize` |角度应用程序 Next.js 国际化 |下一个国际 | `npm i next-intl` | Next.js 应用程序路由器最小捆绑 |临桂JS | `npm 我@lingui/core @lingui/react` |捆绑尺寸至关重要类型安全 |类型安全-i18n | `npm i typesafe-i18n` | TypeScript 优先的项目字符串提取 | i18next 解析器 | `npx i18next-解析器` |从代码中提取密钥 ICU 棉绒 | @formatjs/cli | `npx 格式提取` |验证 ICU 消息 ## 决策树：库选择项目要求： │ ├─ React/Next.js 项目？ │ ├─ ICU优先消息目录+FormatJS工具？ │ │ └─react-intl (FormatJS) │ │ │ ├─ 灵活性、插件、延迟加载？ │ │ └─react-i18next │ │ │ ├─ 捆绑包大小很重要吗？ │ │ └─ LinguiJS（ICU语法） │ │ │ └─ TypeScript优先，编译时安全？ │ └─ typesafe-i18n │ ├─ Vue/Nuxt 项目？ │ └─ vue-i18n（组合 API） │ ├─ Angular 项目？ │ ├─ 首选内置解决方案？ │ │ └─ @angular/localize（第一方，AOT 支持） │ │ │ └─ 需要i18next生态系统吗？ │ └─ Angular-i18next（包装器） │ └─ 与框架无关/Node.js？ └─ i18next 核心（随处可用） ## 库比较图书馆 |重症监护室支持 |延迟加载 |打字稿 |最适合 ---|---|---|---|--- 反应-i18next |插件/可选 |本地 |好 |灵活、流行的 React 选择反应国际 |本地 |手册|好 | ICU优先目录+工具临桂JS |本地 |本地 |优秀|具有捆绑意识的应用程序类型安全-i18n |有限公司|手册|优秀|编译时关键安全 vue-i18n |本地 |本地 |好 | Vue 3 应用程序 @角度/本地化 |本地 |奥特|本地 |角度应用程序 ## 核心概念 ### 字符编码（关键） **始终在整个堆栈中使用 UTF-8** 以防止文本损坏：所需 PASS：UTF-8 无处不在 - 数据库：utf8mb4 (MySQL) 或 UTF-8 (PostgreSQL) - HTML: - HTTP 标头：内容类型：text/html；字符集=utf-8 - 文件编码：将所有源文件保存为UTF-8 - API 响应：采用 UTF-8 编码的 JSON UTF-8 支持所有 Unicode 字符，包括表情符号、数学符号和所有语言脚本。编码不一致会导致：字符损坏 (�)、重音名称搜索失败以及国际输入被拒绝。 ### 翻译关键模式 // 平键（简单） "welcome": "欢迎使用我们的应用程序" "user.greeting": "你好，{name}" // 嵌套键（有组织的） { “用户”：{ "greeting": "你好，{name}", “个人资料”：{ “标题”：“您的个人资料” } } } // 命名空间分离（可扩展） // common.json、auth.json、dashboard.json ### ICU 消息格式要点 // 简单插值 “你好，{名字}！” // 复数 “{计数，复数，一项 {# 项} 其他 {# 项}}” // 选择（性别、类别） “{性别，选择，男{He}女{她}其他{他们}}喜欢您的帖子” // 数字格式 “价格：{价格、数量、货币}” // 日期格式 “发布时间：{日期、日期、媒体}” ### 区域设置检测策略优先顺序： 1.用户偏好（存储在profile/localStorage中） 2. URL参数或路径（/en/about、?lang=de） 3. Cookie（NEXT_LOCALE、i18next） 4. Accept-Language 标头 5. 默认语言环境后备 ## 区域设置质量门（SEO/AEO 安全）将这些门用于区域设置路由、可索引页面（例如“/vi/*”、“/de/*”）： * 不要在单一区域设置路线上传送混合语言内容。 * 不要默默地退回到英语以获取可索引的页面内容。 * 将元数据、面包屑和 JSON-LD 保留在与可见内容相同的区域设置中。 * 优先选择 CI 中的显式缺失键处理，而不是生产 SEO 页面中的运行时回退。 * 如果回退不可避免，请使用区域设置安全的中性副本并跟踪丢失的键。 ### 缺少翻译决策规则 * 营销/SEO 页面：阻止发布或替换为区域设置安全的副本；切勿注入英文片段。 * 产品 UI（非索引表面）：通过遥测和后续修复可以接受回退。 ## EN/RU 混合语言回归协议当用户报告区域设置混合时使用此选项（例如显示 EN 片段的 RU 屏幕）。 ### 1) 键奇偶校验差异（基础与目标区域设置）比较源语言环境文件和目标语言环境文件之间的键集；将丢失的键视为面向用户的页面上的释放阻止程序。 jq -r '路径（标量）|加入（“。”）'app/src/messages/en/*.json |排序 -u > /tmp/en.keys jq -r '路径（标量）|加入（“。”）'app/src/messages/ru/*.json |排序 -u > /tmp/ru.keys comm -23 /tmp/en.keys /tmp/ru.keys # EN 中存在，RU 中缺失 ### 2) UI 中的硬编码字符串扫描在应使用 i18n 键的组件/页面中搜索用户可见的文字。 rg -n '>[A-Za-z][^<]{2,}<' app/src -g '*.tsx' rg -n '"[A-Za-z][^"]{2,}"' app/src -g '*.tsx' -g '*.ts' ### 3) 路由级别区域烟雾检查对于目标区域设置路由，请验证呈现的文本是否一致本地化，并且关键 UI 区域中没有出现后备 EN 片段。 ### 4) 引擎文本审核确保计算/引擎驱动的消息（不仅仅是静态标签）通过翻译映射，而不是返回原始 EN 字符串。 ### 5) CI 门添加一个轻量级门，该门在以下情况下会失败： * 缺少所需的目标区域设置键， * 新添加的 UI 文字绕过 i18n 层， * 区域设置路由的烟雾页面包括混合语言哨兵术语。 ### 运行时约束注意事项如果代理运行时没有外部翻译连接器，请勿阻止自动翻译工具。实施关键完整性+占位符策略，然后在单独的跟踪通道中回填已批准的翻译。 ## 引擎输出 i18n（`_i18n` 元数据模式）服务器生成的引擎内容（占星计算、ML 输出、计算报告）需要本地化，而不需要使引擎能够感知区域设置。 ### 模式 * 引擎在英文字符串旁边附加 `_i18n: { key: "transits.neptune_trine.description", params: {planet: "Neptune" } }` * 客户端解析：`_i18n ? t(_i18n.key, _i18n.params) : englishFallback` * 向后兼容：没有 `_i18n` 的旧缓存响应优雅地降级为英语 * 服务器缓存一次；每个区域设置都在客户端上解析 * 在“t(key)”之前使用“t.has(key)”以实现优雅的回退图案|状态 |为什么 ---|---|--- `{ text: "海王星三分木星", _i18n: { key: "transits.neptune_trine", params: { p1: "海王星", p2: "木星" } } }` |通过 |客户端根据区域设置进行解析；服务器缓存一次 `{ text_en: "...", text_ru: "...", text_de: "..." }` |失败 |服务器膨胀，每个区域的缓存 `t(含义.主题)` |失败 |使用原始引擎输出作为翻译密钥 `t.has('含义.4.主题') ? t('meanings.4.theme') : 含义.theme` |通过 |密钥丢失时的优雅回退 ## 语言环境键设计反模式 ### “1 个字段，N 个槽位” 将一个区域设置键用于多种不同的 UI 目的。每个 UI 槽（徽章、卡片标题、模式描述、肯定）都需要自己的语义上不同的键，即使英文文本恰好相似。图案|状态 |为什么 ---|---|--- `meanings.4.advice` 用于业债、人生道路、生日指导和高级周期（同文 6x）|失败 |当任何插槽需要不同的平移时，耦合就会断裂 `意义.4.建议`、`业力债务.4.lifeLesson`、`lifePath.4.肯定`、`生日.4.指导` |通过 |每个插槽有不同的键 - 独立翻译 ### 短变体与长变体从一开始就为两者做好计划。图案|状态 |为什么 ---|---|--- `nodeGrowth`（完整：“北交点 — 增长和新的开始”）+ `nodeGrowthShort`（徽章：“增长”）|通过 |每个 UI 上下文都有适当的长度单个“nodeGrowth”键对于徽章 UI 来说太长，需要子字符串破解 |失败 |非英语语言环境中的子字符串中断 ### 字符串转换上的静态键映射当 API 输出格式与区域设置键命名不匹配时，请使用硬编码映射而不是字符串操作。 // PASS：显式映射——处理所有边缘情况 const PHASE_TO_KEY：记录<字符串，字符串> = { "New Moon": "新", "Waxing Crescent": "washingCrescent", “第一季度”：“第一季度”，“满月”：“满” }; // 失败：字符串转换 — 在“New Moon”→“newMoon”与实际键“new”上中断 const key = PhaseName.replace(/\s+/g, '').replace(/^./, c => c.toLowerCase()); ## 机器翻译质量关卡简短的、特定领域的术语会妨碍自动机器翻译。已知的例子：语言环境 |预计 | MT 输出 |期限 ---|---|---|--- 阿拉伯语 | `¡¡¡`（地球作为元素） | `??????（耳朵）| “地球” 日语 | `火`（火作为元素）| `枞`（枞树）| “火” 印地语 | `भू`（地球）| `कान`（耳朵）| “地球” ### 规则 1. 维护每个区域的领域术语（星座、元素、行星名称、天文术语）的精选词典 2. 在没有查字典的情况下，切勿自动翻译少于 3 个单词的术语 3. 机器翻译后审核：grep 查找已知的错误翻译（按语言环境编译阻止列表） 4. 对于新语言环境，首先翻译领域术语，然后将其用作 MT 的术语表约束 ## 语言环境传播协议添加 EN 键的每个提交都必须传播到所有目标区域设置。这是#1 重复出现的 i18n bug — 在 4 个以上的独立会话中出现。 ### 步骤 1. **提交之前**：将 EN 语言环境文件与目标语言环境进行比较以查找缺少的键 2. **基于脚本的传播**：将缺少的键从 EN 注入到具有 EN 后备值的所有其他语言环境中 3. **CI gateway** ：当目标语言环境文件的键数少于 EN（可配置阈值）时，构建失败 4. **预提交挂钩**（可选）：在暂存的语言环境文件上自动运行传播脚本 ### 快速密钥奇偶校验 jq -r '路径（标量）| join(".")' messages/en/*.json |排序 -u > /tmp/en.keys 对于 ard de es fr hi it ja ko pt-BR ru tr vi zh 中的区域设置；做 jq -r '路径（标量）| join(".")' messages/$locale/*.json |排序 -u > /tmp/$locale.keys echo "=== $locale 缺失 === 通讯 -23 /tmp/en.keys /tmp/$locale.keys |头-20 完成 ### 批量翻译方法首先找到所有差距（基于差异），然后逐个文件进行系统翻译。一次一个发现比批处理慢 5 倍： 1. 在所有语言环境中运行密钥奇偶校验以生成完整的间隙列表 2. 按名称空间/文件对丢失的键进行分组 3. 使用现有翻译作为词汇表上下文，一次为每个语言环境翻译一个文件 4. 批次完成后验证奇偶校验 ## 重复 JSON 键检测大型手动编辑的 JSON 语言环境文件可能具有重复的键。根据 JSON 规范，最后编写者获胜——密钥会被悄悄丢弃。 ### CI 检查 # 检测 JSON 语言环境文件中的重复键节点-e“ const fs = require('fs'); const 文件 = process.argv[1]; const text = fs.readFileSync(file, 'utf8'); 常量键 = []; JSON.parse(text, (key, value) => { if (key)keys.push(key); 返回值; }); const dupes =keys.filter((k, i) =>keys.indexOf(k) !== i); if (dupes.length) { console.error('重复键', file, ':', [...new Set(dupes)]);进程.退出(1); } ” “$文件” 在 CI 中的每个语言环境文件上运行此命令，以在静默按键冲突到达生产环境之前捕获它们。 ## 导航 ### 资源（深入探讨） * [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]() \- 日期、数字、货币 * [references/testing-i18n.md]() \- 伪本地化、视觉回归、复数测试、缺失翻译 CI 检测 * [references/accessibility-i18n.md]() \- 跨语言的屏幕阅读器、多语言环境中的 ARIA、BiDi 可访问性、IME * [references/content-management-patterns.md]() \- 翻译记忆库、术语表、译者上下文、MTPE 工作流程、成本优化 ### 模板（生产启动器） * [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+ 精选外部参考 ### 相关技能 * [../software-frontend/SKILL.md]() \- 前端架构模式（React、Vue、Angular、Next.js） * [../marketing-seo-complete/SKILL.md]() \- Hreflang，国际 SEO ## 常见模式 ### 命名空间组织语言环境/ ├── zh/ │ ├── common.json # 共享：按钮、错误、导航 │ ├── auth.json # 登录、注册、密码 │ ├── dashboard.json # 仪表板特定 │ └──validation.json # 表单验证消息 ├── 德/ │ └── ...（结构相同） └── ar/ └── ...（结构相同） ### 延迟加载（性能） // i18next：按需加载命名空间 i18n.loadNamespaces('仪表板').then(() => { // 仪表板翻译现已可用 }); // React Suspense 集成 <暂停后备={<加载/>}> <仪表板/> ### TypeScript 集成 // resources.d.ts - 类型安全密钥从 './locales/en/common.json' 导入通用；声明模块'i18next'{ 接口自定义类型选项{ defaultNS: '通用'; 资源：{ 常见：常见类型； }; } } // 现在 t('nonexistent') 显示 TypeScript 错误 ## 要避免的反模式反模式 |问题 |修复 ---|---|--- 硬编码字符串 |不可翻译 |提取所有面向用户的文本字符串连接 |打破翻译上下文 |使用插值 `{name}` 手动复数 |对于许多语言来说都是错误的 |使用 ICU 复数规则 RTL 的内联样式 |无法扩展 |使用 CSS 逻辑属性仅在 URL 中存储区域设置 |迷失导航 |也坚持到cookie/存储没有后备区域设置 |缺少按键的空白文本 |始终设置 `fallbackLng` 可索引非英语页面上的无声英语后备 |混合语言输出会损害用户体验，并可能削弱区域 SEO/AEO 质量 |使用区域设置安全的副本或在可索引路由的缺失键上构建失败预先加载所有语言环境 |初始加载缓慢|每个命名空间/区域设置的延迟加载 ## 操作清单 ### 初始设置 * 必需：根据决策树选择 i18n 库 * 必需：设置翻译的目录结构 * 必需：配置后备语言环境链 * 必需：设置区域设置检测策略 * 必需：为翻译键添加 TypeScript 类型 * 必需：为命名空间配置延迟加载 ### 翻译工作流程 * 必需：设置字符串提取（i18next-parser、formatjs、Lingui） * 必需：在需要时与 TMS 集成（Phrase、Lokalise、Crowdin、Locize） * 必需：配置 CI/CD 进行翻译同步 * 必需：设置翻译审核流程（术语表 + 风格指南 + QA 门） * 必需：在开发中添加缺失键检测 * 必需：为区域设置路由页面添加硬编码字符串检测 * 必需：验证元数据 + JSON-LD 区域设置与可见内容的奇偶性 * 必需：为高意图页面上的混合语言回归添加区域设置 QA ### i18n 密钥验证（每次更改门）添加新的 `t()` / `useTranslations()` 调用或新的消息键时： 1. 验证基本语言环境文件中是否存在密钥（例如“messages/en/*.json”）。 2. 在代码中使用密钥之前，将其添加到基本语言环境文件中。 3. 对于多区域设置项目，在所有区域设置文件中添加占位符条目或确认后备链能够正常处理丢失的键。 4. 在提交之前运行项目的缺失键检测（例如，“npm run build”或“next-intl”编译检查）。缺少 i18n 键会导致本地化页面上出现空白文本或后备语言渗色，这是一种无声的、面向用户的回归。 ### RTL 支持 * 必需：使用 CSS 逻辑属性 (margin-inline-start) * 必需：为 RTL 语言环境设置 `dir="rtl"` * 必需：使用真实的 RTL 内容进行测试（阿拉伯语、希伯来语） * 必需：处理混合字符串中的双向文本 (BiDi) * 必需：在适当的情况下镜像方向图标和图像 ### 测试 * 必需：使用 0、1、2、5、21 测试复数（特定于语言） * 必需：测试每个区域设置的日期/数字/货币格式 * 必需：测试关键屏幕/组件中的 RTL 布局 * 必需：测试缺少翻译键的处理（仅限开发人员的警告） * 必需：测试区域设置切换和持久性（cookie/存储/url） ## 货币检查协议在推荐库、版本或工具时，请验证目标生态系统和项目限制的最新内容。与过时的硬编码数字相比，更喜欢软件包注册表和发行说明。 ### 包版本（Node/npm） npm 查看 i18next 版本 npm 查看react-i18next版本 npm 查看react-intl版本 npm 查看 vue-i18n 版本 npm 查看下一个国际版本 npm 查看@angular/localize 版本 npm 查看@lingui/core 版本 npm 查看 typesafe-i18n 版本 ###“X还推荐吗？”检查 * 检查项目的最后发布日期、未解决的问题和维护活动（GitHub 版本/问题）。 * 检查框架兼容性（Next.js App Router/RSC、React 19、Vue 3、Angular 当前主要版本）。 * 对于捆绑问题，请使用捆绑分析器在真实应用程序中进行测量，而不是依赖已发布的尺寸声明。 ## Ops Runbook：大型区域设置目录（法学硕士安全）当区域设置目录对于单次读取而言太大、出现混合语言 UI 或报告缺少键时，请使用此选项。 ### 90 秒分类 # 1) 确认语言环境文件布局 rg --files src/messages | rg --files src/messages |排序 # 2) 读取前检测超大目录 wc -l src/messages/en/*.json src/messages/*/*.json |排序-nr |头 # 3) 大文件的块读取（避免工具限制） sed -n '1,200p' src/messages/en/landing.json sed -n '201,400p' src/messages/en/landing.json ### 键奇偶校验（基础与目标区域设置）基=en 目标=ru jq -r '路径（标量）|加入（“。”）' src/messages/$BASE/*.json |排序 -u > /tmp/$BASE.keys jq -r '路径（标量）|加入（“。”）' src/messages/$TARGET/*.json |排序 -u > /tmp/$TARGET.keys # 目标缺失通讯 -23 /tmp/$BASE.keys /tmp/$TARGET.keys # 目标中的额外内容通讯 -13 /tmp/$BASE.keys /tmp/$TARGET.keys ### 硬编码的 UI 字符串扫描 # TSX/TS 硬编码文字（快速启发式） rg -n --pcre2 '"[A-Za-z][^"\n]{2,}"' src --glob '*.tsx' --glob '*.ts' # JSX 文本节点 rg -n --pcre2 '>[A-Za-z][^<]{2,}<' src --glob '*.tsx' ### CI 门模式（无混合语言） # 如果出现已知的缺失密钥哨兵，则构建失败 rg -n '__MISSING_I18N__|TODO_TRANSLATE' src/messages && 退出 1 ||真实 # 可选：阻止本地化、可索引路由上的英语回退 rg -n 'fallback.*en|defaultLocale.*en' src/app src/lib ### 操作规则 * 切勿一次性读取大型语言环境文件；总是块。 * 首先使用密钥差异，其次使用翻译过程。 * 将营销/SEO 区域设置关键差距视为发布障碍。 * 如果没有跟踪审阅通过，请勿自动插入机器翻译。

软件本地化

包含技能