Skip to main content

Setup with React project

info

If you use Create React App, even ejected, follow LinguiJS and Create React App setup guide.

This setup guide is for any project which uses React.

Install​

  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
    tip

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

    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"]
    }
    info

    If you use any preset, check first if it contains macros plugin. These presets already includes macros plugin: react-scripts

  3. 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"],
      catalogs: [
        {
          path: "<rootDir>/src/locales/{locale}/messages",
          include: ["src"],
        },
      ],
      format: "po",
    };

    PO format is recommended for message catalogs. See format documentation for other available formats.

  4. 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.

  1. 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)
tip

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

Congratulations! You've successfully set up project with LinguiJS. Now it's good time to follow React tutorial or read about ICU Message Format which is used in messages.

Further reading​

Checkout these reference guides for full documentation:

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