CLI: Download translations

Last updated: September 09, 2026

Download command takes translation from SimpleLocalize and saves them to your local files. See also how to use [configuration file] (/docs/cli/configuration/) for easier deployments and more options.

Usage

simplelocalize download
  --apiKey PROJECT_API_KEY
  --downloadPath DOWNLOAD_PATH
  --downloadFormat FILE_FORMAT

Example

The command downloads translation files for 3 languages, as single-language-json, to ./locales directory as messages_en.json, messages_de.json, messages_fr.json

simplelocalize download
  --apiKey <PROJECT_API_KEY>
  --downloadPath ./src/messages_{lang}.json
  --downloadFormat single-language-json
  --downloadLanguageKey en,de,fr

Configuration

Download path

Change where the exported translations should be stored using --downloadPath parameter, for example:

# one file
--downloadPath ./src/messages.json

# split by language
--downloadPath ./src/{lang}messages.json

# split by language and namespace
--downloadPath ./src/{lang}/{ns}/messages.json

Available placeholders for a download path:

  • {lang} - language key
  • {ns} - namespace
  • {customer} - customer key (if you are using customer translations)

You can use the placeholders as a part of a directory name, or a file name.

Language mapping

By default {lang} is replaced with the SimpleLocalize language key, so ./Strings.{lang}.resx becomes ./Strings.en.resx. When your project names languages differently than SimpleLocalize does, or when one language should have no suffix at all, map the language keys to the names used in your file system with mappings.lang. The option is available only in the configuration file, not as a command-line argument.

# simplelocalize.yml
downloadPath: ./res/values{lang}/strings.xml
mappings:
  lang:
    - languageKey: "en"     # SimpleLocalize language key
      placeholder: ""       # what {lang} becomes in the file system
    - languageKey: "de"
      placeholder: "-de"

With this configuration en is downloaded to ./res/values/strings.xml and de to ./res/values-de/strings.xml. Note that the separator (-) is part of the placeholder and not of the path — that is what lets one language end up with no suffix. Because of that, every language you download needs its own entry: a language without a mapping keeps its SimpleLocalize key, which would produce ./res/valuesfr/strings.xml for fr.

The mapping works in both directions. On upload the same entries are applied in reverse, so a file found at ./res/values/strings.xml is uploaded as en. See .NET RESX and Android Strings for complete examples.

File format

Change the exported translations format using --downloadFormat parameter, for example:

--downloadFormat java-properties

See the list of available file formats

Filter languages

Choose which languages you want to export using --downloadLanguageKey parameter, for example:

--downloadLanguageKey en,pl,fr

Use language keys that you configured in the 'Languages' tab.

Sort translations

You can change the default sort order using --downloadSort parameter with one of those values:

  • LEXICOGRAPHICAL - sort alphabetically using the lexicographical algorithm
  • NEWEST_KEYS_FIRST - sort by translation key creation date, newest first
  • NEWEST_KEYS_LAST - sort by translation key creation date, oldest first
  • NAMESPACES - sort by namespaces alphabetically
  • IMPORT_ORDER - sort by the import order

Tags

You can download translations with specific tags using --downloadTags parameter (or simply --tags), for example:

simplelocalize upload
  --downloadPath ./messages_{lang}.json
  --downloadFormat single-language-json
  --downloadTags Premium,Development,_none

Use _none to include translations without any tags.

Options

Customize exported translations using options using --downloadOptions, for example:

--downloadOptions WRITE_NESTED,ENABLE_FALLBACKS

See download options

Examples

One file with multiple languages

Command:

simplelocalize download
  --apiKey <PROJECT_API_KEY>
  --downloadPath ./locales/messages.json
  --downloadFormat multi-language-json

Expected output:

.
└── locales
    └── messages.json

One file per language

Command:

simplelocalize download
  --apiKey <PROJECT_API_KEY>
  --downloadPath ./{lang}/messages.json
  --downloadFormat single-language-json

Expected output:

.
├── ca
│   └── messages.json
├── en
│   └── messages.json
└── es
    └── messages.json

One file per language and namespace

Command:

simplelocalize download
  --apiKey <PROJECT_API_KEY>
  --downloadPath /{lang}/{ns}.json
  --downloadFormat single-language-json

Expected output:

.
├── it
│   ├── common.json
│   └── home.json
├── en
│   ├── common.json
│   └── home.json
└── es
    ├── common.json
    └── home.json

Download customer translations for one customer

This option is only available with a Business plan.

simplelocalize download \
 --apiKey PROJECT_API_KEY \
 --downloadPath ./locales/translations_ikea.json \
 --downloadCustomerId ikea \
 --downloadFormat multi-language-json

Expected output:

.
└── locales
    └── translations_ikea.json

Download all customer translations

This option is only available with a Business plan.

simplelocalize download \
 --apiKey PROJECT_API_KEY \
 --downloadPath ./locales/translations_{customer}.json \
 --downloadFormat multi-language-json

Expected output:

.
└── locales
    └── translations_ikea.json