I18n localization

国際化(i18n)・ローカライゼーション(l10n)

目的

「後からやれば良い」という先送りが最大のコスト要因になる。海外展開の可能性が少しでもあれば最初から文字列をキー化し、フォーマット・レイアウト・翻訳ワークフローを設計する。一方で展開予定が明確にゼロなら過剰対応はしない([[mvp-development]] のトレードオフ)。

使うタイミング

• 海外ロケールへの展開を計画している・可能性がある
• ハードコードされた文字列を後付けで外部化しなければならない
• 翻訳フローが属人化していて管理できていない
• 既存i18n実装のレビュー・改善をしたい
• 新機能追加時のi18n対応方針を決めたい

進め方

1. 展開判断: 対応ロケールと優先度を決定する。「日本語のみ」「英語+日本語」「将来的にアジア圏」等、現時点の計画を明文化する
2. キー設計: 翻訳キーの命名規約を決め、既存コードのハードコード文字列を洗い出す
3. フォーマット方針の確定: 日付・数値・通貨の表示フォーマット、タイムゾーン戦略を決める
4. 複数形・変数の規約確定: ICU MessageFormat 等の標準機構を採用するか決め、文字列連結を禁止するルールを周知する
5. UIレイアウトの検証: テキスト膨張・RTL対応の要否を確認し、各ロケールでレイアウト崩れがないことを確かめる
6. 翻訳ワークフロー構築: 機械翻訳/LLM下訳 → ネイティブレビュー → 用語集更新のフローを整備する
7. CI組み込み: 未翻訳キー検出・翻訳ファイルの lint をパイプラインに追加する([[cicd-deployment]])
8. ローカライズ優先順位の決定: UI文字列 → ストア掲載文 → ヘルプ・ドキュメント → サポート対応の順で進める。全部一気にやらない

設計の要点

翻訳キーの命名規約

• 画面・機能ベースのプレフィックスを付ける: checkout.confirm_button、auth.login_error.invalid_password
• 動的な文字列は変数を含むキーで管理: search.result_count → "{count, plural, one {# 件} other {# 件}}"
• キーは英語小文字・スネークケース・ドット区切りで統一する
• UIラベルと通知メッセージなど用途が異なるものは名前空間を分ける

変数と複数形

• 文字列連結は絶対禁止: "件の" + count + "結果" は語順が言語で変わるため破綻する
• テンプレート内挿入を使う: t('search.results', { count }) → "{count} results found"
• 複数形・性数一致は ICU MessageFormat または対象フレームワークの標準機構で処理する
• 複数形パターンが多い言語(ロシア語・アラビア語等)は設計初期に考慮する

フォーマット

• 日付・時刻・数値・通貨は Intl 等のロケールAPIに委譲し、自前フォーマット実装を禁止する
• タイムゾーンはUTCで保存し、表示時にロケールのタイムゾーンへ変換する([[database-design]])
• 通貨は「金額(整数・小数の精度を保持) + 通貨コード(ISO 4217)」で保持し、表示時にフォーマットする

UIレイアウト

• テキスト膨張を見込む: 英→独は約1.3倍、日→英でも語句によっては伸びる。ボタン・ラベルの幅はフレキシブルに設計する
• RTL(アラビア語・ヘブライ語等)対応の要否を展開計画策定時に決定する。後から追加すると改修コストが高い
• CJK(中国語・日本語・韓国語)フォントの指定漏れに注意する([[screen-design]])
• 英語のみのスクリーンショットでレイアウト確認を完了させない

翻訳ワークフロー

• 機械翻訳/LLMによる下訳 → ネイティブレビュー → 本番投入の3ステップを守る
• 翻訳者へのコンテキスト提供: スクリーンショット・文字数制限・用語集・前後の文脈を必ず共有する
• 用語集(glossary)を管理し、製品固有の名称・動詞の訳語を統一する
• 翻訳ファイルはコードと同じくレビュー対象とし、PRに含める
• フォールバック言語(通常は英語)を設定し、未翻訳キーが直接表示されないようにする

法規制

• 対象国の特商法相当の表記・プライバシーポリシーの現地語対応が必要な場合がある([[legal-compliance]])

成果物テンプレート

i18n設計シート

## i18n設計シート

### 対応ロケールと優先度
| ロケール | 言語 | 優先度 | 対応フェーズ |
|----------|------|--------|------------|
| ja       | 日本語 | P0   | Phase 1    |
| en       | 英語   | P0   | Phase 1    |
| zh-TW    | 繁体字中国語 | P1 | Phase 2 |

