i18n 技能的目标是让应用在任意语言和地区下正确工作,使后续新增语言变成翻译工作而非重构。它要求优先使用平台自带的本地化与格式化 API,而不是在其上再封装自定义框架。
使用方式上,技能根据请求判断模式,不额外询问:构建模式指任务本身要创建或修改 UI 或格式化代码,此时将规则作为编写约束并仅在规则改变决策时用一行说明;采纳模式指用户要求对整个应用做国际化、翻译准备或修复 i18n 问题,按清单执行。除非被要求,不会新增语言;让字符串可本地化与添加翻译是两件独立的事。
平台检测方面,读取清单文件并只加载匹配的指南:Web/JS/TS 通过 package.json 加载 references/js.md;Apple 平台通过 *.xcodeproj 或含应用目标的 Package.swift 加载 references/apple.md;Android 通过 build.gradle(.kts) 加载 references/android.md。若项目已使用 next-intl、react-i18next、vue-i18n、FormatJS 等 i18n 库,则保留并按既有约定处理;React Native/Expo 的字符串与格式化走 js 指南;其他技术栈用该平台的 ICU/CLDR 相关 API 应用规则。
规则按影响分级:可本地化字符串(关键,覆盖所有面向用户的字符串、复数与插值)、时区与时间戳(关键,覆盖存储事件、历史、时间线与日程)、区域感知格式化(高,日期、时间、数字、百分比、货币、时长)、单位与度量(高,距离、速度、重量、温度)、文本与布局(高,用户生成文本、布局、RTL、长翻译)、确定性测试(中,涉及日期、数字或字符串的测试)。
采纳模式流程为:先盘点硬编码用户可见字符串、手写日期/数字格式、字符串拼接、固定单位与左右布局,并在编辑前报告数量;以平台原生格式建立一个仅含英文(或项目开发语言)的字符串目录或消息文件;按影响顺序修复,关键项优先,只改国际化正确性所需内容并保持既有设计与行为;未经用户批准的显式迁移,不得改变持久化数据语义(时间戳含义、存储单位),只能提出建议;按规则添加确定性测试并运行真实测试结果;用平台指南工具做伪本地化、最长文本扩展、RTL 与最大字号验证 UI;最后说明改了什么、仍有哪些硬编码及原因、提出但未执行的迁移。
边界方面,无障碍标签应与普通字符串一样可本地化,但其具体文案属于无障碍范畴;用户生成内容(姓名、备注、地名)除非用户要求,否则不翻译、不转写、不规范化;翻译本身(机器翻译、翻译服务、译者工作流)不在范围内,也不得将应用字符串或用户内容发送到外部服务。