i18n-localization

i18n のローカライズ

このスキルは、製品 UI、ドキュメント、マーケティングページ、メール、Web／アプリのルーティングにわたるローカライズ作業の計画、レビュー、強化に使用します。

標準用語

用語	意味
ロケール	en、en-US、ar-EG など、言語と任意の地域慣習の組み合わせ
メッセージカタログ	翻訳文字列とメッセージのメタデータのソース
ICU メッセージ	変数、複数形、選択肢、序数を安全に扱うメッセージ形式
疑似ロケール	ハードコードされたテキストやレイアウトの切れを明らかにするため、文字列を拡張してマークするテスト用ロケール
RTL	アラビア語やヘブライ語などの言語で使われる右から左へのレイアウト方向
フォールバック	ロケール、キー、翻訳が欠落している場合の意図的な動作

振り分け

$ARGUMENTS	モード	出力
空	ローカライズ監査	現在の対象範囲を調査し、ロケールに関するリスクを特定して、優先順位を付けた改善計画を提示します。
アプリ、ルート、機能、またはファイルパス	実装計画	対象範囲に関連する文字列、ルーティング、書式設定、QA、リリース時の確認事項を洗い出します。
ロケールまたは市場のリスト	ロケール対応状況レビュー	言語、地域、書式設定、ルーティング、フォールバック、翻訳引き継ぎの要件を確認します。
既存の計画または差分	レビュー	見落とされた文字列、安全でない連結、書式設定のバグ、カタログの不整合、RTL 対応の不足、テストの不足を確認します。
ローカライズ以外の自然言語	リダイレクト	対象範囲の境界を説明し、より適切なスキルに案内します。

引数が指定されていない場合は、関連するリポジトリまたは製品の対象範囲についてローカライズ監査を開始します。コードベースとユーザーのリクエストを確認しても判断事項が残る場合を除き、ロケールの希望を尋ねないでください。

参照ファイル一覧

ファイル	読み込むタイミング
references/localization-checklist.md	ローカライズ作業の計画、実装、レビュー、テスト、リリースを行うとき

重要なルール

1. ローカライズは単なる翻訳作業ではなく、製品の契約として扱ってください。対象範囲に含まれる場合は、ルーティング、書式設定、アクセシビリティ、検索メタデータ、分析ラベル、メール、サポート画面まで対応してください。
2. 翻訳済みの断片を連結して文を作らないでください。完全なメッセージと変数、ICU の選択肢／複数形形式、またはフレームワークに相当するメッセージ形式を使用してください。
3. システムにそのレイヤー向けのカタログ抽象化がすでに存在する場合を除き、ユーザーに表示される文字列をビジネスロジックや共有定数に置かないでください。
4. 日付、時刻、数値、通貨、リスト、相対時刻、単位、名前にはロケール対応のフォーマッターを使用してください。文字列テンプレートで独自に書式設定しないでください。
5. 言語と地域を分けて扱ってください。en、en-US、en-GB では、文言、日付、通貨、測定単位、法的内容が異なる場合があります。
6. フォールバックの動作を明確に定義してください。翻訳の欠落は開発環境では明示的に失敗させ、本番環境では意図した形で劣化させてください。
7. 疑似ロケールを使って、文字列の拡張、アクセント付与、括弧マーカー、補間の安全性、切り詰めを確認してください。
8. アラビア語、ヘブライ語、ペルシア語、ウルドゥー語、または混在方向のユーザーコンテンツが表示される可能性がある場合は、RTL と双方向テキストの確認を含めてください。
9. メッセージキーを安定した状態に保ってください。元のメッセージの意味が変わらない限り、カタログを頻繁に変更したり、翻訳メモリを無効にしたりしないでください。
10. 翻訳者がコード構文を扱わずに済むようにしてください。注記、スクリーンショット、変数の説明、文字数制限、製品の背景情報を提供してください。

ワークフロー

1. 対象範囲を特定する

リクエストによって影響を受ける対象を特定します。

• UI コンポーネント、サーバーレンダリングされたページ、ネイティブ画面、メール、PDF、ドキュメント、通知、エラー状態、空の状態、トランザクション関連の文言。
• ルート構造、ロケールのネゴシエーション、リダイレクト、正規 URL、hreflang、サイトマップのエントリ、保存済みのユーザーロケール設定。
• データ駆動型コンテンツ、CMS フィールド、Markdown／ドキュメントのコンテンツ、法務文書、価格、単位、市場ごとの提供状況。

