1仕組みと動作原理
唯一のコード資産は標準ライブラリのみで構成された監査スクリプトです。3つの正規表現でソースコード内の t('key') / i18n.t('key') / i18next.t('key') を抽出し、フラット化したロケールJSONのキー集合と集合演算を行います。
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*['\"]([^'\"]+)['\"]"), ]
1つ目の正規表現にある (?<![\w.]) の否定戻り読み（後読み）が極めて重要です。obj.t(...) のようなプロパティアクセスを翻訳関数の呼び出しと誤認するのを防ぎます。3つのパターンは単独の t / i18n.t / i18next.t という一般的な記述を網羅し、AST解析ではなくプレーンテキスト抽出を行うため、SKILL.md では動的キー（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 が含まれる」といった境界条件での誤判定を防ぎます。
3つの差分テーブルを出力します：missing_by_locale（コード側で使用されているが該当ロケールに未定義）、unused_by_locale（ロケールに存在するがコード側で未使用）、parity_missing（ロケール間の不整合、「enには存在するがzhにはない」等）。
i18n-expert/scripts/i18n_audit.py
parity_missing[name] = sorted(other_keys - locale_key_map[name])
parity_missing は「他ロケール全体のキーの和集合から該当ロケールのキーを引いたもの」として実装されています。そのため、あるロケールファイルに欠落があり別のロケールには存在するキーが浮き彫りになり、SKILL.md の『Treat missing keys/parity gaps as blockers』が準拠する検知トリガーとなります。
複数形キーは特別に除外されます。キー自体が直接一致しなくても、_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_one/key_other）が欠落として誤検出されるのを防ぎ、全複数形キーが赤マークされる事態を回避します。
ロケール名の推論には規約があります。common.json / translation.json / messages.json のような汎用ファイル名の場合、親ディレクトリ名をロケール名として採用します（locales/en-US/common.json → en-US）。
i18n-expert/scripts/i18n_audit.py
if path.name in {"common.json", "translation.json", "messages.json"}:
該当しない場合はファイルの stem（拡張子抜きの名前）を採用します。この規約によって出力内の各テーブルがどのロケール名に紐づくかが決定されるため、ロケールごとにディレクトリを分けるマルチネームスペース構成には必須の対応です。
ワークフローは「監査 → 修正 → 再検証」の閉ループであり、ギャップをゼロにすることを完了条件とします。監査で見つかった欠落はブロッカーとみなし、解消するまで再実行を義務付けています。
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 の3つのアクセシビリティ属性用の2本立てです。
i18n-expert/SKILL.md
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\""
1本目の正規表現は "<[^>]+>[^<{]*[A-Za-z][^<{]*<" であり、「タグの内側かつ波括弧の外側にある英字を含むテキスト」を抽出します。[^<{] によって埋め込み済みの値を弾き、{t('x')} を再検出する偽陽性を減らします。SKILL.md は『Localize accessibility labels.』と明記し、a11y文言もスコープに含めています。
エラーハンドリングには厳格な原則を設けています。生の error.message をUIに絶対に露出させずローカライズ文言のみを表示し、生の詳細はログにのみ出力した上で、未知のエラーコードにはフォールバック用文言を用意します。
i18n-expert/SKILL.md
- Never expose raw `error.message` to UI; show localized strings only.
Step 6 ではこれを3つのアクション（エラーコード → ローカライズキー、生の詳細はログのみ、未知コードにはローカライズフォールバック）として記述し、Guardrails セクションでも重ねて強調しています。これは「エラー情報の多言語化」を単なる翻訳作業からセキュリティとUXの課題へと昇格させるものです（生の message は内部パス、スタックトレース、英語の技術詳細を含みがちであるため）。
技術スタック別のフレームワーク選定のデフォルト指針を提供し、「ルーティングがロケールを認識するか否か」（サブパス/サブドメイン/クエリパラメータ）を最序盤で決定するよう求めています。
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 内で「勝手にロケールを追加しない」「構造化ネームスペース（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)
サマリーモードではロケールごとに Missing / Unused / Parity missing の3つのカウントを表示し、欠落キーは先頭50件のみ出力（それ以上は ... 表示）して大規模プロジェクトでの画面埋め尽くしを防ぐなど、使い勝手が考慮されています。
2コア機能
01ソースコードからの t('key') 利用箇所の抽出（t / i18n.t / i18next.t を網羅する3つの正規表現）
02ロケールJSONからドット区切りパス形式のキー集合へのフラット化（ネストされたネームスペースに対応）
03未定義キーの検出（複数形サフィックスの除外ロジックを含む）
04言語間でのキーの対称性チェック（parity_missing）および未使用キーの検出（unused_by_locale）
05ハードコードされたUI表示文字列の特定（JSXテキスト + aria-label/title/placeholder）
06i18nフレームワーク導入ガイド（React/Next.js/Vueの選定、Providerの接続、言語切り替えと永続化、ロケールルーティング戦略）
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 で実行、標準ライブラリのみ使用。ソースコードとロケールJSONは読み取り専用で、出力は stdout のみ）
- 本地工作目录: ファイルの読み書きと成果物の出力: スクリプト自体にはファイル書き込み処理なし（コード全体に open(...,'w')、write_text、ファイルへの json.dump は存在せず、json.dump(..., sys.stdout) のみ）
監査ノート： 統一判定基準による評価：① 唯一の実行可能アセットは標準ライブラリのみで書かれたPythonスクリプトであり、ローカルでソースコードとロケールJSONを読み取って標準出力にのみ出力し、ディスク書き込みは行いません。② ディレクトリ全体のトークンスキャン（https?://、curl、wget、fetch(、API_KEY、TOKEN、SECRET、.env、cookie、keychain、credential、process.env、os.environ、subprocess、exec(、spawn）でヒット件数ゼロ（ネットワーク通信なし、認証情報なし、サブプロセス実行なし）。③ 外部パッケージ依存なし（スクリプトは標準ライブラリ以外を一切インポートせず、i18nライブラリは対象プロジェクトの構成に応じてAgentが導入する形であり、本Skillの自動実行パスには含まれません）。GreenではなくBlueに分類される理由は、実行可能スクリプトを含んでおり、ワークフロー上ユーザーのソースコードやロケールファイルを実際に書き換えるため（誤修正が本番障害に直結するリスクがある）、純粋な対話型スキルにとどまらない点にあります。
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接続、ネームスペース・ロケール階層設計、ルーティング戦略の決定）を監査スクリプト付きで完結させるケースに最適です。特に en-US と zh-CN の両方を保守するチームにとっては、parity_missing がその目的のために直結して機能します。
不向きな用途： 人の手を介さずに全自動・ワンクリックでサイト全体の多言語化を完了させたいケースには適していません（動的キーの目視確認やブランド用語の翻訳可否判断を必須としており、文言の翻訳品質自体は保証対象外です）。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.