localization-toolkit

I18n エキスパート

概要

i18n の設定と監査を一通り行います。i18n フレームワークを設定し、ユーザー向けの文字列をキーに置き換え、ロケール間の整合性を確保し、en-US と zh-CN の複数形処理と書式設定を検証します。

主な機能

• ライブラリの選定と設定（React、Next.js、Vue）。
• キーの設計とロケールファイルの構成。
• 翻訳の生成と品質管理の方針（AI、プロ翻訳、手動）。
• ルーティングと言語の検出・切り替え。
• SEO とメタデータのローカライズ（該当する場合）。
• RTL 対応（RTL ロケールが対象の場合のみ）。

スコープの入力（不明な場合は確認）

• フレームワークとルーティング方式。
• 現在の i18n の状態（未導入、一部導入、レガシー）。
• 対象ロケール（デフォルト：en-US + zh-CN）。
• 翻訳品質の要件（AI、プロ翻訳、手動）。
• 使用中のロケール形式（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 ファイルと照合します。