localize

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

ローカライズパイプライン

ローカライズは単なる翻訳ではありません。あらゆる言語や地域でゲームを自然に感じられるようにするための、包括的なプロセスです。ローカライズが不十分だと、没入感が損なわれ、プレイヤーが混乱し、プラットフォーム認証の妨げになります。このスキルでは、文字列の抽出から文化的レビュー、VO の収録、RTL レイアウトのテスト、ローカライズ QA の承認まで、一連のパイプラインを網羅します。

モード：

• scan — ハードコードされた文字列とローカライズのアンチパターンを検出します（読み取り専用）
• extract — 文字列を抽出し、翻訳用のテーブルを生成します
• validate — 翻訳の完全性、プレースホルダー、長さを確認します
• status — すべてのロケールのカバレッジマトリックスを表示します
• brief — 外部チーム向けに翻訳者用のコンテキスト説明ドキュメントを生成します
• cultural-review — 文化的に配慮が必要な内容、シンボル、色、慣用表現を指摘します
• vo-pipeline — 音声ローカライズを管理します：台本、収録仕様、統合
• rtl-check — RTL 言語のレイアウト、ミラーリング、フォントサポートを検証します
• freeze — 文字列の凍結を適用します。翻訳開始前にソース文字列をロックします
• qa — リリース前にローカライズ QA サイクル全体を実行します

サブコマンドが指定されていない場合は、使用方法を出力して終了します。判定：FAIL — 必須のサブコマンドがありません。

---

すべての AskUserQuestion 呼び出しは .claude/docs/automation-modes.md に従います （collaborative は常に確認 · guided は主要な場合のみ確認 · autonomous は記録して続行； automation_always_ask のカテゴリでは常に確認を求めます）。

Phase 2A: Scan モード

ハードコードされたユーザー向け文字列を、コードルート（.claude/docs/code-root-resolution.md に従って解決）内で検索します。コードルートが解決できない場合、ヒット数をゼロとするのではなく、NOT ASSESSED — code root unresolved と報告してください。 未解決のルートからのゼロ件という結果は「ローカライズ対象がない」と受け取られますが、これこそがこのチェックで防ぐ失敗です。

• UI コード内にあり、ローカライズ関数（tr()、Tr()、NSLocalizedString、GetText など）でラップされていない文字列リテラル
• パラメーター化すべき連結文字列
• 名前付きのもの（{playerName}）ではなく、位置指定のプレースホルダー（%s、%d）を含む文字列
• ロケールに応じた書式設定を使わず、ロケール依存のデータ（数値、日付、通貨）が混在する書式文字列

ローカライズのアンチパターンを検索します。

• ロケール対応の関数を使用していない日時の書式設定
• ロケールを考慮していない数値の書式設定（1,000 と 1.000 など）
• 画像やテクスチャに埋め込まれたテキスト（assets/ 内のアセットファイルを指摘）
• 左から右へのテキスト方向を前提とした文字列（配置、文字列の組み立て順序）
• 文字列のロジックに組み込まれた性別・複数形の前提（複数形や性別トークンを使用する必要があります）
• ハードコードされた句読点（例："You won!" — 感嘆符の使い方はロケールによって異なります）

すべての指摘事項を、ファイルパスと行番号とともに報告します。このモードは読み取り専用です。ファイルは書き込みません。

---

Phase 2B: Extract モード

• すべてのソースファイルをスキャンし、ローカライズされた文字列の参照を探します
• assets/data/strings/ 内の既存の文字列テーブルと比較します
• キーがまだ割り当てられていない文字列の新しいエントリーを生成します
• 次の規則に従ってキー名を提案します：[category].[subcategory].[description]
  • 例：ui.hud.health_label、dialogue.npc.merchant.greeting、menu.main.play_button
• 新しいエントリーにはそれぞれ context フィールドが必要です。翻訳者向けのコメントとして、以下を説明します：
  • 表示される場所（どの画面、どのシーン）
  • 最大文字数
  • プレースホルダーの意味（{playerName} = プレイヤーが選択した表示名）
  • 該当する場合は、性別・複数形に関するコンテキスト

文字列テーブルに追加する新しい文字列の差分を出力します。

差分をユーザーに提示します。次のように質問します：「これらの新しいエントリーを assets/data/strings/strings-en.json に書き込んでもよいですか？」

はいの場合は、全体を置き換えず、新しいエントリーのみの差分を書き込みます。判定：COMPLETE — 文字列を抽出して書き込みました。

---

Phase 2C: 検証モード

assets/data/strings/ 内のすべての文字列テーブルファイルを読み込みます。各ロケールについて、次の項目を確認します。

