1实现原理 · 为什么它能做到
唯一的代码资产是一个纯标准库的审计脚本：用三条正则抽取源码里的 t('key') / i18n.t('key') / i18next.t('key')，与 locale JSON 扁平化后的 key 集合做集合运算。
i18n-expert/scripts/i18n_audit.py
KEY_PATTERNS = [ re.compile(r"(?<![\w.])t\(\s*['\"]([^'\"]+)['\"]"), re.compile(r"\bi18n\.t\(\s*['\"]([^'\"]+)['\"]"), re.compile(r"\bi18next\.t\(\s*['\"]([^'\"]+)['\"]"), ]
第一条正则的 (?<![\w.]) 前置否定断言是关键：避免把 obj.t(...) 这种属性访问误当成翻译函数调用。三条模式覆盖裸 t / i18n.t / i18next.t 三种常见写法，是纯文本抽取而非 AST 解析——所以 SKILL.md 同时要求人工处理动态 key（t(var)）。
扫描时主动跳过 node_modules 与 .git，并按扩展名白名单收文件，避免在大仓库里做无意义遍历。
i18n-expert/scripts/i18n_audit.py
if "node_modules" in path.parts or ".git" in path.parts: continue
默认扩展名来自 argparse 的 default=["ts", "tsx", "js", "jsx"]，可用 --ext 重复指定。iter_source_files 用 rglob("*") 递归，靠 parts 判断而非字符串匹配路径，避免把「项目名里含 node_modules」这类边界误伤。
输出三张差异表：missing_by_locale（代码用了但该 locale 没有）、unused_by_locale（locale 有但代码没用到）、parity_missing（各 locale 之间的缺失，回答「en 有 zh 没有」）。
i18n-expert/scripts/i18n_audit.py
parity_missing[name] = sorted(other_keys - locale_key_map[name])
parity_missing 的实现是「其它所有 locale 的 key 并集 减去 本 locale 的 key」，因此一个 locale 文件缺失、但另一个没缺的 key 会被点出来——这正是 SKILL.md 里『Treat missing keys/parity gaps as blockers』所依赖的信号。
复数键被专门豁免：key 本体没直接命中、但存在 _one/_other 等 CLDR 复数后缀变体时不算缺失。
i18n-expert/scripts/i18n_audit.py
PLURAL_SUFFIXES = ("_zero", "_one", "_two", "_few", "_many", "_other")
compute_missing 里先 if key in locale_keys 再 if has_plural_variant(key, locale_keys) 才落进 missing。这里在做什么：让 t('key', { count }) 这种写法（源码里是裸 key，locale 里是 key_one/key_other）不被误报为缺失，否则审计会把所有复数键全部标红。
locale 名推断有约定：common.json / translation.json / messages.json 这类通用文件名用父目录名当 locale 名（locales/en-US/common.json → en-US）。
i18n-expert/scripts/i18n_audit.py
if path.name in {"common.json", "translation.json", "messages.json"}:
否则退回用文件 stem 当名字。这条决定了输出里每张表挂在哪个 locale 名下，对多命名空间项目（每 locale 一个目录）是必要适配。
工作流是「审计 → 修复 → 复验」的闭环，且把缺口归零当作完成条件：审计发现缺失即视为 blocker，改完必须复跑到零。
i18n-expert/SKILL.md
8) Validate - Re-run the audit until missing/parity issues are zero.
Step 3 的措辞是『Treat missing keys/parity gaps as blockers.』，Step 8 要求复跑到零并用 python -m json.tool 校验 JSON 合法——形成「有可执行判据的完成定义」，而不是「改完就说好了」。
裸字符串检索给了具体的 ripgrep 正则：一条抓 JSX 标签里的可见文案，一条抓 aria-label / title / placeholder 三类可访问性属性。
i18n-expert/SKILL.md
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\""
第一条正则是 "<[^>]+>[^<{]*[A-Za-z][^<{]*<"，即「标签内、花括号外、含字母」的文本——用 [^<{] 排除已经插值的内容，减少把 {t('x')} 再抓一遍的假阳性。SKILL.md 专门提示『Localize accessibility labels.』，把无障碍文案纳入范围。
错误处理有一条硬性准则：绝不把原始 error.message 暴露到 UI，只显示本地化文案，原始细节只进日志，并给未知错误码配本地化兜底。
i18n-expert/SKILL.md
- Never expose raw `error.message` to UI; show localized strings only.
Step 6 把它写成三条动作（错误码 → 本地化 key / 原始细节只记日志 / 未知码给本地化 fallback），Guardrails 段落再复述一次。这是把「错误信息本地化」从翻译问题提升为安全与体验问题（原始 message 常含内部路径、堆栈、英文技术细节）。
框架选型给了按栈的默认答案，且把「路由是否 locale 感知」（子路径/子域/query 参数）要求在最早期就定下来。
i18n-expert/SKILL.md
- Choose a framework-appropriate library (e.g., React: react-i18next; Next.js: next-intl; Vue: vue-i18n).
紧随其后的一条是『If routing is locale-aware, define the locale segment strategy early (subpath, subdomain, query param).』——把架构决策前置，避免后期改造路由。
刻意划定「不该翻译」的边界：产品名、API、MCP、Bash 这类技术/品牌词保持原样。
i18n-expert/SKILL.md
- Some technical/brand terms should remain untranslated (e.g., product name, API, MCP, Bash).
同一段 Guardrails 还规定「不擅自新增 locale」「优先结构化命名空间（errors.* / buttons.* / workspace.*）」「占位符 {name}/{{name}} 必须原样保留」——这些是防止批量改造把代码改坏的护栏。
脚本支持 --json 机器可读输出与人类摘要两种模式，便于接入 CI 或人工巡检。
i18n-expert/scripts/i18n_audit.py
if args.json: json.dump(output, sys.stdout, indent=2, ensure_ascii=False)
人类模式会按 locale 打印 Missing / Unused / Parity missing 三个计数，并且只列前 50 条缺失 key（超过打 ...），避免大规模项目刷屏——细节上考虑过可用性。
2核心能力
01从源码抽取 t('key') 用法（三条正则覆盖 t / i18n.t / i18next.t）
02locale JSON 扁平化成点号路径 key 集合（支持嵌套命名空间）
03缺失键检测（含复数后缀豁免）
04多语言键位对齐检测（parity_missing）与未使用键检测（unused_by_locale）
05硬编码用户可见字符串的定位（JSX 文本 + aria-label/title/placeholder）
06i18n 框架搭建指导（React/Next.js/Vue 的选型、provider 接线、语言切换与持久化、locale 分段策略）
07错误码到本地化消息的映射与「不暴露 error.message」准则
08JSON 合法性与测试同步的收尾校验
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | python3（执行 scripts/i18n_audit.py；仅标准库 argparse/json/re/pathlib/typing） |
| cli | rg（ripgrep，用于定位裸字符串与可访问性属性） |
| cli | python -m json.tool（校验 locale JSON 合法性） |
| package | i18n 库（由 agent 按栈安装，非脚本调用：react-i18next / next-intl / vue-i18n） |
| api | 宿主 Edit/写文件能力（替换源码字符串、新增 locale 键、更新测试） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: i18n-expert/scripts/i18n_audit.py（python3 执行，纯标准库；只读源码与 locale JSON，只写 stdo
- 本地工作目录: 文件读写与工件输出: 脚本自身无写操作（全文无 open(...,'w')/write_text/json.dump 到文件，只有 json.dump(..., sys.s
审计说明： 。按统一分档：① 唯一可执行资产是纯标准库 Python 脚本，本地读源码与 locale JSON、只打印不落盘；② 全目录 token 扫描（https?://、curl、wget、fetch(、API_KEY、TOKEN、SECRET、.env、cookie、keychain、credential、process.env、os.environ、subprocess、exec(、spawn）零命中——无网络、无凭证、无子进程；③ 无第三方包依赖（脚本不 import 任何非标准库），i18n 库由 agent 按项目栈安装，不在本 skill 的自动化路径里。落蓝而非绿的原因是：它带可执行脚本且工作流会实际改写用户源码与 locale 文件（改错即出线上事故），不是纯对话型 skill。
5第二遍独立确认
- [ok] 外部依赖逐条是否真实存在 — python3 见 shebang；rg 两条命令见 SKILL.md Step 4 代码块；python -m json.tool 见 Step 8；i18n 库安装见 Step 2 的 Install packages；宿主写能力见 Step 5 与 Deliverables。无一条来自推测。
- [ok] 脚本是否真的只读（安全结论最关键的一条） — 通读 i18n_audit.py 全文：唯一 I/O 是 path.read_text(encoding='utf-8') 与 path.open(encoding='utf-8') 读 locale、print 与 json.dump(sys.stdout)。无写文件、无删除、无 mkdir。已在 file_writes 中明确把写入归到 agent 侧。
- [ok] 『零网络』是否被 token 扫描的空结果证明 — 扫描零命中即为证据；SKILL.md 正文也未出现任何 URL 或域名（对比同仓其他 skill 常见域名常量）。故 network_calls = []。
- [ok] 复数豁免是否真在 compute_missing 中生效 — compute_missing 内两个 continue 分支：key in locale_keys 与 has_plural_variant(key, locale_keys)，后者遍历 PLURAL_SUFFIXES 六个后缀构造 f"{key}{suffix}" 再查集合。代码属实，非文档口号。
- [discrepancy] parity_missing 语义是否与 SKILL.md 表述一致 — 〔第二遍标注：措辞微调〕实现是『其它所有 locale key 并集 − 本 locale key』（other_keys - locale_key_map[name]），语义为「别家有而本家缺」，与 SKILL.md『ensuring en-US/zh-CN coverage』一致，但它不是「两两全等」的严格校验：当同缺一个 key 时两边都不报。第一遍若把 parity 描述成「严格一致校验」会夸大，已在 how_it_works/note 中写明实现语义。
- [ok] 动态 key 的处理是否被承诺为自动 — SKILL.md 明写『Manually verify dynamic keys (`t(var)`).』——正则抽取天然覆盖不到动态 key，文档没有掩盖这一限制，不存在夸大。
- [ok] 元数据（license/stars/last_push） — 取自同 repo 同 commit 的池内既有值（MIT、1385★、2026-09-09T12:33:29Z）；本次未联网复核 gh。
6结论
适合： 适合把已有部分 i18n 的 React/Next.js/Vue 项目做一次系统性体检（缺键、键位不齐、未使用键、漏改的硬编码文案、错误信息没本地化），也适合为全新项目搭 i18n 基线：选库、接线 provider、定命名空间与 locale 目录布局、定路由分段策略，一次做完并自带验收脚本。对同时维护 en-US 与 zh-CN 两个 locale 的团队尤其对口——parity_missing 就是为这个场景准备的。
不适合： 不适合想零人工、一键完成全站国际化的场景——它明确要求复核动态 key、人工决定品牌词是否翻译，且文案语义质量不在保障范围；不适合非 Web 或非 TS/JS 栈（脚本默认只扫 ts/tsx/js/jsx，正则也只认 t 系调用）；不适合期望它给出可应用的代码补丁的用法（它只出报告）；也不适合只想翻译单个文案文件的轻量需求——那用它属于过度工程。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload i18n-expert.tar.gz
sha256:
Option B · Copy Guide for Agent8e220e12dd691eab…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.