software-localisation

ソフトウェアのローカライズ

このスキルは、本番環境の Web アプリにおける i18n と l10n に使用します。対象は、ライブラリの選定、メッセージカタログ、ICU の利用、ロケールルーティング、翻訳ワークフロー、RTL、リリースゲートです。目標は単に文字列を翻訳することではありません。ロケールに応じて安全に動作する製品を実現することです。

このスキルを使用する場面

• React、Vue、Angular、Next.js で i18n を設定またはデバッグする
• ライブラリとカタログ戦略を選定する
• ICU の複数形処理、書式設定、ロケール検出を実装する
• RTL サポートを追加する
• 抽出、翻訳ワークフロー、TMS 統合を設定する
• 翻訳漏れ、言語混在のリグレッション、不適切なロケールフォールバック動作を修正する
• バックエンドで生成された文章（AI による要約、ナラティブ）を、ローカライズされた Web クライアントやネイティブクライアントに提供する

別のスキルを使用する場面

• 一般的なフロントエンドアーキテクチャ -> software-frontend
• 国際 SEO と hreflang -> marketing-seo
• 異文化 UX と市場への適応 -> software-ui-ux-design または marketing-geo-localization
• 一般的な WCAG/ARIA 準拠と欧州アクセシビリティ法（EAA）への対応 -> software-accessibility。このスキルでは、i18n に特化した部分（lang/dir の伝播、スクリプトに応じた行の高さ、IME）のみを references/accessibility-i18n.md で扱います。

このスキルを使用しない場面

• 製品のロケールが1つで、追加する計画も確定していない — 念のために ICU カタログ、TMS 統合、ロケールルーティングを先行して構築しないでください。通常の文字列でリリースし、2つ目のロケールが実際に必要になった時点で再検討します。
• 依頼が「このテキストを翻訳して」であり、コード、カタログ、製品の画面が関係しない — これはローカライズエンジニアリングではなく翻訳の依頼です。そのまま翻訳してください。
• i18n の実装は関係なく、国際 SEO の構造（hreflang、ccTLD とサブフォルダーのどちらにするか）についての依頼 -> 代わりに marketing-seo を使用します。

ネイティブモバイルの範囲

このスキルでは、Web に加えてネイティブアプリの文字列、複数形、カタログ、翻訳パイプラインを扱います。バックエンドで生成された文章と、カタログのキーと値の対応も対象です。詳細は references/backend-generated-content-i18n.md を参照してください。ここでのフレームワーク設定は Web を優先して扱います。プラットフォーム API については software-ios-native、software-android-native、または software-mobile を参照してください。そこで確認する項目は次のとおりです。

• iOS：String Catalog（Localizable.xcstrings）。複数形はエディターの「複数形で変化」を使用します。これにより、各言語の CLDR 複数形が追加されます。
• Android：アプリごとの言語設定（Android 13 / API 33 以降）は、AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(...))（後方互換性あり）または LocaleManager を使用します。android:localeConfig または androidResources { generateLocaleConfig = true }（AGP 8.1 以降）でロケールを宣言します。

---

ワークフロー

1. フレームワーク、ロケール数、ルート戦略、翻訳ワークフローを確認します。
2. ライブラリとカタログのモデルを選定します。
3. 明示的に指定されたルートの解決と、初回アクセス時のロケールネゴシエーションおよび永続化を分けて定義します。
4. ICU または同等のメッセージ書式設定を正しく実装します。
5. 抽出、キー漏れ、古くなった翻訳のチェックを追加します（キー漏れの検出）。LLM/MT によるドラフトには、references/translation-workflows.md に記載されている ICU-AST、用語集、品質推定、レビュアーの各ゲートを適用します。
6. 必要に応じて RTL とビジュアルリグレッションのテストを追加します。疑似ローカライズ、RTL の自動テスト、複数形のエッジケースに関するテストパターンは references/testing-i18n.md を参照してください。
7. インデックス可能なルートまたは顧客に表示されるルートで、言語混在や安全でないフォールバック動作が起きる場合はリリースをブロックします。

クイックリファレンス

状況	ライブラリ	理由
React / TypeScript で汎用的な柔軟性が必要	i18next + react-i18next	有効化時のセレクター型付け、プラグイン連携
ICU を優先するカタログを使用し、FormatJS ツールがすでに導入済み	react-intl	FormatJS の抽出／コンパイルに対応した ICU カタログ
Next.js App Router	next-intl	RSC + App Router 向けに構築され、ロケールルーティングが設定済み
Vue	vue-i18n	フレームワーク標準で、Vue ツールと連携
Angular	@angular/localize	ビルド時の抽出と AOT コンパイル
バンドルサイズの予算が厳しい	Lingui	マクロによる抽出。実際に配布するバンドルを測定してください
チームが型ラッパーの自動生成を明確に希望している	typesafe-i18n	キーの型安全性を完全に確保。メンテナンス負荷が高いモデル

