FormatJS CLI

Last updated: November 23, 2022Author: Jakub Pomykała

format js cli importing

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

Table of contents

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 | bash

# Windows (PowerShell)
. { iwr -useb } | 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

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

Translate messages in the editor

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

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 = "";
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());