Skip to main content

Installation and Setup

Lingui is more than just a package; it's a comprehensive suite of tools designed to simplify internationalization. You have the flexibility to choose the specific tools that best fit your project's needs.

Learn how to install Lingui in your project, whether you use JavaScript, React or React Native. Lingui also supports various transpilers and build tools, such as Babel, SWC, and Vite.

Prerequisites​

  • Make sure you have Node.js installed (v20 or higher).
  • Install Lingui CLI to manage your translations and catalogs.
tip

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

Choosing Transpiler​

A transpiler converts code within a language, transforming newer features into older equivalents for compatibility, or expanding concise syntax into more detailed implementations.

Lingui needs a transpiler to work. It's responsible for transforming Lingui's JS/JSX components into ICU Message Format and extracting message IDs. Both Babel and SWC transpilers are supported. Depending on your project setup, you can choose the one that suits your needs.

Babel is a JavaScript transpiler that converts modern code into backward-compatible versions and allows custom syntax transformations.

Lingui requires @lingui/babel-plugin-lingui-macro (recommended) or babel-plugin-macros to perform the transformation.

If you are using a framework that doesn't allow you to change the Babel configuration (e.g. Create React App > 2.0), these frameworks may support babel-plugin-macros out of the box.

Follow these steps to set up Lingui with Babel:

  1. Install the Babel core and @lingui/babel-plugin-lingui-macro packages as development dependencies:

    npm install --save-dev @babel/core
    npm install --save-dev @lingui/babel-plugin-lingui-macro

  2. Add @lingui/babel-plugin-lingui-macro to the top of the plugins section of your Babel config (e.g. .babelrc):

    {
      "plugins": ["@lingui/babel-plugin-lingui-macro"]
    }
tip

When using a preset, first check if it includes the macros plugin. If so, then you don't need to install and set up @lingui/babel-plugin-lingui-macro. For example, react-scripts already includes the macros plugin.

Build Tools​

Vite​

Vite is a blazing fast frontend build tool powering the next generation of web applications.

Lingui supports Vite with a dedicated plugin @lingui/vite-plugin. The Lingui Vite integration supports both @vitejs/plugin-react and @vitejs/plugin-react-swc and compiles .po message catalogs on the fly.

Setup with @vitejs/plugin-react​

This plugin uses Babel to transform your code. To use Lingui with Vite and @vitejs/plugin-react, follow these steps:

  1. Follow the Babel Setup instructions.

  2. Install @lingui/vite-plugin as a development dependency and @lingui/react as a runtime dependency:

    npm install --save-dev @lingui/vite-plugin
    npm install --save @lingui/react

  3. Setup Lingui in vite.config.ts:

    vite.config.ts
    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react";
    import { lingui } from "@lingui/vite-plugin";

    export default defineConfig({
      plugins: [
        react({
          babel: {
            plugins: ["@lingui/babel-plugin-lingui-macro"],
          },
        }),
        lingui(),
      ],
    });
    info

    The @vitejs/plugin-react does not use babel config (e.g. babel.rc) from your project by default. You have to enable it manually or specify Babel options directly in vite.config.ts.

Setup with @vitejs/plugin-react-swc​

This plugin uses SWC to transform your code, which is significantly faster than Babel.

  1. Follow the SWC Setup instructions.

  2. Install @lingui/vite-plugin and @lingui/swc-plugin as development dependencies and @lingui/react as a runtime dependency:

    npm install --save-dev @lingui/vite-plugin @lingui/swc-plugin
    npm install --save @lingui/react

  3. Setup Lingui in vite.config.ts:

    vite.config.ts
    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react-swc";
    import { lingui } from "@lingui/vite-plugin";

    export default defineConfig({
      plugins: [
        react({
          plugins: [["@lingui/swc-plugin", {}]],
        }),
        lingui(),
      ],
    });

Basic Configuration​

Lingui needs a configuration file to work. The configuration file specifies the source files, message catalogs, and other settings.

By default, Lingui looks for the configuration in the following locations:

  • lingui.config.js or lingui.config.ts file exporting a configuration object (recommended).
  • .linguirc file in JSON format.
  • lingui section in package.json.

You can also define the environment variable LINGUI_CONFIG with the path to your config file.

Let's create a basic configuration file in the root of your project (next to package.json):

lingui.config.js
/** @type {import('@lingui/conf').LinguiConfig} */
module.exports = {
  sourceLocale: "en",
  locales: ["cs", "en"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
};

The configuration above specifies the source locale as English and the target locales as Czech and English.

According to this configuration, Lingui will extract messages from source files in the src directory and write them to message catalogs in src/locales (the English catalog would be in src/locales/en/messages.po, for example). See Configuration for a complete reference.

note

Replace src with the name of the directory where you have the source files.

The PO format is the default and recommended format for message catalogs. See the Catalog Formats for other available formats.