software-localisation

软件本地化

将此技能用于生产级 Web 应用的 i18n 和 l10n：库的选择、消息目录、ICU 用法、区域设置路由、翻译工作流、RTL 支持和发布门槛。目标不只是翻译字符串，而是确保产品行为适合不同区域设置。

何时使用此技能

• 在 React、Vue、Angular 或 Next.js 中设置或调试 i18n
• 选择库和目录策略
• 实现 ICU 复数规则、格式化和区域设置检测
• 添加 RTL 支持
• 配置提取、翻译工作流或 TMS 集成
• 修复翻译缺失、语言混杂回归问题或不当的区域设置回退行为
• 向本地化的 Web 或原生客户端交付后端生成的文案（AI 摘要、叙述文本）

转到其他技能

• 通用前端架构 -> software-frontend
• 国际 SEO 和 hreflang -> marketing-seo
• 跨文化 UX 和市场适配 -> software-ui-ux-design 或 marketing-geo-localization
• 通用 WCAG/ARIA 合规性和《欧洲无障碍法案》(EAA) 准备 -> software-accessibility；此技能仅涉及 i18n 特定部分（lang/dir 传递、适应文字系统的行高、IME），详见 references/accessibility-i18n.md

何时不使用此技能

• 产品只有一个区域设置，且没有增加更多区域设置的既定计划——不要“以防万一”而预先构建 ICU 目录、TMS 集成或区域设置路由。使用普通字符串发布，等第二种区域设置成为现实需求时再处理。
• 用户只是要求“翻译这段文字”，不涉及代码、目录或产品界面——这是翻译任务，而不是本地化工程任务；直接翻译即可。
• 用户询问的是国际 SEO 结构（hreflang、ccTLD 与子目录的选择），不涉及 i18n 实现 -> 改为转到 marketing-seo。

原生移动端边界

此技能负责原生应用和 Web 应用中的字符串、复数形式、目录和翻译流程，也包括后端生成的文案以及目录键值对一致性：参见 references/backend-generated-content-i18n.md。此处的框架设置以 Web 为主；平台 API 归属 software-ios-native、software-android-native 或 software-mobile。请检查这些技能中的要点：

• iOS：字符串目录（Localizable.xcstrings）；通过编辑器的“按复数形式变化”设置复数形式，该设置会添加每种语言的 CLDR 复数形式。
• Android：通过 AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(...))（向后兼容）或 LocaleManager 设置应用级语言偏好（Android 13 / API 33+）；使用 android:localeConfig 声明区域设置，或使用 androidResources { generateLocaleConfig = true }（AGP 8.1+）。

---

工作流

1. 确认框架、区域设置数量、路由策略和翻译工作流。
2. 选择库和目录模型。
3. 将显式路由解析与首次进入时的区域设置协商及持久化分开定义。
4. 正确实现 ICU 或等效的消息格式化。
5. 添加提取、缺失键和过期翻译的控制（缺失键检测）；对于 LLM/MT 草稿，请执行 references/translation-workflows.md 中的 ICU-AST、术语表、质量评估和审核门槛。
6. 在需要时添加 RTL 支持和视觉回归测试；伪本地化、RTL 自动化和复数边界测试模式请参见 references/testing-i18n.md。
7. 对可编入索引或面向客户的路由，若存在语言混杂或不安全的回退行为，则阻止发布。

快速参考

场景	库	原因
React / TypeScript，注重通用灵活性	i18next + react-i18next	启用后支持选择器类型；插件集成
目录优先采用 ICU，且已在使用 FormatJS 工具	react-intl	ICU 目录支持通过 FormatJS 提取和编译
Next.js App Router	next-intl	专为 RSC + App Router 构建；配置好的区域设置路由
Vue	vue-i18n	原生支持框架；与 Vue 工具集成
Angular	@angular/localize	构建时提取和 AOT 编译
需要控制较小的包体积	Lingui	宏提取；测量实际发布的包体积
团队明确需要生成类型包装器	typesafe-i18n	完整的键类型安全；维护成本较高

