API Reference - CLI (@lingui/cli)

@lingui/cli manages locales, extracts messages from source files into message catalogs and compiles message catalogs for production use.

Install

1. Install @lingui/cli as a development dependency:

   npm install --save-dev @lingui/cli @babel/core
   # Or yarn
   yarn add --dev @lingui/cli @babel/core
   

2. Add following scripts to your package.json:

   {
      "scripts": {
         "extract": "lingui extract",
         "compile": "lingui compile",
      }
   }
   

Global options

--config <config>

Path to LinguiJS configuration file. If not set, the default file is loaded as described in LinguiJS configuration reference.

Commands

extract

lingui extract [files...] [--clean] [--overwrite] [--format <format>] [--locale <locale>] [--convert-from <format>] [--verbose] [--watch]

This command extracts messages from source files and creates a message catalog for each language using the following steps:

1. Extract messages from all *.jsx? files inside srcPathDirs

2. Merge them with existing catalogs in localeDir (if any)

3. Write updated message catalogs to localeDir

[files...]

Filters source paths to only extract messages from passed files. For ex:

lingui extract src/components

Will extract only messages from src/components/**/* files, you can also pass multiple paths.

It’s useful if you want to run extract command on files that are staged, using for example husky, before commiting will extract messages from staged files:

{
   "husky": {
      "hooks": {
         "pre-commit": "lingui extract $(git diff --name-only --staged)"
      }
   }
}

--clean

Remove obsolete messages from catalogs. Message becomes obsolete when it’s missing in the source code.

--overwrite

Update translations for sourceLocale from source.

--format <format>

Format of message catalogs (see format option).

--locale <locale>

Only extract data for the specified locale.

--convert-from <format>

Convert message catalogs from previous format (see format option).

--verbose

Prints additional information.

--watch

Watch mode.

Watches only for changes in files in paths defined in config file or in the command itself.

Remember to use this only in development as this command do not cleans obsolete translations.

--debounce <delay>

Debounce, when used with –debounce <delay>, delays extraction for <delay> milliseconds, bundling multiple file changes together.

extract-template

lingui extract-template [--verbose]

This command extracts messages from source files and creates a .pot template file.

--verbose

Prints additional information.

compile

lingui compile [--strict] [--format <format>] [--verbose] [--namespace <namespace>] [--watch]

This command compiles message catalogs in localeDir and outputs minified Javascript files. Each message is replaced with a function that returns the translated message when called.

Also, language data (pluralizations) are written to the message catalog as well.

--strict

Fail if a catalog has missing translations.

--format <format>

Format of message catalogs (see format option).

--verbose

Prints additional information.

--namespace

Specify namespace for compiled message catalogs (also see compileNamespace for global configuration).

--typescript

Is the same as using compileNamespace with the value “ts”. Generates a {compiledFile}.d.ts and the compiled file is generated using the extension .ts

--watch

Watch mode.

Watches only for changes in locale files in your defined locale catalogs. For ex. locales\en\messages.po

--debounce <delay>

Debounce, when used with –debounce <delay>, delays compilation for <delay> milliseconds, to avoid compiling multiple times for subsequent file changes.