JSON - Single Language

Last updated: June 17, 2022Author: Jakub Pomykała

The most basic and common JSON format for software app localization. It can be used in any kind of web projects, desktop program or game. Simple JSON object contains translation key set by a developer during program implementation process, and localized message for end user.

File format example

  "home.interface.signup": "Signup",
  "home.interface.email": "Email",
  "home.interface.password": "Password"

You can also use multi-language-json format to download all translations at once.

SimpleLocalize also recognizes nested JSON keys, as shown below.

  "home": {
    "interface": {
      "signup": "Signup",
      "email": "Email",
      "password": "Password"

Above JSON will result with:

  • home.interface.signup,
  • home.interface.email,
  • home.interface.password translation keys in Translation Editor.

Message interpolation

Pluralization and variables formatting is done by your translation library (e.g. FormatJS) You can use a {key} argument for placing a value into the message. The key is looked up in the input data, and the string is interpolated with its value.


  "home": {
      "welcome": "Hello, {name}!"

Your variable: name.


  "home": {
      "message": "I have {numCats, number} cats.",
      "notifications": "You have {itemCount, plural, =0 {no items} one {1 item} other {{itemCount} items}}."

Learn more about ICU message syntax.

Upload translation files

Upload with command-line tool

simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat single-language-json \
  --uploadPath ./translations_{lang}.json

Learn more about uploading translations with CLI.

Import with REST API

    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=single-language-json' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.json

Learn more about importing translations with API.

Download translation files

Download with command-line tool

simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat single-language-json \
  --downloadPath ./translations_{lang}.json

To download translations with nested keys use option WRITE_NESTED. See all download options.

simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat single-language-json \
  --downloadPath ./translations_{lang}.json \
  --downloadOptions WRITE_NESTED

Learn more about downloading translations with CLI.

Export with REST API

    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=single-language-json \
    --header 'x-simplelocalize-token: <API_KEY>'

Learn more about exporting translations with API.