I18n エキスパート

概要

完全な i18n セットアップと監査パスを実行します: i18n フレームワークを設定し、ユーザー向けのテキストをキーで置き換え、ロケール間でのパリティを確保し、en-US と zh-CN の複数形と書式設定を検証します。

コア機能

• ライブラリ選択とセットアップ（React、Next.js、Vue）。
• キー体系とロケールファイル構成。
• 翻訳生成と品質戦略（AI、プロフェッショナル、手動）。
• ルーティングと言語検出/切り替え。
• SEO とメタデータのローカライゼーション（該当する場合）。
• RTL サポート（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 エントリ/設定ファイルを作成します。
• アプリケーションルートでプロバイダーを設定し、ロケールリソースをロードします。
• 言語切り替え機能と永続性（ルート/パラメータ/localStorage）を必要に応じて追加します。
• ロケールファイルレイアウトとキー名前空間を確立します。
• ルーティングがロケール対応の場合、ロケールセグメント戦略を早期に定義します（サブパス、サブドメイン、クエリパラメータ）。
• メタデータがユーザー向けの場合、タイトル/説明の翻訳を含めます。

3. キー使用状況とロケール間パリティを監査

• 実行:

  python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json>
  

• 欠落しているキー/パリティギャップをブロッカーとして扱います。
• 動的キー（t(var)）を手動で検証します。

4. ユーザー向けの生のテキストを検出

• 検索:

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

• アクセシビリティラベルをローカライズします。

5. テキストをキーで置き換え

• UI テキストに t('namespace.key') を使用します。
• 複数形には t('key', { count }) + _one/_other キーを使用します。
• 時間/日付/数値フォーマットに Intl/アプリフォーマッターを使用します。

6. エラーハンドリングのローカライゼーション（重要）

• エラーコードをローカライズされたキーにマップします。ローカライズされた UI のみを表示します。
• 生のエラー詳細はログのみに記録します。
• 不明なコード向けのローカライズされたフォールバックを提供します。

7. ロケールファイルを更新

• 両方のロケールで欠落しているキーを追加します。
• プレースホルダーの一貫性を保ちます。明示的に要求された場合を除き、名前を変更しないでください。
• 合意した方法を使用して翻訳を生成します。プレースホルダーと複数形ルールを保持します。

8. 検証

• 欠落/パリティの問題がゼロになるまで監査を再実行します。
• JSON を検証します（例: python -m json.tool <file>）。
• 表示テキストをアサートするテストを更新します。

ガードレール

• 生の error.message を UI に公開しないでください。ローカライズされた文字列のみを表示します。
• 明示的に要求されない限り、余分なロケールを追加しないでください。
• 構造化された名前空間を優先します（例: errors.*, buttons.*, workspace.*）。
• 翻訳は簡潔で一貫性のあるものにします。
• 一部の技術用語/ブランド用語は翻訳しないままにします（例: 製品名、API、MCP、Bash）。

成果物（期待される出力）

• i18n 設定/プロバイダーの配線。
• 各対象言語のロケールファイル。
• 安定したキーで置き換えられた UI テキスト。
• 言語切り替え機能と永続性（該当する場合）。
• 表示テキストについての更新されたテスト。

アーキテクチャガイダンス（簡潔に）

• キー構造: 領域別のネストされた名前空間を優先します（例: common.buttons.save, pricing.tier.pro）。
• ファイルレイアウト: ロケール毎に 1 ファイルまたは名前空間ごと; キーをロケール間で同期させます。
• プレースホルダー: {name}/{{name}} を正確に保持します。複数形をロケールルールで検証します。
• 書式設定: 日付、時間、数値、リスト書式に Intl/アプリヘルパーを使用します。
• SEO/メタデータ: アプリがそれらを公開している場合、タイトルと説明をローカライズします。
• RTL: RTL ロケールの場合のみ必要; 論理的な CSS プロパティを使用し、レイアウトをテストします。
• Web 以外のサーフェス（Electron メインプロセスダイアログ、CLI プロンプト、ネイティブメニュー）もローカライゼーションが必要です。

パフォーマンスに関する注記（短編）

• アプリがサポートしている場合、ロケールバンドルを遅延ロードします。
• 大きなロケールファイルを名前空間で分割します。

失敗モード（ウォッチリスト）

• 欠落している翻訳: デフォルトロケールにフォールバックし、警告をログします。
• RTL レイアウトの問題: 論理的な CSS を検証し、ページをテストします。
• SEO 欠落: 該当する場合、代替手段とメタデータがローカライズされていることを確認します。

検証チェックリスト（短編）

• 欠落しているキーと生の UI 文字列がない。
• ロケール切り替えが機能し、永続化する。
• 複数形と書式設定が両方のロケールで検証されている。
• フォールバックロケールが設定されている。

リソース

scripts/

• scripts/i18n_audit.py: t('key') の使用法を抽出し、ロケール JSON ファイルと比較します。