FormatJS CLI

In this article, we will focus only on message extraction from FormatJS using a dedicated CLI from FormatJS team. After that, I will show you how to configure and upload the output to SimpleLocalize and automate the workflow.

Read a full tutorial with configuring FormatJS and FormatJS CLI.

Add dependencies

Install Format JS CLI development dependency to your project.

# Using NPM
npm i -D @formatjs/cli

# Using yarn
yarn add -D @formatjs/cli

Install SimpleLocalize CLI

Install SimpleLocalize locally, to it will help us to automate the process of uploading and downloading translations from the translation editor.

# macOS / Linux / Windows (WSL)
curl -s https://get.simplelocalize.io/2.6/install | bash

# Windows (PowerShell)
. { iwr -useb https://get.simplelocalize.io/2.6/install-windows } | iex;

Add scripts

Add the following command to your package.json scripts:

{
  "scripts": {
    "i18n:extract": "formatjs extract 'src/**/*.{ts,js,tsx,jsx}' --out-file lang.json",
    "i18n:upload": "simplelocalize upload --apiKey <PROJECT_API_KEY> --uploadPath ./lang.json --uploadFormat simplelocalize-json --languageKey en",
    "i18n:auto-translate": "simplelocalize auto-translate --apiKey <PROJECT_API_KEY>",
    "i18n:download": "simplelocalize download --apiKey <PROJECT_API_KEY> --downloadPath ./messages.json --downloadFormat multi-language-json"
  }
}

Use your project API Key instead <PROJECT_API_KEY> values. You can find your API Key in SimpleLocalize project > 'Integrations' > 'Project credentials' > API Key.

You can also create a simplelocalize.yml file with configuration, so you won't have to add your API key to every command.

apiKey: <YOUR_PROJECT_API_KEY>

Extract messages

Use an extract script to start FormatJS CLI extraction. It will save all translation keys in lang.json file.

$ npm run i18n:extract

Message extraction with FormatJS CLI

Upload messages

Now you can use SimpleLocalize CLI to upload lang.json file to the translation editor. Use your project API Key in --apiKey parameter. You can find your API Key in SimpleLocalize project > 'Integrations' > 'Project credentials' > API Key.

$ simplelocalize upload \
        --apiKey YOUR_API_KEY \
        --languageKey en \
        --uploadFormat simplelocalize-json \
        --uploadPath ./lang/en.json

Please note that we provided a languageKey in the upload component that matches the language of defaultMessage texts in your code. Thanks to that SimpleLocalize will automatically assign default messages as translations.

Upload FormatJS extraction results via SimpleLocalize CLI

Manage JSON strings

Now you can translate your React application JSONs using the translation editor.

Manage your translation strings in Translation Editor

If you want to translate your app in multiple languages fast, you can add new languages in the Languages tab, and use auto-translation features to speed up the process.

How to start auto-translation for many languages at once

Get translations

Download locally

Download JSON file with translation to your project files with CLI. Run simplelocalize download command like below to download JSON files with translations.

$ simplelocalize download \
        --apiKey YOUR_API_KEY \
        --downloadFormat single-language-json \
        --downloadPath ./i18n/messages_{lang}.json

CLI will download the files to the ./i18n/messages_{lang}.json files, where {lang} is the language code set in Languages tab.

Download FormatJS translation messages via SimpleLocalize CLI

Resources

Was this helpful?

Documentation