• 完全性 — ソース（en）にキーが存在するものの、このロケールの翻訳がない
• プレースホルダーの不一致 — ソースに {name} があるが、翻訳では省略されている、または余分なプレースホルダーが追加されている
• 文字列長の違反 — 翻訳が、ソースの context フィールドに記録されている文字数制限を超えている
• 複数形の形式数 — ロケールで N 個の複数形が必要だが、翻訳の形式数が足りない
• 孤立したキー — 翻訳は存在するが、コードルート内でそのキーを参照している箇所がない
• 古い翻訳 — 翻訳の作成後にソース文字列が変更されている（再翻訳が必要としてフラグを付ける）
• エンコーディング — 非 ASCII 文字が含まれており、フォントアトラスがそれらをサポートしている（不確かな場合はフラグを付ける）

検証結果は、ロケールと重大度ごとにまとめて報告します。このモードは読み取り専用です。ファイルは書き込みません。

---

Phase 2D: ステータスモード

• ソーステーブル内のローカライズ可能な文字列の合計数を数えます
• ロケールごとに、翻訳済み、未翻訳、古い（翻訳後にソースが変更された）文字列の数を数えます
• カバレッジマトリクスを生成します。

## Localization Status
Generated: [Date]
String freeze: [Active / Not yet called / Lifted]

| Locale | Total | Translated | Missing | Stale | Coverage |
|--------|-------|-----------|---------|-------|----------|
| en (source) | [N] | [N] | [N] | [N] | [N]% |
| [locale] | [N] | [N] | [N] | [N] | [X]% |

> **Every cell above is a count you must take from the string table — including
> the source row.** Do not pre-fill the source locale as `100%`: that asserts a
> result before counting, and on a project with no `assets/data/strings/` it
> produces a coverage report for a table that does not exist. If the string table
> is absent, the whole status output is
> **`NOT ASSESSED — no string table found`**, not a matrix of zeros with a
> confident source row.

### Issues
- [N] hardcoded strings found in source code (run /localize scan)
- [N] strings exceeding character limits
- [N] placeholder mismatches
- [N] orphaned keys
- [N] strings added after freeze was called (freeze violations)

このモードは読み取り専用です。ファイルは書き込みません。

---

Phase 2E: ブリーフモード

翻訳者向けのコンテキストブリーフィング文書を生成します。この文書は、文字列テーブルのエクスポートとともに、外部の翻訳チームまたはローカライズベンダーに送付されます。

以下を読み込みます。

• design/gdd/ — ゲームのジャンル、トーン、設定、キャラクター名を抽出します。GDD はセクションごとに読み込みます。Grep ツール（パターン ^#、コンテンツモード）で必要な見出しを探し、offset と limit を指定して該当範囲を Read します。
• assets/data/strings/strings-en.json — ソース文字列テーブル
• design/narrative/ 内の既存の設定資料またはナラティブ文書

次を生成します：production/localization/translator-brief-[locale]-[date].md

# Translator Brief — [Game Name] — [Locale]

## Game Overview
[2-3 paragraph summary of the game, genre, tone, and audience]

## Tone and Voice
- **Overall tone**: [e.g., "Darkly comic, not slapstick — think Terry Pratchett, not Looney Tunes"]
- **Player address**: [e.g., "Second person, informal. Never formal 'vous' — always 'tu' for French"]
- **Profanity policy**: [e.g., "Mild — PG-13 equivalent. Match intensity to source, do not soften or escalate"]
- **Humour**: [e.g., "Wordplay exists — if a pun cannot translate, invent an equivalent local joke; do not translate literally"]

## Character Glossary
| Name | Role | Personality | Notes |
|------|------|-------------|-------|
| [Name] | [Role] | [Personality] | [Do not translate / transliterate as X] |

## World Glossary
| Term | Meaning | Notes |
|------|---------|-------|
| [Term] | [What it means] | [Keep in English / translate as X] |

## Do Not Translate List
The following must appear verbatim in all locales:
- [Game name]
- [UI terms that match in-engine labels]
- [Brand or trademark names]

## Placeholder Reference
| Placeholder | What it represents | Example |
|-------------|-------------------|---------|
| `{playerName}` | Player's chosen display name | "Shadowblade" |
| `{count}` | Integer quantity | "3" |

## Character Limits
Tight UI fields with hard limits are marked in the string table `context` field.
Where no limit is stated, target ±30% of the English length as a guideline.

## Contact
Direct questions to: [placeholder for user/team contact]
Delivery format: JSON, same schema as strings-en.json

「この翻訳者向けブリーフを production/localization/translator-brief-[locale]-[date].md に書き込んでもよろしいですか？」と尋ねます。

