Flat vs Nested i18n Keys: Pros, Cons, and When to Use Each

Flat vs Nested i18n Keys

Translation files can be organized in two fundamental ways: flat (all keys at the root level) and nested (keys grouped into hierarchical objects). This structural choice affects every aspect of your localization workflow.

Flat Keys

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

Advantages:

• Simpler to search with grep or IDE search (every key is a single string)
• No risk of accidentally overwriting parent objects during merge
• Easier to count total keys and track translation progress
• Works natively with Java Properties, PO/gettext, and XLIFF formats

Disadvantages:

• Long keys become repetitive and verbose
• Harder to see the hierarchical relationship between related keys
• File grows quickly and becomes difficult to scan visually

Nested Keys

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

Advantages:

• Compact and DRY -- common prefixes are not repeated
• Clear visual hierarchy makes it easy to find related translations
• Natural mapping to component or page structure
• Supported natively by most modern i18n libraries

Disadvantages:

• Git merge conflicts are more common because changes to sibling keys affect the same JSON object
• Risk of accidentally nesting a scalar under an existing key path
• Some CI tools count keys differently depending on nesting depth

Hybrid Approach

Many teams use a hybrid: nested for the top two levels (namespace and category) and flat for leaf keys. This balances readability with merge safety:

{
  "common": {
    "buttons.submit": "Submit",
    "buttons.cancel": "Cancel"
  }
}

Format Compatibility

• JSON -- supports both flat and nested
• YAML -- naturally nested but can be flat
• Java Properties -- flat only
• XLIFF / PO -- flat only (key-value pairs)
• TypeScript -- supports both via object literals