人気だけで選ばないでください。ルーティングモデル、抽出のニーズ、ICU に関する要件、チームのメンテナンス習慣に基づいて選択してください。フレームワークごとのセットアップ手順については、references/framework-guides.md を参照してください。

ICU MessageFormat 2（MF2）：まだ標準の選択肢ではありません

MF2 は Unicode の LDML 仕様で構文レベルの標準化が完了しており（CLDR/LDML 47、2025 年 3 月以降 Stable）、「新しい ICU」として扱いたくなるかもしれません。しかし、ツールチェーンが追いつくまでは、本番環境のカタログを MF2 に移行しないでください。ICU 自体の実装がドラフト／テクノロジープレビューの状態を脱しているか、使用するライブラリ（react-intl/FormatJS、i18next、vue-i18n、Lingui）が本番用の MF2 対応経路を提供しているか、TMS で往復変換できるかを確認してください。MessageFormat 1 / ICU 構文（references/icu-message-format.md に記載）を引き続き使用し、切り替えを推奨する前に採用状況を再確認してください。これは「仕様が確定したのだから、安全に使えるはず」というよくある誤診です。

---

基本ルール

エンコーディングとコンテンツモデル

• 最初から最後まで UTF-8 を使用します
• 翻訳対象の文字列を連結しないでください
• 場当たり的な書式設定ではなく、補間と ICU の複数形または選択ルールを使用します

ロケールのルーティングとフォールバック

• 有効な URL またはディープリンクでロケールが明示されている場合、そのリクエストでは明示されたロケールを優先します。ナビゲーションと正規メタデータでも維持してください（日付／数値／通貨の検出に関する詳細は、references/locale-handling.md を参照してください）
• ロケールが明示されていない場合は、認証済みのユーザー設定、保存済みの選択、対応する Accept-Language、デフォルトロケールの順にネゴシエートします
• 保存済みの設定によってロケール未指定のエントリールートからリダイレクトしてもかまいませんが、共有されたロケール明示 URL を暗黙のうちに書き換えてはいけません
• 必ずフォールバックロケールを定義します
• インデックス登録可能な英語以外のルートで、英語に暗黙のうちにフォールバックしてはいけません
• メタデータ、パンくずリスト、JSON-LD、表示される文言は、すべて同じロケールに統一します

翻訳ワークフロー

• キーは手作業でコピーせず、抽出します
• 名前空間の構造を安定させます
• 翻訳者向けのコンテキスト、用語集のルール、レビューゲートを追加します。抽出／TMS／CI パイプラインのパターンについては references/translation-workflows.md を、TM、用語集、規模拡大時のコストに関するパターンについては references/content-management-patterns.md を参照してください
• ハードコードされた文字列の検出とキーの不足チェックを CI で実行します

RTL とアクセシビリティ

• CSS の論理プロパティを使用します
• 必要に応じて dir="rtl" を設定します
• 実際の RTL コンテンツでテストします。アラビア語／ヘブライ語／ペルシア語に特有のパターンについては、references/rtl-support.md を参照してください
• ロケールごとに BiDi の処理、アイコン、スクリーンリーダーの動作を確認します

---

本番リリースのゲート

ゲート	失敗条件	対処方法
言語の混在した出力	ロケールに応じたページに、別のロケールのキーが表示される	マージ前に、キーの不足を検出する CI チェックを実施します
キー不足の漏出	主要な UX やマーケティングのルートに、キー ID またはフォールバック文字列がそのまま表示される	CI パイプラインで抽出結果とカタログを差分チェックします
リリース経路での機械翻訳	用語集、トーン、レビューチェックを経ずに MT の出力が挿入される	顧客に表示されるすべてのロケールに対して、人によるレビュー工程を追加します
ロケール切り替えで状態が失われる、またはナビゲーションが壊れる	ユーザーがロケールを変更すると、カート、フォーム、またはルートの状態が失われる	ロケールの状態を一元管理し、ルート／Cookie とは分離します
視覚検証なしでの RTL リリース	リリース時にアラビア語／ヘブライ語／ペルシア語のレイアウトが崩れている	リリース前に、少なくとも 1 つの RTL ロケールで視覚チェックに合格することを必須にします
ローカライズによるアクセシビリティの低下	ロケールの変更により、言語／方向のマークアップ、スクリプトの表示、またはテキスト入力が壊れる	references/accessibility-i18n.md の i18n アクセシビリティ項目をテストし、法的適用性に関する判断はアクセシビリティ担当者に引き継ぎます

