# 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 (including Next.js and React Server Components) or React Native. Lingui also supports various transpilers and build tools, such as Babel, SWC, and Vite.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* Make sure you have [Node.js](https://nodejs.org/) installed (v22.19 or higher).
* Install [Lingui CLI](https://lingui.dev/ref/cli.md) to manage your translations and catalogs.

tip

Don't miss the [Lingui ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) which can help you find and prevent common i18n mistakes in your code.

## Choosing a Transpiler[​](#choosing-a-transpiler "Direct link to Choosing a Transpiler")

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

Lingui needs a transpiler to work. It's responsible for transforming Lingui's JS/JSX components into [ICU MessageFormat](https://lingui.dev/guides/message-format.md) and extracting message IDs. Both Babel and SWC transpilers are supported. Follow the Babel or SWC setup depending on what transpiler your project already uses.

* Babel
* SWC

> 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`](https://github.com/kentcdodds/babel-plugin-macros) (deprecated as of V6) 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 `@lingui/babel-plugin-lingui-macro` package as a development dependency:

   * npm
   * Yarn
   * pnpm

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

   ```
   yarn add --dev @lingui/babel-plugin-lingui-macro
   ```

   ```
   pnpm add --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.

caution

If you're using [React Compiler](https://react.dev/learn/react-compiler), make sure that `@lingui/babel-plugin-lingui-macro` comes **before** the React Compiler plugin in the Babel plugins list. This ensures macros are expanded correctly before the compiler processes the code.

> SWC is an extensible Rust-based platform for the next generation of fast developer tools.

Lingui supports SWC with a dedicated plugin [`@lingui/swc-plugin`](https://lingui.dev/ref/swc-plugin.md). SWC is significantly faster than Babel and is a good choice for large projects.

Follow these steps to set up Lingui with SWC:

1. Install `@lingui/swc-plugin` 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
   ```

2. [Add necessary configurations](https://lingui.dev/ref/swc-plugin.md#usage).

caution

SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions is not guaranteed. See the [SWC compatibility](https://lingui.dev/ref/swc-plugin.md#swc-compatibility) for more information.

caution

If you're using [React Compiler](https://react.dev/learn/react-compiler) with SWC, the `@lingui/swc-plugin` must run **before** the React Compiler plugin. This is necessary because Lingui macros need to be expanded before the React Compiler processes your code.

However, in Next.js, the React Compiler is enabled via a simple boolean flag (`reactCompiler: true`) in `next.config.js`, and there's currently no way to control plugin ordering. As a result, Lingui may not work correctly with the React Compiler in SWC-based setups like Next.js.

## Basic Configuration[​](#basic-configuration "Direct link to Basic Configuration")

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

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

lingui.config.js

```
import { defineConfig } from "@lingui/cli";



export default defineConfig({

  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](https://lingui.dev/ref/conf.md) 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](https://lingui.dev/ref/catalog-formats.md) for other available formats.

## Build Tools[​](#build-tools "Direct link to Build Tools")

### Vite[​](#vite "Direct link to 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`](https://lingui.dev/ref/vite-plugin.md). This plugin is responsible for compiling message catalogs and some fine-tuning for Vite.

There are two ways to set up Lingui with Vite by using the [`@vitejs/plugin-react`](https://www.npmjs.com/package/@vitejs/plugin-react) or [`@vitejs/plugin-react-swc`](https://www.npmjs.com/package/@vitejs/plugin-react-swc). You need to choose the one that fits your project setup.

* Babel (plugin-react)
* SWC (plugin-react-swc)
* Vite 8+ with Rolldown

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

1. Follow the [Choosing a Transpiler](#choosing-a-transpiler) instructions.

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

   * npm
   * Yarn
   * pnpm

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

   npm install --save @lingui/react
   ```

   ```
   yarn add --dev @lingui/vite-plugin

   yarn add @lingui/react
   ```

   ```
   pnpm add --save-dev @lingui/vite-plugin

   pnpm add @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 the 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`.

The `@vitejs/plugin-react-swc` plugin uses SWC to transform your code, which is significantly faster than Babel. To use Lingui with Vite and SWC, follow these steps:

1. Follow the [Choosing a Transpiler](#choosing-a-transpiler) instructions.

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

   * npm
   * Yarn
   * pnpm

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

   npm install --save @lingui/react
   ```

   ```
   yarn add --dev @lingui/vite-plugin @lingui/swc-plugin

   yarn add @lingui/react
   ```

   ```
   pnpm add --save-dev @lingui/vite-plugin @lingui/swc-plugin

   pnpm add @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";

   import { linguiMacroSwcPlugin } from "@lingui/swc-plugin/options";



   export default defineConfig({

     plugins: [

       react({

         plugins: [linguiMacroSwcPlugin()],

       }),

       lingui(),

     ],

   });
   ```

Vite 8+ uses Rolldown to transpile and bundle your code. By default, it doesn't require Babel or SWC. However, Rolldown doesn't support native plugins yet, so you still need Babel or SWC to transform Lingui macros.

The easiest approach is to use a preset exported from `@lingui/vite-plugin`:

1. Install `@lingui/vite-plugin` and `@rolldown/plugin-babel` as development dependencies and `@lingui/react` as a runtime dependency:

   * npm
   * Yarn
   * pnpm

   ```
   npm install --save-dev @lingui/vite-plugin @rolldown/plugin-babel

   npm install --save @lingui/react
   ```

   ```
   yarn add --dev @lingui/vite-plugin @rolldown/plugin-babel

   yarn add @lingui/react
   ```

   ```
   pnpm add --save-dev @lingui/vite-plugin @rolldown/plugin-babel

   pnpm add @lingui/react
   ```

2. Setup Lingui in `vite.config.ts`:

   vite.config.ts

   ```
   import { defineConfig } from "vite";

   import react from "@vitejs/plugin-react";

   import { lingui, linguiTransformerBabelPreset } from "@lingui/vite-plugin";

   import babel from "@rolldown/plugin-babel";



   export default defineConfig({

     plugins: [

       react(),

       lingui(),

       babel({

         presets: [linguiTransformerBabelPreset()],

       }),

     ],

   });
   ```

info

If you want to use React Compiler together with Lingui, place the React Compiler preset **before** the Lingui preset. Presets are applied in reverse order, so Lingui will be applied first.

```
plugins: [

  react(),

  lingui(),

  babel({ presets: [reactCompilerPreset(), linguiTransformerBabelPreset()] }),

],
```

### Next.js[​](#nextjs "Direct link to Next.js")

Next.js compiles with SWC by default, so Lingui macros need the [`@lingui/swc-plugin`](https://lingui.dev/ref/swc-plugin.md) registered in the Next.js config file. If your project has a Babel config, Next.js uses Babel instead and the Babel setup above applies. The Lingui configuration from the [Basic Configuration](#basic-configuration) section works unchanged.

next.config.mjs

```
import { linguiMacroSwcPlugin } from "@lingui/swc-plugin/options";



/** @type {import('next').NextConfig} */

const nextConfig = {

  experimental: {

    swcPlugins: [linguiMacroSwcPlugin()],

  },

};



export default nextConfig;
```

Routing by locale, loading catalogs in server and client components and switching the language are covered in the [Next.js App Router i18n tutorial](https://lingui.dev/tutorials/react-rsc.md). The [examples](https://github.com/lingui/js-lingui/tree/main/examples) directory has working Next.js projects for both the SWC and the Babel setup.

## See Also[​](#see-also "Direct link to See Also")

* [React i18n Tutorial](https://lingui.dev/tutorials/react.md)
* [Next.js App Router i18n Tutorial](https://lingui.dev/tutorials/react-rsc.md)
* [React Native i18n Tutorial](https://lingui.dev/tutorials/react-native.md)
* [JavaScript i18n Tutorial](https://lingui.dev/tutorials/javascript.md)