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)。
- 形式/文化的要件(ある場合)。
ワークフロー(監査 -> 修正 -> 検証)
- スコープとロケールターゲットの確認
- i18nフレームワークとロケールの場所を特定する。
- ロケールを確認する。指定がない場合はデフォルトでen-US + zh-CNとする。
- i18nベースラインのセットアップ(不足している場合)
- フレームワークに適したライブラリを選択する(例:React: react-i18next、Next.js: next-intl、Vue: vue-i18n)。
- パッケージをインストールし、i18nエントリ/設定ファイルを作成する。
- プロバイダをアプリケーションルートに配線し、ロケールリソースを読み込む。
- 言語切り替え機能と永続化(ルート/パラメータ/localStorage)を適宜追加する。
- ロケールファイルのレイアウトとキーの名前空間を確立する。
- ルーティングがロケール対応の場合、ロケールセグメント戦略(サブパス、サブドメイン、クエリパラメータ)を早期に定義する。
- メタデータがユーザー向けの場合は、タイトル/説明の翻訳を含める。
- キーの使用状況とロケールパリティの監査
- 以下を実行する:
python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json> - 欠落キー/パリティギャップはブロッカーとして扱う。
- 動的キー(
t(var))を手動で検証する。
- 生のユーザー向け文字列の検出
- 以下を検索する:
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<" rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\"" - アクセシビリティラベルをローカライズする。
- 文字列をキーに置き換え
- UIテキストには
t('namespace.key')を使用する。 - 複数形には
t('key', { count })+_one/_otherキーを使用する。 - 時刻/日付/数値にはIntl/アプリのフォーマッターを使用する。
- エラーハンドリングのローカライズ(重要)
- エラーコードをローカライズされたキーにマッピングし、ローカライズされたUIのみを表示する。
- 生のエラー詳細はログにのみ出力する。
- 不明なコードに対しては、ローカライズされたフォールバックを提供する。
- ロケールファイルの更新
- 欠落したキーを両方のロケールに追加する。
- プレースホルダーを一貫して保持する。要求がない限り名前の変更は避ける。
- 合意された方法で翻訳を生成し、プレースホルダーと複数形ルールを保持する。
- 検証
- 欠落/パリティの問題がゼロになるまで監査を再実行する。
- 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ファイルと比較する。
アクティベーショントリガー
エラーコードからローカライズされたメッセージへのマッピング、およびキーパリティ、複数形、フォーマットの検証。