haomingz 国际化本地化助手
概述
完成一次完整的 i18n 搭建 + 审计流程：配置 i18n 框架、将用户可见的字符串替换为翻译键、确保多语言文件一致性、校验 en-US 和 zh-CN 的复数规则与格式化。
核心能力
- 库选型与配置（React、Next.js、Vue）。
- 翻译键架构与语言文件组织。
- 翻译生成策略（AI 翻译、专业翻译、人工翻译）。
- 路由与语言检测/切换。
- SEO 和元数据本地化（如适用）。
- 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=\"[^\"]+\"" - 将无障碍标签也纳入本地化范围。
- 用翻译键替换硬编码字符串
- 使用
t('namespace.key')替换 UI 文本。 - 复数场景使用
t('key', { count })+_one/_other键。 - 日期/时间/数字使用 Intl/应用内格式化工具。
- 错误信息本地化（关键步骤）
- 将错误码映射为本地化翻译键；仅向用户展示本地化内容。
- 原始错误详情仅写入日志。
- 为未知错误码提供本地化的兜底信息。
- 更新语言文件
- 在所有目标语言文件中补充缺失的键。
- 保持占位符一致；除非要求否则避免重命名。
- 按约定的方式生成翻译；保留占位符和复数规则。
- 验证
- 重新运行审计脚本，直到缺失和一致性问题归零。
- 校验 JSON 格式（如
python -m json.tool <file>）。 - 更新涉及可见文本的测试用例。
规范约束
- 绝不向 UI 暴露原始
error.message；只展示本地化字符串。 - 除非明确要求，不添加额外的语言。
- 优先使用结构化命名空间（如
errors.*、buttons.*、workspace.*）。 - 翻译保持简洁一致。
- 部分技术/品牌术语保持英文不翻译（如产品名、API、MCP、Bash）。
交付物
- i18n 配置与 Provider 挂载。
- 各目标语言的语言文件。
- UI 字符串已替换为稳定的翻译键。
- 语言切换器和持久化（如适用）。
- 更新后的测试用例。
架构指南（简要）
- 翻译键结构：按功能区域使用嵌套命名空间（如
common.buttons.save、pricing.tier.pro）。 - 文件布局：每种语言一个文件，或按命名空间拆分；确保各语言文件的键保持同步。
- 占位符：严格保持
{name}/{{name}}原样；按语言规则校验复数形式。 - 格式化：使用 Intl/应用内工具处理日期、时间、数字和列表格式化。
- SEO/元数据：如果应用对外暴露元数据，需翻译标题和描述。
- RTL：仅在涉及 RTL 语言时处理；使用逻辑 CSS 属性并测试布局。
- 非 Web 场景（Electron 主进程对话框、CLI 提示、原生菜单）也需要本地化。
性能建议（简要）
- 在应用支持的情况下按需加载语言包。
- 按命名空间拆分大型语言文件。
常见问题（关注点）
- 翻译缺失：回退到默认语言并记录警告日志。
- RTL 布局异常：检查逻辑 CSS 属性并测试页面。
- SEO 遗漏：确保在适用场景下本地化 alternate 标签和元数据。
验证清单（简要）
- 无缺失翻译键，无硬编码的 UI 字符串。
- 语言切换正常工作且可持久化。
- 两种语言的复数规则和格式化均已验证。
- 已配置兜底语言。
资源
scripts/
scripts/i18n_audit.py：扫描源码中t('key')的使用情况，与语言 JSON 文件进行对比。