Registry / web-framework / unplugin-lingui-macro

unplugin-lingui-macro

library0.3.1jsnpmunverified

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.

web-framework serialization

npm install unplugin-lingui-macro

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNPLUGIN-LINGUI-MA

unplugin-lingui-macro

web-frameworkjavascriptv0.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

linguiMacro

✓ import linguiMacro from 'unplugin-lingui-macro/vite';

✗ const linguiMacro = require('unplugin-lingui-macro');

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.

✓ 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.

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}!`;

Debug

Known issues

breakingVersion 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.

affects: >=0.3.0

gotchaThis 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.

affects: >=0.1.0

gotchaThe 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`.

affects: >=0.1.0

gotchaThis 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.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'unplugin-lingui-macro/vite'

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.

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

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.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

@lingui/confrequiredRequired for Lingui configuration discovery and processing during macro compilation.

esbuildoptionalPeer dependency for esbuild integration.

rolldownoptionalPeer dependency for Rolldown integration.

rollupoptionalPeer dependency for Rollup integration (versions 3 or 4).

viteoptionalPeer dependency for Vite integration (version 3 or greater).

webpackoptionalPeer dependency for Webpack integration (versions 4 or 5).

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/SegaraRai/lingui-for ↗

packagehttps://www.npmjs.com/package/unplugin-lingui-macro ↗

homepagehttps://lingui-for.roundtrip.dev/guides/install-and-first-translation ↗