CLI: Upload translations

Last updated: September 09, 2026

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

Usage

simplelocalize upload
  --apiKey PROJECT_API_KEY
  --uploadPath INPUT_FILE
  --uploadFormat FILE_FORMAT

The command uploads file with English translations.

simplelocalize upload
  --apiKey PROJECT_API_KEY
  --uploadPath ./locales/messages_en.json
  --uploadFormat single-language-json
  --uploadLanguageKey en

Configuration

Upload path

Choose which file(s) should be uploaded using --uploadPath, for example:

# one file
--uploadPath ./locales/messages.json

# translations with namespaces
--uploadPath ./locales/{ns}/messages_en.json

# all translations with namespaces (not recommended)
--uploadPath ./locales/{ns}/messages_{lang}.json

Available placeholders for an upload path:

  • {lang} - language key
  • {ns} - namespace

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

It's not recommended to push translations for every language on upload, as it's unnecessary extends the upload process. Read a step-by-step localization workflow for tips and recommendations

If the language names in your file system differ from the SimpleLocalize language keys (for example a file without any language suffix for the default language), use language mapping in the configuration file. The same mappings.lang entries are applied in reverse on upload.

File format

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

--uploadFormat java-properties

See list of available file formats

Language

Determine into which language the translations should be assigned using --uploadLanguageKey parameter, for example:

--uploadLanguageKey en

Whenever you upload translations please make sure you set the language key using --uploadLanguageKey, otherwise the system will import only translation keys without the actual content.

Dry run

You can test the upload command using --dryRun parameter that will list files to upload without uploading them, for example:

simplelocalize upload
  --uploadPath ./locales/{ns}/messages_{lang}.json
  --uploadFormat single-language-json
  --dryRun # <-- add this

Update translations

By default, only empty translations are updated with the values from the upload; you can update existing values using --update parameter, for example:

simplelocalize upload
  --uploadPath ./locales/messages.json
  --uploadFormat multi-language-json
  --update # <-- add this

Note: --update is a shorthand for --uploadOptions UPDATE_TRANSLATIONS and it will update all existing translations with the values from the upload.

Preview changes

You can preview changes before the upload command using --preview parameter that will list files to upload without importing them, for example:

simplelocalize upload
  --uploadPath ./locales/{ns}/messages_{lang}.json
  --uploadFormat single-language-json
  --preview # <-- add this

Tags

You can assign tags during the upload using --uploadTags (or simply --tags)

simplelocalize upload
  --uploadPath ./messages_{lang}.json
  --uploadFormat single-language-json
  --uploadTags Premium,Development

Use _none to clear tags.

Options

Customize import using options using --uploadOptions, for example:

--uploadOptions UPDATE_ORDER,MARK_AS_ACCEPTED

See upload options

Examples

One file with multiple languages

.
└── locales
    └── messages.json

Command:

simplelocalize upload
  --apiKey <PROJECT_API_KEY>
  --uploadPath ./locales/messages.json
  --uploadFormat multi-language-json

One file per language

In this example we upload only source translations from ./en/messages.json and uses --uploadLanguageKey en-GB to specify the language key for the uploaded file for translation editor. It's a recommended way to upload source translations.

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

Command:

simplelocalize upload
  --apiKey <PROJECT_API_KEY>
  --uploadPath ./en/messages.json
  --uploadLanguageKey en-GB
  --uploadFormat single-language-json

One file per language using placeholders

In this example we use {lang} placeholder to upload many files at once and specify language key for each file. It's not a recommended way to upload source translations, as it uploads more files than necessary.

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

Command:

simplelocalize upload
  --apiKey <PROJECT_API_KEY>
  --uploadPath ./{lang}/index.json
  --uploadFormat single-language-json

One file per language and namespace

In this example we use {ns} placeholder to upload many files at once for the English language. We used --uploadLanguageKey en-GB to specify language key for the uploaded file for the Translation Editor.

.
├── italian
│   ├── common.json
│   └── home.json
├── english
│   ├── common.json
│   └── home.json
└── spanish
    ├── common.json
    └── home.json

Command:

simplelocalize upload
  --apiKey <PROJECT_API_KEY>
  --uploadPath ./english/{ns}.json
  --uploadLanguageKey en-GB
  --uploadFormat single-language-json

Upload customer translations

This option is only available with a Business plan.

.
└── locales
    └── ikea-translations.json

simplelocalize upload \
 --apiKey MY_API_KEY \
 --uploadPath ./locales/ikea-translations.json \
 --uploadCustomerId ikea \
 --uploadFormat multi-language-json