用途
localization-toolkit 是一个面向 UI 代码库的国际化/本地化（i18n）技能，用于在项目中搭建、审计或强制执行 i18n 规范。它覆盖从框架配置、用户可见字符串替换为键、语言文件对齐，到复数与格式化校验的完整流程，默认目标语言为 en-US 与 zh-CN。
主要能力
- 库选择与配置（React、Next.js、Vue）。
- 键架构与语言文件组织。
- 翻译生成与质量策略（AI、专业、人工）。
- 路由与语言检测/切换。
- SEO 与元数据本地化（适用时）。
- RTL 支持（仅当 RTL 语言在范围内时）。
使用方式
工作流分为审计、修复、验证三个阶段：
- 确认范围与目标语言：识别 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 搜索 JSX 文本与 aria-label/title/placeholder 等属性；本地化无障碍标签。
- 用键替换字符串：UI 文本使用 t('namespace.key')；复数使用 t('key', { count }) + _one/_other 键；时间/日期/数字使用 Intl/应用格式化器。
- 本地化错误处理（关键）：将错误码映射到本地化键；仅显示本地化 UI；仅记录原始错误详情；为未知错误码提供本地化回退。
- 更新语言文件：在两种语言中添加缺失键；保持占位符一致；避免未经请求的重命名；按约定方法生成翻译，保留占位符与复数规则。
- 验证：重新运行审计直至缺失/对齐问题为零；验证 JSON（如
python -m json.tool <file>）；更新断言可见文本的测试。
适用场景
- 在 React/TS、Next.js、Vue 等前端项目中搭建 i18n。
- 审计现有 i18n 状态（无、部分、遗留）。
- 需要 en-US 与 zh-CN 双语支持的项目。
- 需要本地化错误处理、无障碍标签、SEO 元数据、RTL 布局的场景。
- 非 Web 界面（Electron 主进程对话框、CLI 提示、原生菜单）的本地化。
限制与注意事项
- 范围输入不明确时需询问：框架与路由风格、现有 i18n 状态、目标语言、翻译质量需求、语言文件格式（JSON、YAML、PO、XLIFF）、正式/文化要求。
- 护栏：绝不将原始 error.message 暴露到 UI；除非明确要求，不添加额外语言；优先使用结构化命名空间（如 errors.、buttons.、workspace.*）；翻译保持简洁一致；部分技术/品牌术语保持不翻译（如产品名、API、MCP、Bash）。
- 失败模式：缺失翻译回退到默认语言并记录警告；RTL 布局问题需验证逻辑 CSS 并测试页面；SEO 缺失需确保适用时本地化 alternates 与元数据。
- 性能：应用支持时懒加载语言包；按命名空间拆分大型语言文件。
交付物
- i18n 配置/provider 接入。
- 每种目标语言的语言文件。
- 替换为稳定键的 UI 字符串。
- 语言切换器与持久化（如适用）。
- 更新后的可见文本测试。
资源
- scripts/i18n_audit.py：提取 t('key') 使用并与语言 JSON 文件比对。