i18n-expert

I18n 专家

概述

完成一套完整的 i18n 配置与审查：配置 i18n 框架，将面向用户的字符串替换为键，确保各语言区域内容一致，并验证 en-US 和 zh-CN 的复数形式与格式化。

核心能力

• 库的选择与配置（React、Next.js、Vue）。
• 键的架构设计与语言区域文件组织。
• 翻译生成与质量策略（AI、专业翻译、人工翻译）。
• 路由与语言检测/切换。
• SEO 和元数据本地化（适用时）。
• RTL 支持（仅在范围包含 RTL 语言区域时）。

范围输入（不明确时请询问）

• 框架和路由风格。
• 现有 i18n 状态（无、部分完成、旧版）。
• 目标语言区域（默认：en-US + zh-CN）。
• 翻译质量要求（AI、专业翻译或人工翻译）。
• 使用的语言区域文件格式（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. 将字符串替换为键

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

6. 本地化错误处理（关键）

• 将错误代码映射到本地化键；仅显示本地化 UI。
• 仅记录原始错误详情。
• 为未知错误代码提供本地化回退文本。

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：在适用情况下确保 alternates 和元数据已本地化。

验证清单（简要）

• 没有缺失的键，也没有未处理的 UI 字符串。
• 区域设置切换正常且会保留。
• 已验证两种区域设置下的复数形式和格式。
• 已配置回退区域设置。

资源

scripts/

• scripts/i18n_audit.py：提取 t('key') 的用法，并与区域设置 JSON 文件进行比较。