Unplugin for Lingui Macros

0.3.1 · active · verified Tue Apr 21

unplugin-lingui-macro is a bundler-agnostic plugin that compiles Lingui macros in plain JavaScript and TypeScript modules. It provides `unplugin` entrypoints for various build tools including Vite, Rollup, Webpack, esbuild, Rolldown, Rspack, and Bun. This package is specifically designed for applications that use Lingui macros outside of framework-specific files (e.g., `.svelte` or `.astro`), where dedicated framework plugins handle the transformation. The current stable version is 0.3.1, with releases occurring as part of the broader `lingui-for` monorepo, suggesting an active but coordinated release cadence. A key differentiator is its focus on generic JS/TS files, offering optional `linguiConfig` overrides for macro and runtime bindings, but it does not perform Lingui message extraction; that remains a task for `@lingui/cli` and related extractors.

Common errors

```
Error: Cannot find module 'unplugin-lingui-macro/vite'
```
cause Incorrect or missing bundler-specific suffix in the import path (e.g., `/vite`, `/rollup`, `/webpack`).

fix Ensure you are importing the plugin with the correct suffix for your bundler, e.g., `import linguiMacro from 'unplugin-lingui-macro/vite';` for Vite.
```
Internal server error: The macro you imported from "@lingui/react/macro" is not transformed.
```
cause The `unplugin-lingui-macro` plugin might not be correctly configured or enabled in your bundler, or `unplugin-auto-import` is not working as expected.

fix Verify that `unplugin-lingui-macro` is added to your bundler's plugin list (e.g., `plugins: [linguiMacro()]` in Vite config). Ensure that Lingui dependencies are correctly installed and version compatible.
```
[plugin:unplugin-lingui-macro] ReferenceError: i18n is not defined
```
cause The `@lingui/core` package, which provides the `i18n` runtime, is either not installed or not correctly configured/imported at runtime.

fix Install `@lingui/core` as a runtime dependency (`npm install @lingui/core`) and ensure that Lingui's `I18nProvider` (if using React) or `i18n` instance is initialized and available where needed.

Warnings

breaking Version 0.3.0 unified transform-time Lingui config loading around a new `config` option and `defineConfig` helpers. Old methods for configuring Lingui through the plugin options might be removed or behave differently.
Fix: Review your `linguiConfig` plugin options and migrate to the new `config` option structure as described in the documentation, potentially utilizing `defineConfig` helpers if available.
gotcha This plugin requires `@lingui/core` version `^5.0.0` and Node.js 22+ for proper operation. Using older versions may lead to unexpected errors or incompatible macro compilation.
Fix: Ensure your project's `package.json` specifies `@lingui/core` at `^5.0.0` or higher and that you are running Node.js 22 or newer. Update dependencies if necessary.
gotcha The plugin is designed for plain JavaScript and TypeScript modules only. For framework-specific files (e.g., `.svelte` or `.astro`), you should use the corresponding framework-specific Lingui plugins like `lingui-for-svelte` or `lingui-for-astro`.
Fix: If working with framework-owned files, ensure you are using the correct framework-specific Lingui plugin in addition to or instead of `unplugin-lingui-macro`.
gotcha This plugin is solely responsible for compiling Lingui macros at build time; it does not perform message extraction. You still need to configure and run `@lingui/cli` with appropriate extractors for translation message extraction.
Fix: Set up `@lingui/cli` in your project, including `lingui extract` commands in your build pipeline, to manage the extraction of translatable messages from your source code.

Install

npm install unplugin-lingui-macro npm
yarn add unplugin-lingui-macro yarn
pnpm add unplugin-lingui-macro pnpm

Imports

linguiMacro
wrong:
```
const linguiMacro = require('unplugin-lingui-macro');
```
correct:
```
import linguiMacro from 'unplugin-lingui-macro/vite';
```
Import the specific bundler-suffixed entrypoint (e.g., `/vite`, `/rollup`, `/webpack`) for the chosen build tool. The base `unplugin-lingui-macro` can also be imported if using `createUnplugin` directly. CommonJS `require` is generally not used for modern bundler plugins.
defineConfig
```
import { defineConfig } from 'vite';
```
Used for defining Vite configuration. While not directly from `unplugin-lingui-macro`, it's a standard part of integrating plugins into Vite.
t
```
import { t } from '@lingui/core/macro';
```
This is a Lingui macro import that `unplugin-lingui-macro` processes. The plugin automatically detects imports from `@lingui/core/macro`, `@lingui/macro`, and `@lingui/react/macro`.
LinguiMacroOptions
```
import type { LinguiMacroOptions } from 'unplugin-lingui-macro/types';
```
For TypeScript users, import the options type from the `/types` entrypoint to get correct type hints for the plugin configuration.

Quickstart

This quickstart demonstrates how to integrate `unplugin-lingui-macro` into a Vite project using TypeScript, including basic plugin configuration and an example of how Lingui macros are used in a plain JavaScript/TypeScript module.

import { defineConfig } from "vite";
import linguiMacro from "unplugin-lingui-macro/vite";

export default defineConfig({
  plugins: [
    linguiMacro({
      linguiConfig: {
        runtimeConfigModule: {
          i18n: ["@lingui/core", "i18n"],
        },
      },
    }),
  ],
});

// Example of usage in a plain TS/JS module:
// src/constants.ts
import { t } from "@lingui/core/macro";

export const pageTitle = t`Settings`;
export const welcomeMessage = (name: string) => t`Hello, ${name}!`;

view raw JSON →