Skip to main content

Configuration

The following reference covers all supported configuration options in Lingui. To learn more about configuring Lingui, read the Installation and Setup guide.

By default, Lingui looks for the configuration in the following locations:

  • lingui.config.js or lingui.config.ts file exporting a configuration object (recommended).
  • .linguirc file in JSON format.
  • lingui section in package.json.

You can also define the environment variable LINGUI_CONFIG with the path to your config file.

In the case of TypeScript-based config you can use ESM format and export default.

catalogs​

Default value:

[
  {
    path: "<rootDir>/locale/{locale}/messages",
    include: ["<rootDir>"],
    exclude: ["**/node_modules/**"],
  },
];

The catalogs configuration defines the location of message catalogs and specifies which files are included when the extract command scans for messages.

  • path: the directory where the message catalogs are located. It should not end with a slash and must not include a file extension, which depends on the format configuration. The {locale} token will be replaced by the catalog's locale.
  • include and exclude: these patterns specify which files to include or exclude during the extraction process. They are passed to minimatch for pattern matching.
  • <rootDir>: represents the root directory of the project. It is replaced with the actual root directory when the configuration is loaded. By default, <rootDir> represents the configuration file's location.

The path, include, and exclude patterns are interpreted relative to the current process CWD (current working directory).

The {name} token in the path will be replaced with the catalog name. Be sure to include the {name} pattern in the source path as well, as it acts like a * glob pattern:

{
  "catalogs": [
    {
      "path": "<rootDir>/components/{name}/locale/{locale}",
      "include": ["<rootDir>/components/{name}/"]
    }
  ]
}

Examples​

Let's assume we use locales: ["en", "cs"] and format: "po" in all examples.

All catalogs in one directory​

{
  "catalogs": [
    {
      "path": "locales/{locale}"
    }
  ]
}
locales/
├── en.po
└── cs.po

Catalogs in separate directories​

{
  catalogs: [
    {
      path: "locales/{locale}/messages",
    },
  ];
}
locales
├── en/
│   └── messages.po
└── cs/
    └── messages.po

Separate catalogs per component, placed inside component directory​

{
  "catalogs": [
    {
      "path": "components/{name}/locale/{locale}",
      "include": ["components/{name}/"]
    }
  ]
}
components/
├── RegistrationForm/
│   ├── locale/
│   │  ├── en.po
│   │  └── cs.po
│   ├── RegistrationForm.test.js
│   └── RegistrationForm.js
└── LoginForm/
    ├── locale/
    │  ├── en.po
    │  └── cs.po
    ├── LoginForm.test.js
    └── LoginForm.js

Separate catalogs per component, placed inside shared directory​

{
  "catalogs": [
    {
      "path": "locale/{locale}/{name}",
      "include": ["components/{name}/"]
    }
  ]
}
.
├── locale/
│   ├── en/
│   │   ├── RegistrationForm.po
│   │   └── LoginForm.po
│   └── cs/
│       ├── RegistrationForm.po
│       └── LoginForm.po
└── components/
    ├── RegistrationForm/
    │   ├── RegistrationForm.test.js
    │   └── RegistrationForm.js
    └── LoginForm/
        ├── LoginForm.test.js
        └── LoginForm.js

locales​

Default value: []

The locale tags used in the project. The extract and compile commands write a catalog for each locale specified. Each locale should be a valid BCP-47 code:

{
  "locales": ["en", "cs"]
}

fallbackLocales​

Default value: {}

Translations from fallbackLocales are used if the translation for the given locale is missing. It uses CLDR Parent Locales by default, unless you override it with a false to use the default message or message ID instead:

{
  "fallbackLocales": false
}

The fallbackLocales object allows to configure fallback locales for each locale instance:

{
  "fallbackLocales": {
    "en-US": ["en-GB", "en"],
    "es-MX": "es"
  }
}

In this example, if any translation isn't found on en-US, then it will search on en-GB, after that if not found we'll search in en.

it's also possible to configure a default fallback locale for all locales:

{
  "fallbackLocales": {
    "en-US": ["en-GB", "en"],
    "es-MX": "es",
    "default": "en"
  }
}

sourceLocale​

Default value: ""

sourceLocale specifies the default language of message IDs in your source files. The catalog for sourceLocale doesn't need actual translations since message IDs are used as-is by default. However, you can still override any message ID by providing a custom translation.

The main difference between sourceLocale and fallbackLocales is their purpose: sourceLocale defines the language used for message IDs, while fallbackLocales provides alternative translations when specific messages are missing for a particular locale.

pseudoLocale​

Default value: ""

Locale used for pseudolocalization. For example, when you set pseudoLocale: "en", all messages in the en catalog will be pseudo-localized. The locale must be included in the locales config.

Read more about Pseudolocalization.

catalogsMergePath​

Default value: ""

Define the path where translated catalogs are merged into a single file per locale during the compile process.

