i18n-localization

i18n 本地化

使用此技能规划、审查或强化产品界面、文档、营销页面、电子邮件以及 Web／应用路由界面的本地化工作。

标准词汇

术语	含义
locale	语言及可选的地区惯例，例如 en、en-US 或 ar-EG
message catalog	翻译字符串及消息元数据的来源
ICU message	一种能够安全处理变量、复数、选择项和序数的消息格式
pseudo-locale	一种测试用 locale，会扩展并标记字符串，以暴露硬编码文本和布局截断问题
RTL	从右向左的布局方向，适用于阿拉伯语和希伯来语等语言
fallback	locale、键或翻译缺失时的预设处理方式

分派

$ARGUMENTS	模式	输出
空	本地化审计	检查当前界面，找出 locale 风险，并返回按优先级排列的整改计划。
应用、路由、功能或文件路径	实施计划	针对该范围梳理受影响的字符串、路由、格式化、QA 和发布检查。
locale 或市场列表	locale 就绪情况审查	验证语言、地区、格式化、路由、回退机制及翻译交接要求。
现有计划或差异	审查	检查遗漏的字符串、不安全的拼接、格式化错误、目录偏差、RTL 缺漏及测试缺失。
与本地化无关的自然语言	转介	说明范围边界，并转至更合适的技能。

用户未提供参数时，从审计相关代码库或产品界面的本地化情况开始。除非代码库和用户请求仍存在尚未解决的实际决策，否则不要询问 locale 偏好。

参考文件索引

文件	阅读时机
references/localization-checklist.md	规划、实施、审查、测试或发布本地化工作时

关键规则

1. 将本地化视为产品契约，而不是单纯的翻译流程。在范围内时，还要覆盖路由、格式化、无障碍、搜索元数据、分析标签、电子邮件和支持界面。
2. 绝不要拼接翻译片段来组成句子。使用完整消息和变量、ICU 选择／复数形式，或框架提供的等效消息格式。
3. 除非系统在该层已有目录抽象，否则不要将面向用户的字符串放进业务逻辑和共享常量中。
4. 日期、时间、数字、货币、列表、相对时间、单位和姓名均使用 locale 感知的格式化器。不要用字符串模板手动实现格式化。
5. 将语言与地区分开处理。en、en-US 和 en-GB 可能对应不同的文案、日期、货币、计量单位和法律内容。
6. 明确规定回退行为。开发环境中，缺失的翻译应明确报错；生产环境中，应采用有意设计的降级方式。
7. 检查 pseudo-locale，验证文本扩展、重音符号、括号标记、插值安全性和截断情况。
8. 如果用户内容中可能出现阿拉伯语、希伯来语、波斯语、乌尔都语或混合方向文本，则检查 RTL 和双向文本。
9. 保持消息键稳定。除非源消息的含义发生变化，否则不要大幅改动目录，也不要使翻译记忆失效。
10. 避免让译者接触代码语法。提供备注、截图、变量说明、字符限制和产品背景。

工作流

1. 界定范围

确定请求影响的界面：

• UI 组件、服务端渲染页面、原生屏幕、电子邮件、PDF、文档、通知、错误状态、空状态和事务性文案。
• 路由结构、语言区域协商、重定向、规范 URL、hreflang、站点地图条目，以及持久化的用户语言区域偏好。
• 数据驱动的内容、CMS 字段、Markdown／文档内容、法律文本、定价、计量单位和特定市场的可用性。

如果请求涉及实现工作，请先阅读现有的 i18n 库、路由惯例、目录格式和测试模式，再提出更改方案。

2. 提取并建模消息

对于每个包含字符串的界面：

• 将面向用户的字符串移入现有目录或消息层。
• 使用带有命名变量的完整句子消息。
• 使用 ICU 风格的变体或框架原生等效方式，建模复数、选择、性别、序数和依赖数量的文本。
• 为含义模糊的标签、产品术语、占位符和变量添加译者说明。
• 使用与语义含义稳定绑定的键，而不要只依据英文措辞命名。

除非它们嵌套在稳定的功能命名空间下，否则应避免使用 title、subtitle 或 buttonText 等通用键。

3. 本地化格式

检查所有受语言区域影响的值：

• 日期、时间、时区、相对时间和日历假设。
• 数字、小数、百分比、货币、会计格式、紧凑记数法和单位格式。
• 列表、姓名、地址、电话号码、邮政编码、排序、大小写和搜索规范化。
• 表单验证、解析、掩码，以及服务端／客户端往返行为。

优先使用 Intl.* 等平台格式化器、框架辅助工具或经过审核的库 API。

4. 路由与持久化语言区域

核实：

• 应用如何选择语言区域：URL 前缀、域名、账户设置、Cookie、浏览器语言或显式选择器。
• 重定向是否具有确定性且可安全缓存。
• 规范 URL、备用链接、元数据、Open Graph、站点地图、robots 规则和文档导航是否符合语言区域策略。
• API、后台任务和电子邮件是否与可见应用使用相同的语言区域上下文。

除非产品已将语言区域协商与身份验证或计费策略耦合，否则不要将两者混在一起。

5. 测试与 QA

至少建议或添加以下检查：

• 目录完整性和未使用键检测。
• 缺失的插值变量。
• 伪语言区域渲染。
• 对扩展字符串和相关 RTL 布局进行快照或视觉覆盖。
• 针对具有代表性的语言区域进行格式化测试，至少包含一个非美国语言区域。
• 检查无障碍支持，包括语言属性、方向、屏幕阅读器标签和已翻译的 aria 文本。

对于审查任务，请说明现有测试能证明什么，以及哪些内容仍需视觉或译者 QA。

渐进式披露

• 从本 SKILL.md 开始，了解路由、硬性规则和输出格式。
• 仅在规划、审查或发布具体的本地化工作时，才阅读 references/localization-checklist.md。
• 不要预加载无关的前端、SEO、文案或 JavaScript 指南。
• 引入新工具前，先使用项目现有的 i18n 库和目录格式。

输出格式

返回简洁且面向实现的内容：

• 发现：用于审计和审查，按严重程度排序，并注明文件或路由。
• 计划：用于实现请求，按依赖顺序排列：路由／目录基础、字符串提取、格式化、QA、发布。
• 验收标准：在相关时，包含目录完整性、伪语言区域、格式化、回退以及路由／SEO 检查。
• 待解决问题：仅列出无法依据代码库或用户请求确定的未决选择。

除非用户明确要求润色文案，否则不要改写营销文案。除非本地化暴露出明确的布局或方向性缺陷，否则不要进行一般性的前端改版。

验证约定

在宣布更改完成前，从此技能目录运行：

python scripts/check.py

完成标准：

1. scripts/check.py 以退出码 0 结束。
2. 此技能目录下不再存在可移植 CLI 违规项。
3. 对分发规则表进行冒烟审查，覆盖空提示词、明确提示词、隐式提示词和负向对照提示词。