Flat or nested JSON for translation files?

16 October 2026

Both hold the same texts. The choice is about what your i18n library expects and what your team finds easier to read.

Flat

Every key is on one level, with dots as part of the name:

{
  "checkout.title": "Checkout",
  "checkout.pay_now": "Pay now"
}

Easy to search for and to compare line by line. Fits libraries that treat the key as a plain string.

Nested

The dots become objects:

{
  "checkout": {
    "title": "Checkout",
    "pay_now": "Pay now"
  }
}

i18next and ngx-translate read nested files out of the box and look up checkout.title by walking the objects. Grouping by screen or feature also makes a large file easier to browse.

Which to choose

• Use what your library already reads. With i18next or ngx-translate, nested is the usual choice.
• i18next can read flat files too if you set keySeparator: false, which also allows dots in texts' keys without nesting.
• If you plan to nest, avoid giving a group's name a text of its own: checkout and checkout.title can't both be texts in a nested file.

In Sleekdocs Translate

Keys are stored the same way whichever format you use, and imports accept both: a nested file is read as dotted keys. The project's File format setting, JSON - Flat or JSON - Nested, decides the shape of the files you deploy and export, and the API can return either with format=flat or format=nested.