I18n 专家
概述
完成完整的 i18n 设置 + 审计流程:配置 i18n 框架、将用户可见字符串替换为键、确保语言文件一致性、验证 en-US 和 zh-CN 的复数/格式化规则。
核心能力
- 库的选择和设置(React、Next.js、Vue)。
- 键架构和语言文件组织。
- 翻译生成和质量策略(AI、专业、手动)。
- 路由和语言检测/切换。
- SEO 和元数据本地化(适用时)。
- RTL 支持(仅当 RTL 语言在范围内)。
范围输入(如果不明确请询问)
- 框架和路由风格。
- 现有 i18n 状态(无、部分、遗留)。
- 目标语言(默认:en-US + zh-CN)。
- 翻译质量需求(AI vs 专业 vs 手动)。
- 使用的语言格式(JSON、YAML、PO、XLIFF)。
- 形式/文化要求(如有)。
工作流程(审计 -> 修复 -> 验证)
- 确认范围和语言目标
- 确定 i18n 框架和语言文件位置。
- 确认语言;当指定时默认使用 en-US + zh-CN。
- 设置 i18n 基线(如果缺失)
- 选择适合框架的库(例如,React:react-i18next;Next.js:next-intl;Vue:vue-i18n)。
- 安装包并创建 i18n 入口/配置文件。
- 在应用根节点中连接 Provider 并加载语言资源。
- 添加语言切换器和持久化机制(路由/参数/localStorage 视情况而定)。
- 建立语言文件布局和键命名空间。
- 如果路由是语言感知的,尽早定义语言段策略(子路径、子域名、查询参数)。
- 如果元数据对用户可见,包括标题/描述的翻译。
- 审计键使用和语言文件一致性
- 运行:
python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json> - 将缺失键/一致性差距视为阻碍项。
- 手动验证动态键(
t(var))。
- 查找原始用户可见字符串
- 搜索:
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<" rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\"" - 本地化无障碍标签。
- 将字符串替换为键
- 对 UI 文本使用
t('namespace.key')。 - 对于复数使用
t('key', { count })+_one/_other键。 - 对时间/日期/数字使用 Intl/应用格式化器。
- 本地化错误处理(关键)
- 将错误代码映射到本地化键;仅显示本地化 UI。
- 仅记录原始错误详细信息。
- 对未知代码提供本地化后备。
- 更新语言文件
- 在两种语言中添加缺失的键。
- 保持占位符一致;除非请求,否则避免重命名。
- 使用商定的方法生成翻译;保留占位符和复数规则。
- 验证
- 重新运行审计直到缺失/一致性问题为零。
- 验证 JSON(例如,
python -m json.tool <file>)。 - 更新断言可见文本的测试。
防护规则
- 切勿将原始
error.message暴露给 UI;仅显示本地化字符串。 - 除非明确请求,否则不要添加额外的语言。
- 首选结构化命名空间(例如,
errors.*、buttons.*、workspace.*)。 - 保持翻译简洁一致。
- 某些技术/品牌术语应保留不翻译(例如,产品名称、API、MCP、Bash)。
交付物(预期输出)
- i18n 配置/提供者连接。
- 每种目标语言的语言文件。
- 将 UI 字符串替换为稳定的键。
- 语言切换器和持久化机制(如适用)。
- 更新用于可见文本的测试。
架构指南(保持简洁)
- 键结构:按区域优先使用嵌套命名空间(例如,
common.buttons.save、pricing.tier.pro)。 - 文件布局:每种语言一个文件或每种语言一个命名空间;保持键在语言之间同步。
- 占位符:精确保留
{name}/{{name}};根据语言规则验证复数。 - 格式化:对日期、时间、数字和列表格式化使用 Intl/应用辅助函数。
- SEO/元数据:如果应用暴露它们,则本地化标题和描述。
- RTL:仅 RTL 语言需要;使用逻辑 CSS 属性并测试布局。
- 非 Web 界面(Electron 主进程对话框、CLI 提示、原生菜单)也需要本地化。
性能说明(简短)
- 当应用支持时,惰性加载语言包。
- 按命名空间拆分大型语言文件。
失败模式(观察列表)
- 缺少翻译:回退到默认语言并记录警告。
- RTL 布局问题:验证逻辑 CSS 并测试页面。
- SEO 缺失:确保在适用时本地化 alternative 链接和元数据。
验证清单(简短)
- 没有缺失的键,没有原始 UI 字符串。
- 语言切换有效且持久。
- 在两种语言中验证复数和格式化。
- 配置了回退语言。
资源
scripts/
scripts/i18n_audit.py:提取t('key')的使用情况并与语言 JSON 文件进行比较。
激活触发器
将错误代码映射到本地化消息,并验证键一致性、复数和格式化。