---

Phase 2F: 文化的レビュー モード

Agent を介して localization-lead を起動します。対象ロケール（assets/data/strings/ と assets/ から読み込みます）全体にわたって、以下の文化的配慮について監査するよう依頼します。

レビュー対象コンテンツ

シンボルとジェスチャー

• 親指を立てる、OK サイン、ピースサイン — 意味は地域によって異なります
• アート、UI、音声に含まれる宗教的またはスピリチュアルなシンボル
• 国旗、地図の表現、係争地域

色

• 白（アジアの一部の文化では喪を表す）、緑（一部地域で政治的な連想がある）、赤（幸運か危険か）
• 文化的な連想と矛盾する警告色

数字

• 4（日本語・中国語で死を連想）、13、666 — UI での使用（部屋番号、アイテム数、価格）にフラグを付ける

ユーモアと慣用句

• 他のロケールでは不快な意味に訳される慣用句
• 一部の市場（特に日本、ドイツ、中東）では不適切なトイレ・身体に関するユーモア
• 特定の地域で文化的にセンシティブな話題を扱うブラックユーモア

暴力とコンテンツレーティング

• DE（ドイツ）、AU（オーストラリア）、CN（中国）、AE（UAE）でレーティング変更が必要となるコンテンツ
• 血の色、ゴアの程度、薬物への言及 — 必要に応じて地域別アセットのバリエーションを検討するため、すべてにフラグを付ける

名前と表現

• 対象ロケールで不快、卑猥、または否定的な意味を持つキャラクター名
• 国籍、宗教、民族に関するステレオタイプな表現

調査結果を次の表で提示します。

発見事項	影響を受けるロケール	重大度	推奨アクション
[説明]	[ロケール]	[BLOCKING / ADVISORY / NOTE]	[変更 / レビュー対象としてフラグを付ける / 承認]

BLOCKING = そのロケールでのリリース前に必ず修正します。ADVISORY = 変更を推奨します。NOTE = 情報提供のみです。

「この文化的レビューの報告書を production/localization/cultural-review-[date].md に書き込んでもよろしいですか？」と尋ねます。

---

フェーズ 2G：VO パイプラインモード

ボイスオーバーのローカライズプロセスを管理します。引数からサブタスクを判断します。

• vo-pipeline scan — VO 録音が必要なすべての台詞行を特定します
• vo-pipeline script — ディレクター向けメモ付きの録音台本を作成します
• vo-pipeline validate — 録音済みの VO ファイルがすべて存在し、正しく命名されていることを確認します
• vo-pipeline integrate — VO ファイルがコード／アセット内で正しく参照されていることを確認します

VO パイプライン：スキャン

assets/data/strings/ と design/narrative/ を読み込み、以下を特定します。

• すべての台詞行（キーが dialogue.* に一致するもの）とそのソーステキスト
• 録音済みの行（assets/audio/vo/ に音声ファイルが存在するもの）
• 未録音の行

録音マニフェストを出力します。

## VO Recording Manifest — [Date]

| Key | Character | Source Line | Status |
|-----|-----------|-------------|--------|
| dialogue.npc.merchant.greeting | Merchant | "Welcome, traveller." | Recorded |
| dialogue.npc.merchant.haggle | Merchant | "That's my final offer." | Needs recording |

VO パイプライン：台本

キャラクターごとに、シーン別にまとめた録音台本ドキュメントを作成します。以下を含めます。

• キャラクター名と簡単な性格メモ
• 珍しい固有名詞の発音ガイド付きの台詞全文
• 各行の感情／演技指示（[Warm, welcoming]、[Annoyed, clipped]）
• 会話への返答となる行（文脈を提示します：「プレイヤーがたった今 X と言った」）

「VO 録音台本を production/localization/vo-scripts-[locale]-[date].md に書き込んでもよいですか？」と確認します。

VO パイプライン：検証

assets/audio/vo/[locale]/ 内のすべての .wav／.ogg ファイルを Glob で検索します。VO マニフェストと照合し、以下を報告します。

• ファイルの欠落（台本に行があるが、音声ファイルがない）
• 余分なファイル（音声ファイルは存在するが、一致する文字列キーがない）
• 命名規則違反

VO パイプライン：統合

コードルート内で VO 音声への参照を Grep します。参照されている各パスが assets/audio/vo/[locale]/ に存在することを確認します。壊れた参照を報告します。

---

フェーズ 2H：RTL チェックモード

右から左に記述する言語（アラビア語、ヘブライ語、ペルシア語、ウルドゥー語）では、 テキストを翻訳するだけでなく、レイアウトを反転する必要があります。このモードでは実装を検証します。

