# Locale Guard

> 在前端代码库（React/TypeScript、Vue等）中搭建、审计和规范国际化/本地化流程，包括配置i18n框架、将硬编码字符串替换为翻译键、确保en-US/zh-CN等语言文件覆盖完整、映射本地化错误消息，并校验翻译键一致性、复数规则和格式化。当用户需要实施或审查多语言支持，提及i18n、本地化、翻译键、多语言文件，或询问如何替换硬编码字符串、配置react-i18next/next-intl、处理复数规则、进行语言审计时触发。

- Skill: `haomingz/locale-guard` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add haomingz/locale-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haomingz/locale-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: haomingz (https://skillmd.com/u/haomingz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/haomingz/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) 审计翻译键使用情况和多语言一致性
- 运行：
  ```bash
  python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json>
  ```
- 将缺失的翻译键或一致性问题视为阻塞项。
- 手动检查动态翻译键（`t(var)`）。

4) 查找未本地化的硬编码字符串
- 搜索：
  ```bash
  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 文件进行对比。