JSON - SimpleLocalize

Last updated: May 22, 2025
simplelocalize-json
File format value
simplelocalize-json
List of supported file formats

SimpleLocalize JSON is a universal format that can be used to import and export translations from different localization programs. It works well with FormatJS CLI and can be used to import translations from different localization programs. Learn more about integrating FormatJS with SimpleLocalize.

File format example

Here is an example of a SimpleLocalize JSON file:

{
  "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}}."
  }
}

Metadata

The SimpleLocalize JSON format supports the following metadata:

  • message - localized message (optionally defaultMessage can be used instead)
  • description - description of the translation key
  • charactersLimit - character limit for the translation key, use -1 to remove limit
  • tags - tags for the translation key, use [] to remove tags
  • lock - lock translation modification for the given key, use false to unlock

Example SimpleLocalize JSON with metadata:

{
  "say_hi": {
    "message": "Cześć!",
    "description": "Welcome message",
    "charactersLimit": 21,
    "tags": ["my-tag-1", "my-tag-2"],
    "lock": true
  },
  "say_goodbye": {
    "message": "Do widzenia!",
    "description": "Farewell message",
    "charactersLimit": 37,
    "tags": ["my-tag-1"],
    "lock": false
  }
}

If you skip any metadata field, it won't remove the existing value in SimpleLocalize. For example, if you want to remove the description field, you need to set it to an empty string.

Export metadata

By default, SimpleLocalize JSON format does not export any additional metadata. Use export options to include metadata in the exported file. The following options are available:

  • INCLUDE_TAGS - include tags in the exported file
  • INCLUDE_LOCK_STATE - include lock status in the exported file
  • INCLUDE_CHARACTERS_LIMIT - include character limit in the exported file

Import default messages

If you want to import messages into SimpleLocalize using CLI, you need to pass a language key as an argument. The language key is used to determine the language of the imported messages. See an example CLI command below:

simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat simplelocalize-json \
  --uploadPath ./extracted.json \
  --languageKey en

Add --overwrite argument to update the existing translations, otherwise, only new ones will be added.

Import descriptions

By default, CLI imports descriptions as Code Descriptions. Use --uploadOptions UPDATE_DESCRIPTIONS parameter to push values from 'description' fields as translator descriptions. See an example CLI command below:

simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat simplelocalize-json \
  --uploadPath ./extracted.json \
  --languageKey en

Code descriptions differ from the descriptions in the translation editor. They are used to provide additional context for translators from the code perspective, and they cannot be edited or cleared in the translation editor. They are updated only by uploading new translations via CLI.

Learn more about uploading translations with CLI.

Resources

Was this helpful?