CLI: Upload translations

Last updated: October 08, 2024Author: 

Upload existing translations or translation keys from your local project files. The uploaded translations and translations keys you can find in the translation editor.

Table of contents

Usage

Before you start, you need to install the CLI. Follow the CLI installation guide.

simplelocalize upload --apiKey <MY_API_KEY> ...
How to upload translation files with command-line tool

Additional parameters:

  • --overwrite allows you to update translations.
  • --delete allows you to delete translations that are not present in uploaded file.
  • --dryRun allows you to check what translation files will be uploaded without actually uploading them.
  • --namespace allows you to specify a namespace for the uploaded file(s),
  • --customerId allows you to specify a customer ID for the uploaded file(s),
  • --uploadOptions allows you to pass additional options to the upload command. E.g.: --options TRIM_LEADING_TRAILING_SPACES. To pass multiple options, use comma as a separator.

Since version 2.7 you can skip 'upload' part in the parameters names, e.g.: --path instead of --uploadPath.

Example: One file with multiple languages

.
└── locales
    └── messages.json

Command:

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

Example: One file per language

In this example we upload only source translations from ./en/messages.json and uses --uploadLanguageKey en-GB to specify language key for the uploaded file for the 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/index.json
  --uploadLanguageKey en-GB
  --uploadFormat single-language-json

Example: 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

Example: 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

Example: 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

Upload options

Many upload formats offer additional options. You can activate them using --uploadOptions parameter.

simplelocalize upload \
 --apiKey MY_API_KEY \
 --uploadPath ./translations.json \
 --uploadFormat multi-language-json \
 --uploadOptions UNESCAPE_NEW_LINES,PUBLISH_AFTER_IMPORT

See all available upload options

Override translations from file

If you want to override translations existing translations in translation editor you can use --overwrite option. This option won't clear translations that are not present in the file.

simplelocalize upload \
 --apiKey MY_API_KEY \
 --uploadPath ./translations.json \
 --uploadFormat multi-language-json \
 --overwrite

This option is useful when you want to update translations from a file for a given language, instead of managing them via the translation editor.

Delete translations that are not present in uploaded files

If you want to delete all other translations from the translation editor and keep only those from uploaded files you can use --delete option. Make sure you know what you are doing, you can create a backup of your project before using this option.

simplelocalize upload \
 --apiKey MY_API_KEY \
 --uploadPath ./translations.json \
 --uploadFormat multi-language-json \
 --delete

Check what translations will be uploaded

If you want to check what translations will be uploaded without actually uploading them you can use --dryRun option.

simplelocalize upload \
 --apiKey MY_API_KEY \
 --uploadPath ./translations/{ns}/{lang}.json \
 --uploadFormat single-language-json \
 --dryRun
Was this helpful?