JSON Translation Files

Format, editor, and workflow for the de-facto translation format in the JavaScript ecosystem.

JSON (.json) is the default translation file format for i18next, react-intl, vue-i18n, next-i18next, and most JavaScript / TypeScript frameworks. A JSON translation file maps translation keys to translated strings, typically with one file per language per namespace (e.g. en/common.json, de/common.json). JSON works in two structural styles — nested (object hierarchy) and flat (dot-separated keys) — both reachable via t("label.cancel") in i18next. For pluralization, modern projects use the i18next JSON v4 format, which uses CLDR plural-form suffixes (_one, _other, _few, etc.). For a deeper editor + workflow guide, see How to open and edit JSON translation files.

Key facts

What it is: JSON-formatted key/value translation file
File extensions: .json, .json5
Encoding: UTF-8 (always)
Structures: nested (objects) or flat (dot-separated keys)
Plurals (i18next v4): CLDR suffixes — _one, _other, _few, _many, _zero
Used by: i18next, react-i18next, next-i18next, vue-i18n, angular-i18next, FormatJS / react-intl, svelte-i18n, Lingui, and most JS / TS i18n libraries

Nested vs flat JSON

Nested JSON uses object structure to organize keys hierarchically. It is cleaner in source, easier to navigate visually, and the most common style in i18next projects:

{
  "appName": "My App",
  "label": {
    "cancel": "Cancel",
    "save": "Save"
  },
  "greeting": "Hello, {{name}}!",
  "items_one": "You have one item.",
  "items_other": "You have {{count}} items."
}

Flat JSON uses dot-separated keys without nesting. Translators in spreadsheets find this easier; the values stay reachable via t("label.cancel") in i18next exactly as before:

{
  "appName": "My App",
  "label.cancel": "Cancel",
  "label.save": "Save",
  "greeting": "Hello, {{name}}!",
  "items_one": "You have one item.",
  "items_other": "You have {{count}} items."
}

Both formats are equivalent at runtime — i18next resolves keys the same way. Pick one and stay consistent across files. Locize imports both styles.

i18next JSON v3 vs v4

The i18next JSON format has two versions, distinguished by how plurals are encoded:

JSON v3 (legacy, pre-i18next 21): plural keys use _plural, _0, _1, _2 suffixes — a custom pre-CLDR scheme.
JSON v4 (current, i18next 21+): plural keys use CLDR plural-form suffixes — _one, _other, _few, _many, _zero. The i18next runtime auto-selects the right form based on language and count.

For new projects, use v4. For existing v3 projects, the i18next-v4-format-converter tool migrates v3 files to v4.

Editing JSON translation files

Code editors (VS Code, Sublime Text, IntelliJ): built-in JSON validation, auto-formatting (Shift+Alt+F in VS Code), and linting catch trailing commas and missing quotes. Plugins like i18n Ally surface translation status across languages without leaving the editor.
Cloud TMS platforms: Locize imports both .json and .json5. Translators work in a CAT-style UI with translation memory and glossary, the export round-trips back to JSON for the build.
Online editors: translate.i18next.com handles simple cases for free.
Online JSON validators: JSONLint for spot-checking or pasting in problematic files.

Common JSON translation workflows

i18next / react-i18next / next-i18next. One JSON file per language per namespace. Add a new language by creating a {lng}/{ns}.json tree, copy keys from the default, translate values.
SaveMissing & CDN delivery. With i18next-locize-backend and saveMissing: true, new keys flow into Locize automatically as developers write them. Translations sync back via CDN — no rebuilds needed.
Translator handoff. Export JSON to a TMS, translate, import back. The TMS preserves keys and structure across the round-trip.
Migrating to v4. If your project still uses i18next JSON v3, run i18next-v4-format-converter across all locale files to update plural suffixes.

How to translate JSON files in Locize

Locize imports and exports .json and .json5files in both nested and flat styles, supporting i18next JSON v3 and v4 plural conventions:

Get started
Import your .json file
Edit translations in the CAT view with translation memory, glossary, and style guide applied automatically
Use bulk actions for AI / machine translation, then route results through a review workflow
Export back to JSON — or convert to YAML, gettext, XLIFF, or any other supported format. For runtime delivery without redeploying, use the Locize CDN directly via i18next-locize-backend.

For a deeper guide to opening, validating, and editing JSON translation files including editor recommendations, see How to open and edit JSON translation files.

Frequently asked questions

What is a JSON translation file?

A JSON translation file (.json) is a plain-text file that maps translation keys to translated strings as JSON key/value pairs. It is the default translation format for i18next, react-intl, vue-i18n, next-i18next, and most JavaScript / TypeScript frameworks. Each language typically has its own .json file (e.g. `en/common.json`, `de/common.json`).

What is the difference between nested and flat JSON?

Flat JSON uses dot-separated keys: `"label.cancel": "Cancel"`. Nested JSON uses object structure: `{"label": {"cancel": "Cancel"}}`. Both reach the same value via `t("label.cancel")` in i18next. Flat is easier for translators in spreadsheets; nested is cleaner in source. Pick one and stay consistent — Locize and i18next support both.

What is the i18next JSON v4 format?

i18next JSON v4 (introduced in i18next v21.0.0) uses CLDR plural-form suffixes — `key_one`, `key_other`, `key_few`, `key_many`, `key_zero` — instead of the older `_plural` / `_0` / `_1` suffixes from v3. v4 is the current default; the i18next library auto-selects the right form based on language and count.

How do I edit JSON translation files?

Any code editor opens .json files (VS Code with built-in JSON validation is the common choice). For team workflows use a translation management system that imports JSON — Locize imports and exports both .json and .json5 — so translators work in a CAT-style UI without seeing JSON syntax.

Does JSON support comments?

Standard JSON does not support comments. JSON5 is an extended dialect that does — Locize supports both `.json` and `.json5` files. For projects that need comments alongside translations, JSON5 is a practical option; for projects that need comments and richer features, consider gettext .po, Fluent .ftl, or YAML.

How do plurals work in JSON for i18next?

In i18next JSON v4, define one key per plural form using CLDR suffixes: `items_one: "1 item"`, `items_other: "{{count}} items"`. At runtime call `t("items", { count: 5 })` — i18next picks the right key based on count and the active language's plural rules. Languages like Russian or Arabic have more forms (one/few/many/other) than English (one/other).

Which frameworks use JSON for translations?

i18next (the JavaScript i18n framework), react-i18next, next-i18next, vue-i18n (when configured for JSON), angular-i18next, svelte-i18n, react-intl / FormatJS (often), Lingui, and most modern JavaScript / TypeScript i18n libraries. JSON is the de-facto translation format in the JavaScript ecosystem.

Translate JSON without redeploying for typos.

Import, edit with translation memory, glossary and AI, review, and ship via CDN — all in one place.

Start free trial