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
orlingui.config.ts
file exporting a configuration object (recommended)..linguirc
file in JSON format.lingui
section inpackage.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 theformat
configuration. The{locale}
token will be replaced by the catalog's locale.include
andexclude
: 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.
import { formatter } from "@lingui/format-po"
export default {
[...]
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.