不要只看受欢迎程度来做选择。应根据路由模型、提取需求、ICU 使用预期和团队维护习惯来决定。各框架的设置步骤请参见 references/framework-guides.md。

ICU MessageFormat 2（MF2）：尚不适合作为默认选择

MF2 已在 Unicode 的 LDML 规范中完成语法层面的标准化（自 CLDR/LDML 47 起稳定，2025 年 3 月），因此很容易让人把它视为“新版 ICU”。在工具链跟上之前，不要将生产目录迁移到 MF2：确认 ICU 自身的实现是否已脱离草案／技术预览状态，你的库（react-intl/FormatJS、i18next、vue-i18n、Lingui）是否提供生产级 MF2 支持，以及你的 TMS 能否对其进行往返转换。继续使用 MessageFormat 1 / ICU 语法（文档见 references/icu-message-format.md），并在建议切换前重新检查采用情况——“规范已经定稿，所以使用它一定安全”是常见的误判。

---

核心规则

编码和内容模型

• 全程使用 UTF-8
• 不要拼接可翻译字符串
• 使用插值和 ICU 复数或选择规则，而不是临时格式化

区域设置路由和回退

• 对于当前请求，有效 URL 或深层链接中明确指定的区域设置优先；在导航和规范元数据中保留该设置（日期／数字／货币检测的具体说明请参见 references/locale-handling.md）
• 未明确指定区域设置时，依次根据已验证的偏好、已保存的选择、受支持的 Accept-Language，然后是默认区域设置进行协商
• 已保存的偏好可以将未指定区域设置的入口路由重定向，但不得静默改写共享的、明确指定区域设置的 URL
• 始终定义一个回退区域设置
• 不要在可编入索引的非英语路由上静默回退到英语
• 元数据、面包屑、JSON-LD 和可见文案必须使用相同的区域设置

翻译工作流

• 提取键，不要手动复制
• 保持命名空间结构稳定
• 添加译者上下文、术语表规则和审核关卡；提取／TMS／CI 流水线模式请参见 references/translation-workflows.md，翻译记忆库、术语表和规模化成本模式请参见 references/content-management-patterns.md
• 在 CI 中运行硬编码字符串检测和缺失键检查

RTL 和无障碍

• 使用 CSS 逻辑属性
• 在需要时设置 dir="rtl"
• 使用真实的 RTL 内容进行测试；阿拉伯语／希伯来语／波斯语的特定模式请参见 references/rtl-support.md
• 验证各区域设置下的双向文本处理、图标和屏幕阅读器行为

生产门禁

门禁	失败条件	补救措施
输出混用多种语言	任何按语言区域路由的页面都显示了其他语言区域的键	在合并前通过缺失键 CI 检查发现问题
缺失键泄漏	核心用户体验或营销路由显示键 ID 或原始回退字符串	在 CI 流水线中进行提取并与目录对比
发布流程中使用机器翻译	未经过术语表、语气规范或审核门禁，就插入机器翻译结果	为所有面向客户的语言区域添加人工审核步骤
切换语言区域后状态丢失或导航故障	用户切换语言区域后丢失购物车、表单或路由状态	集中管理语言区域状态；使其与路由／Cookie 分离
RTL 发布前未进行视觉验证	发布时阿拉伯语／希伯来语／波斯语布局损坏	发布前必须通过一个 RTL 语言区域的视觉检查
本地化导致无障碍访问回归	切换语言区域导致语言／方向标记、文字渲染或文本输入出现问题	测试 references/accessibility-i18n.md 中的国际化无障碍访问部分；将法律适用性问题交由无障碍访问负责人处理

已知陷阱