既知の落とし穴

落とし穴	防止策
抽出、TMS、ランタイム間でキーがずれている — フォールバックは「機能」しているように見えるが、ロケールが壊れている	CI でキー不足をチェックし、リリース前に抽出結果と TMS カタログを差分チェックします
表示文字列は翻訳されているが、検証メッセージ／メタデータ／メール／JSON-LD が英語のままになっている	プロジェクト開始時にすべてのロケール対象（UI、メール、SEO、法務）を列挙し、それぞれを個別のテストゲートとして扱います
文法や性別に配慮が必要な文言に文字列連結を使っている	ICU の {count, plural, ...}／{gender, select, ...}（または vue-i18n のパイプ複数形など、ライブラリ独自の複数形構文）を使います。"Hello " + name は決して使わないでください
ラテン文字のロケールしかテストしていない	「完了」とする前に、長い文字列を使うロケール（de／ru）を 1 つ、非ラテン文字のロケール（ja／ar）を 1 つ必須にします
優先順位のルールがないまま、ルート、Cookie、クライアントの状態でロケールが個別に永続化されている	解決ルールを分けます。リクエストには明示的な URL／ディープリンクのロケールを使い、それ以外の場合は、認証済みのユーザー設定 > 永続化された選択 > 対応する Accept-Language > デフォルトの順にします
用語集やレビューなしで機械翻訳をリリースしている	顧客に表示されるすべてのコンテンツに、用語集、トーンルール、人によるレビューチェックを必須にします
複数形のカテゴリー数を記憶に頼っている（例：「フランス語は英語と同じで one／other の 2 つだけ」）	CLDR は言語ごとのカテゴリー数を随時改定しています（フランス語は現在 one, many, other です）。最新の CLDR 複数形ルール一覧で確認し、以前のプロジェクトの情報に基づいてハードコードしないでください
CSP／Trusted Types がない状態で、翻訳コンテンツを生の HTML（v-html、dangerouslySetInnerHTML、ICU HTML タグ）としてレンダリングしている	vue-i18n（CVE-2025-53892）と Angular の i18n パイプライン（CVE-2026-27970）の両方で、このパターンに関する XSS 勧告が実際に出ています。翻訳ファイルへの書き込みアクセスは特権として扱い、パッチ適用済みのライブラリバージョンを固定してください

よくあるアンチパターン

アンチパターン	正しいアプローチ
ロケールに応じたページで、暗黙のフォールバックとして英語を使う	デフォルト以外のロケールでキーが不足している場合、CI またはプレビューで明確に失敗させます
翻訳キーにビジネスロジックを含める	キーは UI テキストを表します。ビジネスロジックはコードに記述します
開発者の都合で翻訳を分割する	安定した製品ドメインとランタイムの読み込み境界に基づいて分割します
RTL 対応のために CSS の方向指定プロパティ（left、right）をビューごとに修正する	最初から CSS の論理プロパティ（inline-start、inline-end）を使います
製品の各領域（マーケティング、サポート、製品）で別々のロケールロジックを実装する	フォールバック、フォーマット、検出を共通のロケールレイヤーに一元化します

運用手順書

大規模なロケールカタログや言語混在インシデントに対応する場合：

• まずキーを差分チェックします
• 次に翻訳します
• マーケティングと SEO のロケール不足はリリースを阻止する要因として扱います
• 大きなロケールファイルは一度に読み込まず、分割します

詳細なトリアージ手順については、references/ops-runbook.md を参照してください。

ナビゲーション

主要なリファレンス

• references/framework-guides.md
• references/icu-message-format.md
• references/translation-workflows.md
• references/rtl-support.md
• references/locale-handling.md
• references/testing-i18n.md
• references/accessibility-i18n.md
• references/content-management-patterns.md
• references/ops-runbook.md
• references/backend-generated-content-i18n.md — ローカライズされたクライアント向けのバックエンド生成文章（ロケール別に生成するか、キャッシュ後に翻訳するか）、ロケールの契約、ネイティブカタログの同等性

テンプレートとデータ

• assets/react-i18next-setup.md
• assets/vue-i18n-setup.md
• assets/nextjs-i18n-setup.md
• data/sources.json

メンテナンス

• python3 scripts/check_urls.py
• python3 scripts/check_examples.py

関連スキル

• software-frontend
• marketing-seo
• software-accessibility

学びのループ

過去の決定事項や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または代替として利用できる場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

内容を適用した後、記憶しておく価値のあるパターン、防止すべきミス、意外だった分野の事実に気付いた場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを learnings.md に1件追加してください。SKILL.md 自体は変更しないでください。