Skip to main content

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​

  1. 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 install --save-dev @lingui/cli @babel/core
    npm install --save-dev @lingui/macro babel-plugin-macros
    npm install --save @lingui/react
    note

    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.

  2. 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 includes macros plugin: react-scripts.

info

For those who prefer not to use Babel, Lingui offers the SWC Plugin as an alternative.

tip

Don't miss the Lingui ESLint Plugin which can help you find and prevent common l10n mistakes in your code.

Configuration​

  1. Create lingui.config.js file with LinguiJS configuration in root of your project (next to package.json). Replace src 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 in src/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.

  2. Add following scripts to your package.json:

    package.json
    {
      "scripts": {
        "extract": "lingui extract",
        "compile": "lingui compile"
      }
    }
tip

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 run extract

There should be no error and you should see output similar following:

> 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)

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​

Footnotes​

  1. For those who prefer not to use Babel, Lingui offers the SWC Plugin as an alternative. ↩