Workflow & Core Tools · daymade/claude-code-skills

i18n-expert

Name: i18n-expert
Author: daymade/claude-code-skills

This skill should be used when setting up, auditing, or enforcing internationalization/localization in UI codebases (React/TS, i18next or similar, JSON locales), including installing/configuring the i18n framework, replacing hard-coded strings, ensuring en-US/zh-CN coverage, mapping error codes to localized messages, and validating key parity, pluralization, and formatting.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The sole code asset is an audit script relying purely on the standard library: it extracts t('key') / i18n.t('key') / i18next.t('key') calls from source code using three regex patterns and performs set operations against the flattened key set of locale JSON files.

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*['\"]([^'\"]+)['\"]"), ]

The (?<![\w.]) negative lookbehind in the first regex is crucial: it prevents property access like obj.t(...) from being mistakenly matched as translation function calls. The three patterns cover the common bare t / i18n.t / i18next.t forms via pure text extraction rather than AST parsing—which is why SKILL.md simultaneously mandates manual handling of dynamic keys like t(var).

The scan proactively skips node_modules and .git, filtering files against an extension allowlist to prevent pointless traversals across large repositories.

i18n-expert/scripts/i18n_audit.py

if "node_modules" in path.parts or ".git" in path.parts: continue

The default extensions come from argparse default=["ts", "tsx", "js", "jsx"], which can be overridden via repeated --ext flags. iter_source_files recursively scans using rglob("*") and relies on path parts checks rather than substring matching, avoiding false positives like edge cases where project names contain node_modules.

It outputs three diff tables: missing_by_locale (used in code but absent from that locale), unused_by_locale (present in locale but unreferenced in code), and parity_missing (key gaps across locales, answering 'present in en but absent in zh').

i18n-expert/scripts/i18n_audit.py

parity_missing[name] = sorted(other_keys - locale_key_map[name])

parity_missing is implemented as 'union of keys from all other locales minus the keys of the current locale'; thus, any key missing in one locale file but present in another is flagged—serving as the exact signal required by SKILL.md's rule: 'Treat missing keys/parity gaps as blockers'.

Plural keys are explicitly exempted: when a base key is not directly matched, it is not flagged as missing if CLDR plural suffix variants like _one/_other exist.

i18n-expert/scripts/i18n_audit.py

PLURAL_SUFFIXES = ("_zero", "_one", "_two", "_few", "_many", "_other")

In compute_missing, a key falls into missing only after checking if key in locale_keys and then if has_plural_variant(key, locale_keys). Purpose: preventing forms like t('key', { count }) (bare key in source, key_one/key_other in locale) from triggering false positives, which would otherwise mark all pluralized keys as missing.

Locale name inference follows conventions: generic filenames such as common.json / translation.json / messages.json inherit their parent directory name as the locale name (locales/en-US/common.json → en-US).

i18n-expert/scripts/i18n_audit.py

if path.name in {"common.json", "translation.json", "messages.json"}:

Otherwise, it falls back to using the file stem. This dictates which locale each table belongs to in the output, serving as an essential adaptation for multi-namespace projects structured with one directory per locale.

The workflow follows a closed loop of 'Audit → Fix → Re-verify', treating zero-gap status as the definition of done: any audit gap is a blocker, requiring re-runs until zero issues remain.

i18n-expert/SKILL.md

8) Validate - Re-run the audit until missing/parity issues are zero.

Step 3 is phrased as 'Treat missing keys/parity gaps as blockers.', while Step 8 requires re-running until zero gaps remain and validating JSON validity via python -m json.tool—establishing an actionable, verifiable definition of done rather than assuming completion upon editing.

Concrete ripgrep regular expressions are provided for detecting hardcoded strings: one captures visible text inside JSX tags, and another detects three accessibility attributes (aria-label, title, and placeholder).

i18n-expert/SKILL.md

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

