JSON - SimpleLocalize

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

The custom build JSON format for different purposes. In most cases, you would like to use it to import translation keys and localized messages from different localization programs. SimpleLocalize will discover automatically what kind of JSON library you use.

File format example

  "translation_key": {
    "message": "my localized message"
  "second_translation_key": {
    "defaultMessage": "my localized message from FormatJS CLI output",
    "description": "Your message to translators. It will also show up in the translation editor"
  "translation_key_with_pluralization": {
    "message": "You have {itemCount, plural, =0 {no items} one {1 item} other {{itemCount} items}}."

You can use simplelocalize-json format with FormatJS CLI. Check FormatJS CLI integration guide.

Import default messages as translations

To import default messages from the file, there are a few conditions that must be met to make it work:

  • You need to specify the language in your CLI command. There are two ways:
    • provide it with --languageKey en-GB or
    • provide it with --uploadPath /locales/{lang}.json.
  • If the translation already exists you need to add --uploadOptions REPLACE_TRANSLATION_IF_FOUND option otherwise the translation won't be replaced.
  • File format must be --uploadFormat simplelocalize-json.

Upload translation files

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

Learn more about uploading translations with CLI.

Download translation files

Usually, SimpleLocalize-JSON format is used only to import translation, and it's recommended to download translations as single-language-json, multi-language-json or any other file format.

All translations

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

One file with one language

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

Learn more about downloading translations with CLI.