Locale guard

国际化本地化助手

概述

完成一次完整的 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）。
• 语气/文化要求（如有）。

工作流程（审计 -> 修复 -> 验证）

1. 确认范围和目标语言

• 识别 i18n 框架和语言文件位置。
• 确认目标语言；未指定时默认使用 en-US + zh-CN。

2. 搭建 i18n 基础（如尚未配置）

• 根据框架选择合适的库（如 React: react-i18next；Next.js: next-intl；Vue: vue-i18n）。
• 安装依赖包并创建 i18n 入口/配置文件。
• 在应用根节点挂载 Provider 并加载语言资源。
• 按需添加语言切换器和持久化机制（路由/参数/localStorage）。
• 建立语言文件目录结构和命名空间规范。
• 如果路由需要感知语言，尽早确定语言段策略（子路径、子域名、查询参数）。
• 如果元数据面向用户，需翻译标题和描述。

3. 审计翻译键使用情况和多语言一致性

• 运行：

  python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json>
  

• 将缺失的翻译键或一致性问题视为阻塞项。
• 手动检查动态翻译键（t(var)）。

4. 查找未本地化的硬编码字符串

• 搜索：

  rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<"
  rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\""
  

• 将无障碍标签也纳入本地化范围。

5. 用翻译键替换硬编码字符串

• 使用 t('namespace.key') 替换 UI 文本。
• 复数场景使用 t('key', { count }) + _one/_other 键。
• 日期/时间/数字使用 Intl/应用内格式化工具。

6. 错误信息本地化（关键步骤）

• 将错误码映射为本地化翻译键；仅向用户展示本地化内容。
• 原始错误详情仅写入日志。
• 为未知错误码提供本地化的兜底信息。

7. 更新语言文件

• 在所有目标语言文件中补充缺失的键。
• 保持占位符一致；除非要求否则避免重命名。
• 按约定的方式生成翻译；保留占位符和复数规则。

8. 验证

• 重新运行审计脚本，直到缺失和一致性问题归零。
• 校验 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 文件进行对比。