陷阱	预防措施
提取、TMS 和运行时之间的键不一致——回退“看似正常”，但语言区域已损坏	在 CI 中运行缺失键检查；发布前将提取结果与 TMS 目录进行对比
可见字符串已翻译，但验证消息／元数据／邮件／JSON-LD 仍为英文	在项目开始时列出所有语言区域涉及的内容（UI、邮件、SEO、法律文本）；将每项都视为单独的测试门禁
对语法敏感或有性别差异的文案使用字符串拼接	使用 ICU {count, plural, ...}／{gender, select, ...}（或库自带的复数语法，例如 vue-i18n 管道复数）；切勿使用 "Hello " + name
只测试拉丁字母语言区域	在标记为“完成”之前，必须测试一个长字符串语言区域（de/ru）和一个非拉丁文字语言区域（ja/ar）
语言区域分别保存在路由、Cookie 和客户端状态中，却没有优先级规则	分别制定解析规则：请求使用 URL／深层链接中明确指定的语言区域；否则依次使用已认证用户偏好 > 已保存的选择 > 受支持的 Accept-Language > 默认值
未使用术语表或审核就发布机器翻译	对所有面向客户的内容要求使用术语表、遵循语气规范并通过人工审核门禁
凭记忆假定复数类别数量（例如“法语和英语一样，只分 one/other”）	CLDR 会随时间修订各语言的类别数量（法语现在有 one, many, other）；请根据当前 CLDR 复数规则表进行核实，不要照搬之前项目中的硬编码规则
在没有 CSP／Trusted Types 的情况下，将翻译内容渲染为原始 HTML（v-html、dangerouslySetInnerHTML、ICU HTML 标签）	vue-i18n（CVE-2025-53892）和 Angular 的 i18n 流水线（CVE-2026-27970）中都存在针对这一具体模式的真实 XSS 安全公告——应将翻译文件的写入权限视为特权，并固定到已修补的库版本

常见反模式

反模式	正确做法
在按语言区域路由的页面上静默回退到英文	当非默认语言区域缺少键时，在 CI 或预览中明确报错
将业务逻辑编码进翻译键	键表示 UI 文本；业务逻辑应放在代码中
为方便开发者而拆分翻译	按稳定的产品领域和运行时加载边界进行拆分
为 RTL 在各视图中逐一修补 CSS 方向属性（left、right）	从一开始就使用 CSS 逻辑属性（inline-start、inline-end）
每个产品界面（营销、支持、产品）分别运行各自的语言区域逻辑	在一个共享的语言区域层中集中处理回退、格式化和检测

运维手册

对于大型语言区域目录或多语言混杂事件：

• 首先对比键
• 然后进行翻译
• 将营销和 SEO 的语言区域缺口视为发布阻断项
• 将大型语言区域文件拆分处理，而不是一次性读取

详细的分诊流程请参阅 references/ops-runbook.md。

导航

核心参考资料

• references/framework-guides.md
• references/icu-message-format.md
• references/translation-workflows.md
• references/rtl-support.md
• references/locale-handling.md
• references/testing-i18n.md
• references/accessibility-i18n.md
• references/content-management-patterns.md
• references/ops-runbook.md
• references/backend-generated-content-i18n.md — 面向本地化客户端的后端生成文案（按语言区域生成与缓存后翻译）、语言区域约定、原生目录一致性

模板和数据

• assets/react-i18next-setup.md
• assets/vue-i18n-setup.md
• assets/nextjs-i18n-setup.md
• data/sources.json

维护

• python3 scripts/check_urls.py
• python3 scripts/check_examples.py

相关技能

• software-frontend
• marketing-seo
• software-accessibility

经验总结循环

当以往的决策或陷阱与当前情况相关时，如果存在 learnings.consolidated.md，请查阅；仅在需要了解历史或它是现有的备用资料时，才使用 learnings.md。否则跳过两者。

应用这些经验后，如果你遇到了值得记住的模式、值得避免的错误，或令你意外的领域知识，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的项目符号。不要修改 SKILL.md 本身。