Skip to main content

Setup with Vite

The Lingui Vite integration:

Setup with @vitejs/plugin-react​

@vitejs/plugin-react uses Babel to transform your code. LinguiJS rely on babel-plugin-macros to compile JSX to ICU Message Format and for automatic ID generation.

  1. Install @lingui/cli, babel-plugin-macros as development dependencies and @lingui/macro, @lingui/react as a runtime dependency:

    npm install --save-dev @lingui/cli @lingui/vite-plugin babel-plugin-macros
    npm install --save @lingui/react @lingui/macro

  2. Setup Lingui in vite.config.ts:

    info

    @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

    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: ["macros"],
          },
        }),
        lingui(),
      ],
    });

Setup with @vitejs/plugin-react-swc​

@vitejs/plugin-react-swc uses SWC to transform your code, which is 20x faster than Babel. LinguiJS rely on @lingui/swc-plugin to compile JSX to ICU Message Format and for automatic ID generation.

  1. Install @lingui/cli, @lingui/swc-plugin as development dependencies and @lingui/macro, @lingui/react as a runtime dependency:

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

  2. 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(),
      ],
    });

Further Setup​

  1. Create a lingui.config.ts file with LinguiJS configuration in the root of your project (next to package.json). Replace src with a directory name where you have source files:
lingui.config.ts
import type { LinguiConfig } from "@lingui/conf";

const config: LinguiConfig = {
  locales: ["en", "cs", "fr"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}",
      include: ["src"],
    },
  ],
};

export default config;

PO format is recommended for message catalogs, and could be compiled on the fly thanks to @lingui/vite-plugin.

See format documentation for other available formats.

  1. Add the following scripts to your package.json:
package.json
{
  "scripts": {
    "messages:extract": "lingui extract"
  }
}

  1. Check the installation by running:

    npm run messages:extract

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

    > npm run messages: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)

    This command should create .po catalogs in the src/locales/ folder:

    src
    └── locales
        ├── cs.po
        ├── en.po
        └── fr.po

  2. Import .po those files directly in your Vite processed code:

    export async function dynamicActivate(locale: string) {
      const { messages } = await import(`./locales/${locale}.po`);

      i18n.load(locale, messages);
      i18n.activate(locale);
    }

See the guide about dynamic loading catalogs for more info.

See Vite's official documentation for more info about Vite dynamic imports.

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