CLI: Download translations

Last updated: June 23, 2025Author: Jakub Pomykała

Download command takes translation from SimpleLocalize and saves them to your local files.

Table of contents

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

Output translation file(s)

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.

File format

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

--downloadFormat java-properties

See 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

Options

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

--downloadOptions WRITE_NESTED,DEFAULT_IF_MISSING

See downloads 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
Was this helpful?