Setup with React
Learn how to add internationalization to a React application using Lingui. This guide applies to any React project, including those created with Create React App.
Installation
- Babel
- SWC
-
Install
@lingui/cli
,@lingui/macro
,babel-plugin-macros
and Babel core packages as a development dependencies, and@lingui/react
as a runtime dependency:- npm
- Yarn
- pnpm
npm install --save-dev @lingui/cli @babel/core
npm install --save-dev @lingui/macro babel-plugin-macros
npm install --save @lingui/reactyarn add --dev @lingui/cli @babel/core
yarn add --dev @lingui/macro babel-plugin-macros
yarn add @lingui/reactpnpm add --save-dev @lingui/cli @babel/core
pnpm add --save-dev @lingui/macro babel-plugin-macros
pnpm add @lingui/react -
Add
macros
plugin to Babel config (e.g:.babelrc
):{
"plugins": ["macros"]
}When using any preset, first check if it includes the
macros
plugin. These presets already includes themacros
plugin:react-scripts
.
-
Install
@lingui/cli
,@lingui/macro
, and@lingui/react
as a runtime dependency:- npm
- Yarn
- pnpm
npm install --save-dev @lingui/cli
npm install --save @lingui/react
npm install --save @lingui/macroyarn add --dev @lingui/cli
yarn add @lingui/react
yarn add @lingui/macropnpm add --save-dev @lingui/cli
pnpm add @lingui/react
pnpm add @lingui/macro -
Install the
@lingui/swc-plugin
package as a development dependency:- npm
- Yarn
- pnpm
npm install --save-dev @lingui/swc-plugin
yarn add --dev @lingui/swc-plugin
pnpm add --save-dev @lingui/swc-plugin
It's recommended to install @lingui/macro
package as a production dependency rather than development one to avoid import/no-extraneous-dependencies
errors in ESLint.
Don't miss the Lingui ESLint Plugin which can help you find and prevent common l10n mistakes in your code.
Configuration
-
Create
lingui.config.js
file with LinguiJS configuration in root of your project (next topackage.json
). Replacesrc
with the directory name where you have source files:lingui.config.js/** @type {import('@lingui/conf').LinguiConfig} */
module.exports = {
locales: ["en", "cs", "fr"],
sourceLocale: "en",
catalogs: [
{
path: "<rootDir>/src/locales/{locale}/messages",
include: ["src"],
},
],
format: "po",
};This configuration will extract messages from source files inside
src
directory and write them into message catalogs insrc/locales
(English catalog would be in e.g:src/locales/en/messages.po
).PO format is recommended for message catalogs. See
format
documentation for other available formats. -
Add following scripts to your
package.json
:package.json{
"scripts": {
"extract": "lingui extract",
"compile": "lingui compile"
}
}
See Configuration reference for more options.
If you use TypeScript, you can add --typescript
flag to compile
script to produce compiled message catalogs with TypeScript types.
Usage
Verify the installation by running the CLI command to extract messages from source files and update message catalogs:
- npm
- Yarn
- pnpm
npm run extract
yarn extract
pnpm run extract
There should be no error, and you should see output similar to the following:
- npm
- Yarn
- pnpm
> npm run extract
Catalog statistics:
┌──────────┬─────────────┬─────────┐
│ Language │ Total count │ Missing │
├──────────┼─────────────┼─────────┤
│ cs │ 0 │ 0 │
│ en │ 0 │ 0 │
│ fr │ 0 │ 0 │
└──────────┴─────────────┴─────────┘
(use "lingui extract" to update catalogs with new messages)
(use "lingui compile" to compile catalogs for production)
> yarn extract
Catalog statistics:
┌──────────┬─────────────┬─────────┐
│ Language │ Total count │ Missing │
├──────────┼─────────────┼─────────┤
│ cs │ 0 │ 0 │
│ en │ 0 │ 0 │
│ fr │ 0 │ 0 │
└──────────┴─────────────┴─────────┘
(use "lingui extract" to update catalogs with new messages)
(use "lingui compile" to compile catalogs for production)
> pnpm run extract
Catalog statistics:
┌──────────┬─────────────┬─────────┐
│ Language │ Total count │ Missing │
├──────────┼─────────────┼─────────┤
│ cs │ 0 │ 0 │
│ en │ 0 │ 0 │
│ fr │ 0 │ 0 │
└─ ─────────┴─────────────┴─────────┘
(use "lingui extract" to update catalogs with new messages)
(use "lingui compile" to compile catalogs for production)
Read more about Lingui CLI and its commands.