FormatJS CLI

In this article, you will learn how to upload FormatJS CLI extraction output with SimpleLocalize.

Table of contents

• Before you start

• Add dependencies

• Install SimpleLocalize CLI

• Adjust package.json

• Extract messages

• Upload messages

• Translate messages in the editor

• Get translations

  • Download locally
  • Fetch from Translation Hosting

• Resources

Before you start

Before you start, you need to have a SimpleLocalize account. If you don't have one yet, you can sign up for free. Create a new project and add get your API Key.

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 upload extracted messages to translation editor and download translated JSON files later.

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

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

Adjust package.json

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

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

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.

Translate messages in the editor

Now you can translate your React application JSONs using the 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.

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.

Fetch from Translation Hosting

If you want to fetch translations from Translation Hosting, you can use any library to make HTTP requests.

const BASE_URL = "https://cdn.simplelocalize.io";
const PROJECT_TOKEN = "<YOUR_PROJECT_TOKEN>";
const ENVIRONMENT = "_latest"; // or "_production"

interface LanguageTranslations {
  [key: string]: string;
}

const fetchTranslationMessages = async (languageKey: string): Promise<LanguageTranslations> => {
  const messages = `${BASE_URL}/${PROJECT_TOKEN}/${ENVIRONMENT}/${languageKey}`;
  return fetch(messages).then((data) => data.json());
};

Resources

• FormatJS guide
• FormatJS CLI message extraction
• JavaScript number formatting