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 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/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.js 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.js
    /** @type {import('@lingui/conf').LinguiConfig} */
    module.exports = {
    locales: ["en", "cs", "fr"],
    catalogs: [{
    path: "src/locales/{locale}",
    include: ["src"]
    }],
    format: "po"
    }

    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.

  2. Add the following scripts to your package.json:

    package.json
    {
    "scripts": {
    "messages:extract": "lingui extract"
    }
    }
  3. 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 │ 00
    │ en │ 00
    │ fr │ 00
    └──────────┴─────────────┴─────────┘

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