JSON - SimpleLocalize

Last updated: August 18, 2026
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.

Namespaces

If a translation key belongs to a namespace, the exported file adds key and namespace fields to that entry, and prefixes the top-level key with namespace: so it stays unique across namespaces (JSON object keys must be unique). See example below:

{
  "my-namespace:say_hi": {
    "key": "say_hi",
    "namespace": "my-namespace",
    "message": "Cześć!"
  }
}

Use the --downloadPath {ns} placeholder (or the SPLIT_BY_NAMESPACES download option) to export a separate file per namespace instead.

Export options

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_DESCRIPTIONS - include translation key descriptions in the exported file
  • 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
  • ESCAPE_NEW_LINES - replace native new lines in translations with \n characters
  • SPLIT_BY_NAMESPACES - export a separate file per namespace
  • ENABLE_FALLBACKS - use fallback language translation if a translation is missing in the selected language
  • EXCLUDE_DEPRECATED_KEYS - skip deprecated keys in the exported file

See all download options.

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_API_KEY> \
  --uploadFormat simplelocalize-json \
  --uploadPath ./extracted.json \
  --languageKey en

Add --update 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_API_KEY> \
  --uploadFormat simplelocalize-json \
  --uploadPath ./extracted.json \
  --uploadOptions UPDATE_DESCRIPTIONS \
  --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