フラット vs ネストi18nキー：メリット、デメリット、使い分け

フラット vs ネストi18nキー

翻訳ファイルは2つの基本的な方法で整理できます：フラット（すべてのキーがルートレベル）とネスト（キーが階層的なオブジェクトにグループ化）。この構造的な選択は、ローカリゼーションワークフローのあらゆる側面に影響します。

フラットキー

{
  "common.buttons.submit": "Submit",
  "common.buttons.cancel": "Cancel",
  "pages.home.title": "Welcome",
  "pages.home.subtitle": "Get started today"
}

利点：

• grepやIDE検索でのシンプルな検索（すべてのキーが単一の文字列）
• マージ時に親オブジェクトを誤って上書きするリスクがない
• 合計キー数のカウントと翻訳進捗の追跡が容易
• Java Properties、PO/gettext、XLIFF形式とネイティブに互換

欠点：

• 長いキーが繰り返しになり冗長
• 関連キー間の階層的関係が見にくい
• ファイルが急速に増大し、視覚的にスキャンしにくくなる

ネストキー

{
  "common": {
    "buttons": {
      "submit": "Submit",
      "cancel": "Cancel"
    }
  },
  "pages": {
    "home": {
      "title": "Welcome",
      "subtitle": "Get started today"
    }
  }
}

利点：

• コンパクトでDRY -- 共通のプレフィックスが繰り返されない
• 明確な視覚的階層により関連する翻訳の検索が容易
• コンポーネントやページ構造への自然なマッピング
• ほとんどのモダンi18nライブラリでネイティブサポート

欠点：

• 兄弟キーの変更が同じJSONオブジェクトに影響するため、Gitマージコンフリクトが発生しやすい
• 既存のキーパス配下にスカラー値を誤ってネストするリスク
• 一部のCIツールはネスト深度によってキーのカウント方法が異なる

フォーマット互換性

• JSON -- フラットとネストの両方をサポート
• YAML -- 自然にネストだがフラットも可能
• Java Properties -- フラットのみ
• XLIFF / PO -- フラットのみ（キーバリューペア）
• TypeScript -- オブジェクトリテラルで両方サポート