Flat JSON file (.json)

JSON (JavaScript Object Notation) is a lightweight data-interchange file format. It has become increasingly popular in the localization industry due to its easy-to-read and write structure, its ability to represent a wide range of data types, and its support for Unicode.

Storing localization data in JSON files can be done in various ways. The most straightforward way is using a Flat JSON (also known as Key-Value JSON) structure. Here, the localization data is represented as a collection of key-value pairs within the JSON file, where each key represents a message identifier and the value a corresponding translation.

Flat JSON example

{
  "common.ok": "OK",
  "common.next": "Next",
  "common.previous": "Previous",
  "page.home.title": "Welcome",
  "page.home.subtitle": "Glad to see you again"
}

Many popular localization libraries have adopted flat JSON as their preferred method for storing localization data. Below you can find examples of some well-known localization libraries that use such data structure.

Below, you can find a sample JSON file for the react-intl localization library.

React-Intl JSON example

{
  "common.ok": "OK",
  "common.next": "Next",
  "common.previous": "Previous",
  "common.device": "{device, select, mobile {Mobile} desktop {Desktop} other {Other}}",
  "common.title-name": "{gender, select, male {Mr. {name}} female {Ms. {name}} other {{name}}}",
  "common.formatted-date": "{currDate, date, medium}",
  "common.formatted-number": "{num, number, ::compact-short}",
  "common.items-counter": "{count, plural, one {{count} item} other {{count} items}}",
  "page.home.title": "Welcome",
  "page.home.subtitle": "Glad to see you {name}"
}

The react-intl library supports ICU Message syntax and offers a vast range of formatting options.

Below, you can find a sample JSON file for the vue-intl localization library.

Vue-Intl JSON example

{
  "common.ok": "OK",
  "common.next": "Next",
  "common.previous": "Previous",
  "common.device": "{device, select, mobile {Mobile} desktop {Desktop} other {Other}}",
  "common.title-name": "{gender, select, male {Mr. {name}} female {Ms. {name}} other {{name}}}",
  "common.formatted-date": "{currDate, date, medium}",
  "common.formatted-number": "{num, number, ::compact-short}",
  "common.items-counter": "{count, plural, one {{count} item} other {{count} items}}",
  "page.home.title": "Welcome",
  "page.home.subtitle": "Glad to see you {name}"
}

The vue-intl library supports ICU Message syntax and offers a vast range of formatting options.

What are the main benefits of using flat JSON localization files?

Flat JSON files provide a simple and easy-to-manage structure for storing and updating localization messages. They can accommodate more advanced message types, such as gender, select, and plural messages, while still maintaining a flat structure.

How can I validate the syntax of a flat JSON localization file?

Flat JSON files used in software localization are regular JSON files. As such, they can be easily validated using various tools that are available on the internet, in code editors, or in specialized localization tools. The most common errors are missing commas and unclosed quotation marks.

How can I handle placeholders in flat JSON files?

Handling placeholders in flat JSON localization files can depend on the localization libraries being used, as different libraries may have their own syntax and conventions for handling placeholders. However, a widely supported method is to use the ICU Message syntax, which allows placeholders to be included in messages using a simple syntax.

How can I handle pluralization and gender in flat JSON files?

Handling pluralization and gender in flat JSON localization files can depend on the localization libraries being used and the way they handle these features. However, a common way to handle these advanced message types is by using the ICU Message syntax, which is supported by many localization libraries.

How should I organize and manage multiple flat JSON files in a project?

When managing multiple flat JSON localization files in a project, it is important to organize them in a way that makes them easy to manage and maintain. One common practice is to keep all localization files in a single folder, such as a lang folder. Each file in the folder can correspond to a specific language, and contain all of the translations for that language. By using a consistent naming convention and logically organizing the files, it becomes easier to add, update, or remove translations as needed throughout the project.

project-name
|-- lang
|   |-- ar.json
|   |-- en.json
|   |-- es-MX.json
|-- src
|-- ...

Previous: Supported file formats

Tired of manually editing translation files?

Our platform streamlines software localization for you.

Try now for Free

Flat JSON file (.json)

Documentation

Flat JSON example

React-Intl JSON example

Vue-Intl JSON example

What are the main benefits of using flat JSON localization files?

How can I validate the syntax of a flat JSON localization file?

How can I handle placeholders in flat JSON files?

How can I handle pluralization and gender in flat JSON files?

How should I organize and manage multiple flat JSON files in a project?

Documentation

About

Resources

Free tools

Boring stuff

Newsletter