エンジンを特定します。project.yaml から engine.name を読み込みます。そのキーが存在しないか空の場合（project.yaml に engine: ブロックがない場合も含む）は、.claude/docs/technical-preferences.md を参照します。その後、以下を確認します。

レイアウトの反転

• エンジンで RTL レイアウトが有効になっていますか？（Godot：Control.layout_direction、Unity：RTL Support パッケージ、Unreal：テキスト方向フラグ）
• すべての UI コンテナーが自動反転に設定されていますか、それとも位置がハードコードされていますか？
• プログレスバー、ヘルスバー、方向インジケーターは正しく反転しますか？

テキストの描画

• アラビア語／ヘブライ語の文字セットに対応したフォントが読み込まれていますか？
• アラビア語テキストは正しい合字（文字がつながった書体）で描画されていますか？
• 必要な場合、数字は東アラビア数字で表示されていますか？

文字列の組み立て

• 左から右への読み順を前提とした文字列連結はありませんか？
• 文の構造が逆になる場合でも、文中の {placeholder} の位置は正しく機能しますか？

アセットの確認

• 方向を示す矢印や非対称なデザインを含み、反転版が必要な UI アイコンはありますか？
• RTL 版が必要な、画像内テキストを含むアセットはありますか？

確認する Grep パターン：

• シーン／プレハブファイル内のエンジン固有の RTL フラグ
• HBoxContainer、LinearLayout、HorizontalBox ノード — layout_direction の設定を確認します
• 台詞または UI コード付近での + による文字列連結

調査結果を報告します。修正しないとコンテンツが読めない問題は BLOCKING、見た目の改善に関するものは ADVISORY として分類します。

「この RTL チェックレポートを production/localization/rtl-check-[date].md に書き込んでもよいですか？」と確認します。

---

フェーズ 2I：凍結モード

文字列の凍結により、ソース（英語）の文字列テーブルをロックし、翻訳者が作業中にソースが変更されないようにします。

フリーズの実施

production/localization/freeze-status.md が存在する場合は、現在のフリーズ状況を確認します。

すでにフリーズされている場合：

"文字列フリーズは現在有効です（実施日：[date]）。フリーズ後に[N]個の文字列が追加または変更されています。これらはフリーズ違反であり、再翻訳または承認済みのフリーズ解除が必要です。"

フリーズされていない場合は、フリーズ前のチェックリストを提示します：

Pre-Freeze Checklist
[ ] All planned UI screens are implemented
[ ] All dialogue lines are final (no further narrative revisions planned)
[ ] All system strings (error messages, tutorial text) are complete
[ ] /localize scan shows zero hardcoded strings
[ ] /localize validate shows no placeholder mismatches in source (en)
[ ] Marketing strings (store description, achievements) are final

AskUserQuestion を使用します：

• 質問："今すぐ文字列フリーズを実施しますか？この操作により production/localization/freeze-status.md（Status: ACTIVE）が書き込まれ、ソーステーブルがロックされます。"
• 選択肢：[A] はい — 今すぐ文字列フリーズを実施する / [B] いいえ — まだ追加する文字列がある

[A] の場合：production/localization/freeze-status.md を書き込みます：

# String Freeze Status

**Status**: ACTIVE
**Called**: [date]
**Called by**: [user]
**Total strings at freeze**: [N]

## Post-Freeze Changes
[Any strings added or modified after freeze are listed here automatically by /localize extract]

フリーズの解除

引数に lift が含まれる場合は、「freeze-status.md を LIFTED に更新してもよいですか？」と尋ねてから、Status を LIFTED に設定し、理由と日付を記録します。警告：「フリーズを解除すると、変更されたすべての文字列を再翻訳する必要があります。翻訳チームに通知してください。」

フリーズチェック（extract に自動統合）

extract モードで新規または変更された文字列が見つかり、freeze-status.md の Status が ACTIVE の場合は、extract 自身の「May I write」質問に freeze-status.md を含め、承認されたら新しいキーをそのファイルの ## Post-Freeze Changes に追加して、次の警告を表示します：

"⚠️ 文字列フリーズは有効です。新規または変更された文字列が[N]個追加されています。これらはフリーズ違反です。続行する前にローカライズベンダーに通知してください。"

---

フェーズ 2J：QA モード

ローカライズ QA は、翻訳の納品後、ロケールをリリースする前に実施する専用の確認作業です。これは /localize validate（完全性を確認するもの）とは異なり、実際のプレイを通じて品質を構造的に確認します。

Agent を介して localization-lead を起動し、以下を渡します：

