Lingui Configuration¶
Configuration is read from 3 different sources (the first found wins):
from
lingui
section inpackage.json
from
.linguirc
from
lingui.config.js
Default config:
{
"catalogs": [{
"path": "<rootDir>/locale/{locale}/messages",
"include": ["<rootDir>"],
"exclude": ["**/node_modules/**"]
}],
"compileNamespace": "cjs",
"extractBabelOptions": {},
"compilerBabelOptions": {},
"fallbackLocales": {},
"format": "po",
"locales": [],
"orderBy": "messageId",
"pseudoLocale": "",
"rootDir": ".",
"runtimeConfigModule": ["@lingui/core", "i18n"],
"sourceLocale": "",
}
catalogs¶
Default:
[{
path: "<rootDir>/locale/{locale}/messages",
include: ["<rootDir>"],
exclude: ["**/node_modules/**"]
}]
Defines location of message catalogs and what files are included when
extract
is scanning for messages.
path
shouldn’t end with slash and it shouldn’t include file extension which
depends on format
. {locale}
token is replaced by catalog locale.
Patterns in include
and exclude
are passed to minimatch.
path
, include
and exclude
patterns might include <rootDir>
token, which
is replaced by value of rootDir
.
{name}
token in path
is replaced with a catalog name. Source path must
include {name}
pattern as well and it works as a *
glob pattern:
{
"catalogs": [{
path: "./components/{name}/locale/{locale}",
include: ["./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 dir¶
{
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
compileNamespace¶
Default: cjs
Specify namespace for exporting compiled messages. See compile
command.
(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: {"..."}}
extractBabelOptions¶
Default: {}
Specify extra babel options used to parse source files when messages are being extracted. This is required when project doesn’t use standard Babel config (e.g. Create React App).
{
"extractBabelOptions": {
"plugins": ["@babel/plugin-syntax-dynamic-import"]
}
}
compilerBabelOptions¶
Default:
{
"minified": true,
"jsescOption": {
"minimal": true
}
}
Specify extra babel options used to generate files when messages are being
compiled. We use internaly @babel/generator
that accepts some configuration for generating code with/out ASCII characters.
These are all the options available: https://github.com/mathiasbynens/jsesc
{
"compilerBabelOptions": {
"jsescOption": {
"minimal": false
}
}
}
This example configuration will compile with scaped ASCII characters. https://github.com/mathiasbynens/jsesc#minimal
fallbackLocales¶
Default: {}
fallbackLocales
by default is using CLDR Parent Locales, unless you disable it with a false:
{
"fallbackLocales": false
}
fallbackLocales
object let’s us configure fallback locales to each locale instance.
{
"fallbackLocales": {
"en-US": ["en-GB", "en"],
"es-MX": "es"
}
}
On this example if any translation isn’t found on en-US then will search on en-GB, after that if not found we’ll search in en
Also, we can configure a default one for everything:
{
"fallbackLocales": {
"en-US": ["en-GB", "en"],
"es-MX": "es",
"default": "en"
}
}
Translations from fallbackLocales
is used when translation for given locale is missing.
If fallbackLocales
is false default message or message ID is used instead.
format¶
Default: po
Format of message catalogs. Possible values are:
po¶
Gettext PO file:
#, Comment for translators
#: src/App.js:4, src/Component.js:2
msgid "MessageID"
msgstr "Translated Message"
po-gettext¶
Uses PO files but with gettext-style plurals, see PO File with gettext Plurals.
minimal¶
Simple JSON with message ID -> translation mapping. All metadata (default message, comments for translators, message origin, etc) are stripped:
{
"MessageID": "Translated Message"
}
lingui¶
Raw catalog data serialized to JSON:
{
"MessageID": {
"translation": "Translated Message",
"defaults": "Default string (from source code)",
"origin": [
["path/to/src.js", 42]
]
}
}
Origin is filename and line number from where the message was extracted.
Note that origins may produce a large amount of merge conflicts. Origins can be
disabled by setting origins: false
in formatOptions
.
formatOptions¶
Default: { origins: true }
Object for configuring message catalog output. See individual formats for options.
locales¶
Default: []
Locale tags which are used in the project. extract
and compile
writes one catalog for each locale. Each locale must be a valid
BCP-47 code.
orderBy¶
Default: messageId
Order of messages in catalog:
messageId¶
Sort by the message ID.
origin¶
Sort by message origin (e.g. App.js:3
)
pseudoLocale¶
Default: ""
Locale used for pseudolocalization. For example when you set pseudoLocale: "en"
then all messages in en
catalog will be pseudo localized. The locale has to be included
in locales
config.
rootDir¶
Default: The root of the directory containing your Lingui config file or the package.json
.
The root directory that Lingui CLI should scan when extracting messages from source files.
Note that using <rootDir>
as a string token in any other path-based config
settings will refer back to this value.
runtimeConfigModule¶
Default: ["@lingui/core", "i18n"]
Module path with exported i18n object. The first value in array is module path,
the second is the import identifier. This value is used in macros, which need
to reference the global i18n
object.
You only need to set this alue if you use custom object created using setupI18n()
:
// If you import `i18n` object from custom module like this:
import { i18n } from "./custom-i18n-config"
// ... then add following line to Lingui configuration:
// "runtimeConfigModule": ["./custom-i18n-config", "i18n"]
You may use a different named export:
import { myI18n } from "./custom-i18n-config"
// "runtimeConfigModule": ["./custom-i18n-config", "myI18n"]
In some advanced cases you may also need to change the module from which Trans is imported. To do that, pass an object to runtimeConfigModule:
// If you import `i18n` object from custom module like this:
import { Trans, i18n } from "./custom-config"
// ... then add following line to Lingui configuration:
// "runtimeConfigModule": {
// i18n: ["./custom-config", "i18n"],
// Trans: ["./custom-config", "Trans"]
// }
sourceLocale¶
Default: ''
Locale of message IDs, which is used in source files.
Catalog for sourceLocale
doesn’t require translated messages, because message
IDs are used by default. However, it’s still possible to override message ID by
providing custom translation.
The difference between fallbackLocales
and sourceLocale
is that
fallbackLocales
is used in translation, while sourceLocale
is
used for the message ID.