CLI: Upload translations

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

Upload command takes your local files and uploads them to SimpleLocalize.

Table of contents

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

Input translation file(s)

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

File format

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

--uploadFormat java-properties

See list of available file formats

Language of the translations

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 --replace parameter, for example:

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

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