• QA 対象のロケール
• ゲーム内のすべての画面／フローの一覧（design/gdd/ または /content-audit の出力から取得）
• 現在の /localize validate レポート
• 文化的レビューのレポート（存在する場合）

以下を網羅する QA 計画を作成するよう localization-lead に依頼します：

1. 機能面の文字列チェック — すべての文字列が、切り詰め、プレースホルダーエラー、文字化けなしにゲーム内で表示されること
2. UI はみ出しチェック — UI の範囲を超える翻訳文字列を確認します（文字数制限内でも、言語によっては文字列が長くなる場合があります）
3. 文脈上の正確性 — 文字列の10％をサンプルとしてゲーム内で確認し、翻訳の正確さと自然な言い回しを検証します
4. 文化的レビュー項目 — 文化的レビューで BLOCKING とされた項目がすべて解決済みであることを確認します
5. VO 同期チェック — VO がある場合は、翻訳後のリップシンクまたは字幕タイミングが適切であることを確認します
6. プラットフォーム認証要件 — プラットフォーム固有のローカライズ要件（年齢レーティングのテキスト、法的通知、ESRB／PEGI／CERO のテキスト）を確認します

ロケールごとに QA 判定を出力します：

## Localization QA Verdict — [Locale]

**Status**: PASS / PASS WITH CONDITIONS / NOT ASSESSED / FAIL
**Reviewed by**: localization-lead
**Date**: [date]

### Findings
| ID | Area | Description | Severity | Status |
|----|------|-------------|----------|--------|
| LOC-001 | UI Overflow | "Settings" button text overflows on [Screen] | BLOCKING | Open |
| LOC-002 | Translation | [Key] translation is literal — sounds unnatural | ADVISORY | Open |

### Conditions (if PASS WITH CONDITIONS)
- [Condition 1 — must resolve before ship]

### Sign-Off
[ ] All BLOCKING findings resolved
[ ] Producer approves shipping [Locale]

最初に該当した判定を適用します：BLOCKING の指摘が未解決であれば FAIL、確認を実施できなかった項目があれば NOT ASSESSED。各確認項目はプレイを通じて実施するため、ゲーム内で誰もプレイしていないロケール（または翻訳が納品されていないロケール）は、文字列テーブルだけでは合格にできません。未実施の確認項目をそれぞれ明記してください。それ以外で条件が残っていれば PASS WITH CONDITIONS、そうでなければ PASS とします。NOT ASSESSED は両方の合格判定より優先されます。未プレイのロケールは合格していないためです。また、FAIL よりは下位となるため、未解決の BLOCKING の指摘が見過ごされることはありません。

次のように尋ねます：「このローカライズ QA レポートを production/localization/loc-qa-[locale]-[date].md に書き込んでもよいですか？」

ゲートへの統合：workflow: full では、翻訳対象としてリリースする各ロケールについて、Polish → Release ゲートで PASS または PASS WITH CONDITIONS の判定が必要です（standard では推奨、minimal では省略）。FAIL の場合、そのロケールのみリリースがブロックされます。他のロケールは QA に合格していれば続行できます。NOT ASSESSED のロケールは合格していません。QA が実施されていないためです。

---

フェーズ 3：ルールと次のステップ

ルール

• 英語（en）を常にソースロケールとします
• すべての文字列テーブル項目に、翻訳者向けの注記、文字数制限、プレースホルダーの意味を含むcontextフィールドを含める必要があります
• 翻訳ファイルを直接変更しないでください。レビュー用に差分を生成してください
• 文字数制限はUI要素ごとに定義し、検証モードで適用する必要があります
• 文字列を翻訳者に送る前に、必ず文字列凍結を実施してください。変更中の内容を翻訳してはいけません
• RTL対応は最初から設計に組み込む必要があります。RTLレイアウトの後付けはコストがかかります
• ゲームを商業販売するすべてのロケールで、カルチャーレビューが必要です
• VOスクリプトにはディレクター向けの注記を含める必要があります。台詞だけでは平坦な録音になります

推奨ワークフロー

/localize scan            → find hardcoded strings
/localize extract         → build string table
/localize freeze          → lock source before sending to translators
/localize brief           → generate translator briefing document
[Send to translators]
/localize validate        → check returned translations
/localize cultural-review → flag culturally sensitive content
/localize rtl-check       → if shipping Arabic / Hebrew / Persian
/localize vo-pipeline     → if shipping dubbed VO
/localize qa              → full localization QA pass

出荷する翻訳済みロケールごとに、qaがPASSまたはPASS WITH CONDITIONSを返した後、/gate-check releaseの実行時にQAレポートのパスを含めてください。