Setup with React project
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
-
Install
@lingui/cli
,@lingui/macro
,babel-plugin-macros
and Babel 1 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/reactnoteIt's recommended to install
@lingui/macro
package as a production dependency rather than development one to avoidimport/no-extraneous-dependencies
errors in ESLint. -
Add
macros
plugin to Babel config (e.g:.babelrc
):{
"plugins": ["macros"]
}If you use any preset, check first if it contains
macros
plugin. These presets already includesmacros
plugin:react-scripts
.
For those who prefer not to use Babel, Lingui offers the SWC Plugin as an alternative.
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"
}
}
If you use TypeScript, you can add --typescript
flag to compile
script to produce compiled message catalogs with TypeScript types.
Usage
Check the installation by running:
- npm
- Yarn
- pnpm
npm run extract
yarn extract
pnpm run extract
There should be no error and you should see output similar 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)
Congratulations! You've successfully set up project with Lingui. Now it's good time to follow the React tutorial or read about ICU Message Format which is used in messages.
Further reading
- Internationalization of React apps
- Common i18n patterns in React
@lingui/react
reference documentation- CLI reference
- Configuration reference
- ICU Message Format
Footnotes
-
For those who prefer not to use Babel, Lingui offers the SWC Plugin as an alternative. ↩