Example​

Let's assume we have separate catalogs per component, placed inside shared directory.

Using the catalogsMergePath, separate catalogs can be merged into a single file:

{
  "catalogs": [
    {
      "path": "/locale/{locale}/{name}",
      "include": ["components/{name}/"]
    }
  ],
+ "catalogsMergePath": "locales/{locale}"
}
.
  ├── locale/
  │   ├── en/
  │   │   ├── RegistrationForm.po
- │   │   ├── RegistrationForm.js
  │   │   ├── LoginForm.po
- │   │   └── LoginForm.js
  │   └── cs/
  │       ├── RegistrationForm.po
- │       ├── RegistrationForm.js
  │       ├── LoginForm.po
- │       └── LoginForm.js
+ ├── locales/
+ │   ├── en.js
+ │   └── cs.js
  └── components/
      ├── RegistrationForm/
      │   ├── RegistrationForm.test.js
      │   └── RegistrationForm.js
      └── LoginForm/
          ├── LoginForm.test.js
          └── LoginForm.js

compileNamespace​

Default value: cjs

Specify namespace for exporting compiled messages. See compile command.

cjs​

Use CommonJS exports:

/* eslint-disable */module.exports={messages: {"..."}}

es​

Use ES6 named export:

/* eslint-disable */export const messages = {"..."}

ts​

Use ES6 named export + .ts file with an additional {compiledFile}.d.ts file:

/* eslint-disable */export const messages = {"..."}
import { Messages } from '@lingui/core';
declare const messages: Messages;
export { messages };

json​

{"messages": {"..."}}

(window|global).(.*)​

Assign compiled messages to window or global object. Specify an identifier after window or global to which the catalog is assigned, e.g. window.i18n.

For example, setting compileNamespace to window.i18n creates file similar to this:

/* eslint-disable */window.i18n={messages: {"..."}}

extractorParserOptions​

Default value: {}

Specify additional options used to parse source files when extracting messages.

{
  "extractorParserOptions": {
    "tsExperimentalDecorators": false,
    "flow": false
  }
}

tsExperimentalDecorators​

Default value: false

By default, standard decorators (Stage3) are applied to TS files. Enable this if you want to use TypeScript's experimental decorators.

flow​

Default value: false

Lingui does not ship with Flow typing. However, you can use Lingui in projects written in Flow. Enable this option to tell the extractor that your sources use Flow syntax.

compilerBabelOptions​

Default value:

{
  "minified": true,
  "jsescOption": {
    "minimal": true
  }
}

Specify extra babel options used to generate files when messages are being compiled. We use internally @babel/generator that accepts some configuration for generating code with/out ASCII characters. These are all the options available: jsesc.

{
  "compilerBabelOptions": {
    "jsescOption": {
      "minimal": false
    }
  }
}

This example configuration will compile with escaped ASCII characters (jsesc#minimal).

format​

Default value: po

Message catalog format. The po formatter is used by default. Other formatters are available as separate packages.

lingui.config.{js,ts}
import { defineConfig } from "@lingui/cli";
import { formatter } from "@lingui/format-po";

export default defineConfig({
  // [...]
  format: formatter({ lineNumbers: false }),
});

Read more about available formatters in Catalog Formats or create your own Custom Formatter.

orderBy​

Default value: message

Order of messages in catalog:

message​

Sort by source message.

messageId​

Sort by the message ID, js-lingui-id will be used if no custom id provided.

origin​

Sort by message origin (e.g. App.js:3)

rootDir​

Default: The root of the directory containing your Lingui configuration file or the package.json.

This is the directory where the Lingui CLI scans for messages in your source files during the extraction process.

Note that using <rootDir> as a string token in any other path-based config settings will refer back to this value.

runtimeConfigModule​

Default value: ["@lingui/core", "i18n"]

This setting specifies the module path for the exported i18n object. The first value in the array is the module path, and the second is the name of the import. This configuration is essential for macros that need to reference the global i18n object.

You only need to set this value if you use custom object created using setupI18n:

For example, if you have a custom module that exports the i18n object:

import { i18n } from "./custom-i18n-config";
{
  "runtimeConfigModule": ["./custom-i18n-config", "i18n"]
}

You may use a different named export:

import { myI18n } from "./custom-i18n-config";
{
  "runtimeConfigModule": ["./custom-i18n-config", "myI18n"]
}

In more advanced scenarios, you may need to change the module from which the Trans or useLingui macros are imported:

import { Trans, useLingui } from "./custom-config";
{
  "runtimeConfigModule": {
    "Trans": ["./custom-config", "Trans"],
    "useLingui": ["./custom-config", "useLingui"]
  }
}

extractors​

Default value: [babel]

Extractors it's the way to customize which extractor you want for your codebase.

{
   "extractors": [
      myCustomExtractor,
   ]
}

See the Custom Extractor guide for instructions on creating your own extractor.