実装作業の場合は、変更を提案する前に、既存の i18n ライブラリ、ルーティング規約、カタログ形式、テストのパターンを確認します。

2. メッセージを抽出してモデル化する

文字列を含む各対象について、次の対応を行います。

• ユーザーに表示される文字列を、既存のカタログまたはメッセージレイヤーに移します。
• 名前付き変数を使用した完全な文のメッセージにします。
• 複数形、選択、性別、序数、数に応じて変化するテキストは、ICU 形式のバリエーションまたはフレームワークの同等機能でモデル化します。
• 意味が曖昧なラベル、製品用語、プレースホルダー、変数には、翻訳者向けの説明を追加します。
• 安定したキーは、英語の表現だけでなく、意味に基づいて付けます。

安定した機能名前空間の下に置かれている場合を除き、title、subtitle、buttonText のような汎用キーは避けます。

3. 書式をローカライズする

ロケールによって異なる値をすべて確認します。

• 日付、時刻、タイムゾーン、相対時間、暦に関する前提。
• 数値、小数、パーセント、通貨、会計形式、コンパクト表記、単位の書式。
• リスト、氏名、住所、電話番号、郵便番号、並べ替え、大文字・小文字の変換、検索の正規化。
• フォームの検証、解析、マスク、サーバーとクライアント間の往復動作。

Intl.* などのプラットフォームフォーマッター、フレームワークヘルパー、または十分に検証されたライブラリ API を優先します。

4. ロケールをルーティングして保持する

次の点を検証します。

• アプリがどのようにロケールを選択するか：URL プレフィックス、ドメイン、アカウント設定、Cookie、ブラウザーの言語、明示的なセレクター。
• リダイレクトが決定的で、キャッシュに安全かどうか。
• 正規 URL、代替リンク、メタデータ、Open Graph、サイトマップ、robots ルール、ドキュメントナビゲーションが、ロケール戦略と一致しているか。
• API、バックグラウンドジョブ、メールが、表示中のアプリと同じロケールコンテキストを受け取るか。

製品ですでに結び付けられている場合を除き、ロケールのネゴシエーションを認証または課金ポリシーと混在させないでください。

5. テストと QA

最低限、次の確認を推奨または追加します。

• カタログの網羅性と未使用キーの検出。
• 補間変数の不足。
• 疑似ロケールでのレンダリング。
• 必要に応じて、文字列の拡張や RTL レイアウトを対象とするスナップショットまたはビジュアルカバレッジ。
• 少なくとも 1 つの米国以外のロケールを含む、代表的なロケールでの書式テスト。
• 言語属性、テキストの方向、スクリーンリーダー用ラベル、翻訳された aria テキストに関するアクセシビリティチェック。

レビュータスクでは、利用可能なテストで確認できる内容と、視覚的な QA または翻訳者による QA が引き続き必要な内容を報告します。

段階的な情報開示

• ルーティング、厳守事項、出力形式を確認するには、この SKILL.md から始めます。
• 具体的なローカライズ作業を計画、レビュー、リリースする場合に限り、references/localization-checklist.md を読みます。
• 無関係なフロントエンド、SEO、コピーライティング、JavaScript のガイダンスを事前に読み込まないでください。
• 新しいツールを導入する前に、既存のプロジェクトの i18n ライブラリとカタログ形式を使用します。

出力形式

簡潔で実装を重視した出力を返します。

• 調査結果：監査やレビューでは、ファイルまたはルートへの参照を添え、重要度の高い順に記載します。
• 計画：実装リクエストでは、依存関係の順に記載します：ルーティング／カタログの基盤、抽出、書式、QA、リリース。
• 受け入れ基準：該当する場合、カタログの網羅性、疑似ロケール、書式、フォールバック、ルート／SEO の確認を含めます。
• 未解決の質問：コードベースまたはユーザーのリクエストから根拠を得られない選択事項に限ります。

ユーザーから明示的にコピー編集を依頼された場合を除き、マーケティングコピーを書き換えないでください。ローカライズによって具体的なレイアウトまたは文字方向の不具合が明らかになった場合を除き、一般的なフロントエンドの再設計は行わないでください。

検証契約

変更を完了とする前に、このスキルディレクトリから実行してください。

python scripts/check.py

完了条件：

1. scripts/check.py が終了コード 0 で終了すること。
2. このスキルディレクトリ内に、ポータブル CLI に関する違反が残っていないこと。
3. ディスパッチテーブルのスモークレビューで、空のプロンプト、明示的なプロンプト、暗黙的なプロンプト、ネガティブコントロールのプロンプトを確認すること。