### キー命名規約
- プレフィックス: <画面名>.<コンポーネント名>.<要素>
- 例: `checkout.order_summary.total_label`
- 名前空間: `common`(共通)、`<feature>`(機能別)

### 変数・複数形の規約
- テンプレートエンジン: ICU MessageFormat
- 変数形式: `{variableName}`
- 複数形: `{count, plural, one {# item} other {# items}}`
- 文字列連結: 禁止(eslint-plugin-i18n 等で強制)

### フォーマット方針
- 日付: `Intl.DateTimeFormat` / ライブラリの locale オプション
- 数値: `Intl.NumberFormat`
- 通貨: `Intl.NumberFormat` + ISO 4217 通貨コード
- タイムゾーン: UTC保存 / 表示時変換

### RTL対応
- 要/不要: [要/不要]
- 対象言語: [アラビア語 / ヘブライ語 / 等]

### 翻訳フロー
1. 開発者が英語キーを追加してPRをマージ
2. LLMによる下訳を生成
3. ネイティブレビュアーが確認・修正
4. 翻訳ファイルをPRで追加・レビュー
5. CI で未翻訳キー検出 → ブロック

### 用語集の場所
- リポジトリ: `docs/i18n/glossary.md`
- 管理ツール: [Crowdin / Lokalise / スプレッドシート 等]

### フォールバック言語
- デフォルト: `en`

チェックリスト

• 対応ロケールと優先度を決定・文書化したか
• 翻訳キーの命名規約を定めたか
• 文字列連結を禁止するルール・lintルールを設定したか
• 複数形・変数はICU MessageFormat等の標準機構で処理しているか
• 日付・時刻・数値・通貨をIntl等のロケールAPIで処理しているか
• タイムゾーンをUTCで保存し表示時変換しているか
• テキスト膨張を考慮したUIレイアウトになっているか
• RTL対応の要否を決定したか
• 翻訳ファイルをコードレビューの対象に含めているか
• 未翻訳キーの検出をCIに組み込んだか
• フォールバック言語を設定したか
• 翻訳者にコンテキスト(スクリーンショット・文字数制限・用語集)を提供しているか
• 用語集を作成・管理しているか
• 対象国の法規制対応(特商法等)を確認したか

アンチパターン

• 文字列連結で文を組み立てる: "件の" + count + "結果" は語順が変わる言語で破綻する。テンプレート内挿入を使え
• コードとリソースへのハードコード混在: 翻訳キーを使わず文字列リテラルが残ると漏れが発生する。lintで検出する
• 英語のみでレイアウト確認して完了: テキスト膨張・CJKフォント・RTLで表示が崩壊する。複数ロケールで目視確認する
• 未翻訳キーをそのままユーザーに表示: checkout.total_label が画面に出るのは致命的。フォールバック言語を必ず設定する
• 機械翻訳をレビューなしで本番投入: ニュアンスのズレ・敬語の誤り・用語の不統一が発生する。ネイティブレビューを省略しない
• 全言語を同時にローカライズしようとする: リソースが分散する。優先順位をつけてフェーズを分ける
• 翻訳ファイルをレビュー対象外にする: 誤訳・キー漏れ・不整合がそのまま本番に入る

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

役割	担当	具体的な使い方
司令塔(メインモデル)	対応ロケールの判断・キー設計方針の決定・全体統合	i18n設計シートを作成し、各エージェントへタスクを割り当てる。設計の判断(RTL要否・翻訳フロー選定等)を下す
Opus相当	複雑な複数形・性数一致の文法設計・言語特有の例外対応	ICU MessageFormatのパターン設計や、スラブ語系・アラビア語の複数形ルール等の複雑な文法仕様を深く分析させる
Sonnet相当	文字列の外部化作業・翻訳ドラフト・ハードコードの洗い出しと置換	コードベースをスキャンして翻訳キーへの置換を実施。LLMによる翻訳下訳を生成。既存ファイルへのキー追加作業を担当させる
Haiku相当	ハードコード文字列の検出	grepやASTベースの静的解析でハードコード文字列を高速スキャンさせる。大量ファイルへの反復作業に適している

関連スキル

• [[orchestration]] — 多エージェント並列実行の共通原則
• [[mvp-development]] — i18n対応の優先度トレードオフ
• [[screen-design]] — テキスト膨張・RTL・CJKフォントを考慮したUI設計
• [[database-design]] — タイムゾーン・通貨の保存設計
• [[cicd-deployment]] — 未翻訳キー検出のCI組み込み
• [[legal-compliance]] — 対象国の法規制・表記要件
• [[accessibility]] — 多言語対応とアクセシビリティの交差点
• [[documentation]] — 用語集・翻訳ガイドラインの整備