The first regex is "<[^>]+>[^<{]*[A-Za-z][^<{]*<", matching text inside tags and outside curly braces containing letters—using [^<{] to exclude interpolated content and avoid false positives on {t('x')}. SKILL.md explicitly instructs to 'Localize accessibility labels.', keeping a11y strings strictly in scope.

Error handling enforces a strict rule: never expose raw error.message to the UI, display only localized text, relegate raw details to logs, and provide localized fallbacks for unknown error codes.

i18n-expert/SKILL.md

- Never expose raw `error.message` to UI; show localized strings only.

Step 6 breaks this into three actions (error code → localized key, raw details logged only, localized fallback for unknown codes), which is reiterated in Guardrails. This elevates error localization from a translation issue to a critical security and user experience requirement (raw messages often leak internal paths, stack traces, and English technical details).

Framework selection provides default recommendations per stack and mandates determining early on whether routing is locale-aware (subpaths, subdomains, or query parameters).

i18n-expert/SKILL.md

- Choose a framework-appropriate library (e.g., React: react-i18next; Next.js: next-intl; Vue: vue-i18n).

This is followed immediately by: 'If routing is locale-aware, define the locale segment strategy early (subpath, subdomain, query param).'—shifting architectural decisions upfront to prevent costly routing refactors later.

Deliberate boundaries define what should NOT be translated: technical and brand terms like product names, API, MCP, and Bash remain untouched.

i18n-expert/SKILL.md

- Some technical/brand terms should remain untranslated (e.g., product name, API, MCP, Bash).

The same Guardrails section also dictates 'do not add locales without authorization', 'prefer structured namespaces (errors.* / buttons.* / workspace.*)', and 'preserve placeholders like {name}/{{name}} verbatim'—acting as guardrails against breaking code during bulk refactoring.

The script supports both machine-readable --json output and a human-readable summary mode, making it convenient for CI integration or manual inspection.

i18n-expert/scripts/i18n_audit.py

if args.json: json.dump(output, sys.stdout, indent=2, ensure_ascii=False)

Human mode prints Missing, Unused, and Parity missing counts per locale and truncates missing keys to the first 50 entries (with an ellipsis beyond that), reflecting thoughtful usability design to prevent terminal flood in large repositories.

2Core Capabilities

01Extract t('key') usages from source code (three regexes covering t / i18n.t / i18next.t)

02Flatten locale JSON files into dot-notated key sets (supporting nested namespaces)

03Detect missing keys (with exemptions for plural suffixes)

04Detect multi-locale key alignment gaps (parity_missing) and unused keys (unused_by_locale)

05Locate hardcoded user-facing strings (JSX text + aria-label/title/placeholder)

06Provide i18n framework setup guidance (stack selection for React/Next.js/Vue, provider wiring, language switching/persistence, locale routing strategies)

07Map error codes to localized messages and enforce the 'never expose error.message' rule

08Perform final verification of JSON validity and test synchronization

3External Dependencies

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 键、更新测试）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local script or command: i18n-expert/scripts/i18n_audit.py (executed with python3, pure standard library; read-only access to source code and locale JSON, writes only to stdout)
本地工作目录: File read/write and artifact output: The script performs no write operations itself (no open(...,'w'), write_text, or json.dump to file; only json.dump(..., sys.stdout))

Audit Notes: Based on unified classification: 1) The sole executable asset is a pure standard library Python script that reads source code and locale JSON locally, outputting solely to stdout without writing to disk; 2) Full directory token scans (https?://, curl, wget, fetch(, API_KEY, TOKEN, SECRET, .env, cookie, keychain, credential, process.env, os.environ, subprocess, exec(, spawn) produced zero hits—no network, credentials, or child processes; 3) No third-party dependencies (the script imports only standard library modules); the i18n library is installed by the agent per project stack outside this skill's automated path. Classified as Blue rather than Green because it carries an executable script and the workflow modifies user source code and locale files (where mistakes can cause production incidents), making it more than a purely conversational skill.

5Second-Pass Verification

[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。

6Verdict & Scenarios

Separation of audit and execution: The script only reads and prints, delegating modifications to the agent, allowing reports to be reviewed before taking action.

The definition of done is based on actionable, verifiable criteria rather than intuition.

Handles engineering details without oversight, such as plurals and namespaces (CLDR six-plural suffixes, locale directory name inference).

Error handling guidelines improve both security and user experience simultaneously.

Clearly defines what must remain untouched (preserving placeholders, no unauthorized locales, leaving tech/brand terms untranslated), minimizing the blast radius of batch refactoring.

Best for: Ideal for conducting systematic health checks on existing React/Next.js/Vue projects with partial i18n (missing keys, parity mismatches, unused keys, overlooked hardcoded strings, unlocalized error messages), as well as establishing an i18n baseline for brand-new projects: choosing libraries, wiring providers, structuring namespaces and locale directories, and setting routing segment strategies—all delivered with a self-contained validation script. Especially suited for teams maintaining both en-US and zh-CN locales, as parity_missing is purpose-built for this setup.

Not for: Not suitable for zero-touch, fully automated whole-site localization without human intervention—it explicitly mandates human verification of dynamic keys and brand terms, and linguistic quality is out of scope. Not suitable for non-Web or non-TS/JS stacks (the script defaults to scanning ts/tsx/js/jsx and only recognizes t-style calls). Not suitable for workflows expecting direct code patch generation (it only produces reports). Also not suitable for lightweight tasks like translating a single copy file, where it would be over-engineering.

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload i18n-expert.tar.gz

sha256: 8e220e12dd691eab…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.