{"id":15890,"library":"unplugin-lingui-macro","title":"Unplugin for Lingui Macros","description":"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.","status":"active","version":"0.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/SegaraRai/lingui-for","tags":["javascript","esbuild","i18n","lingui","rolldown","rollup","rspack","unplugin","vite","typescript"],"install":[{"cmd":"npm install unplugin-lingui-macro","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-lingui-macro","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-lingui-macro","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Lingui configuration discovery and processing during macro compilation.","package":"@lingui/conf","optional":false},{"reason":"Peer dependency for esbuild integration.","package":"esbuild","optional":true},{"reason":"Peer dependency for Rolldown integration.","package":"rolldown","optional":true},{"reason":"Peer dependency for Rollup integration (versions 3 or 4).","package":"rollup","optional":true},{"reason":"Peer dependency for Vite integration (version 3 or greater).","package":"vite","optional":true},{"reason":"Peer dependency for Webpack integration (versions 4 or 5).","package":"webpack","optional":true}],"imports":[{"note":"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.","wrong":"const linguiMacro = require('unplugin-lingui-macro');","symbol":"linguiMacro","correct":"import linguiMacro from 'unplugin-lingui-macro/vite';"},{"note":"Used for defining Vite configuration. While not directly from `unplugin-lingui-macro`, it's a standard part of integrating plugins into Vite.","symbol":"defineConfig","correct":"import { defineConfig } from 'vite';"},{"note":"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`.","symbol":"t","correct":"import { t } from '@lingui/core/macro';"},{"note":"For TypeScript users, import the options type from the `/types` entrypoint to get correct type hints for the plugin configuration.","symbol":"LinguiMacroOptions","correct":"import type { LinguiMacroOptions } from 'unplugin-lingui-macro/types';"}],"quickstart":{"code":"import { defineConfig } from \"vite\";\nimport linguiMacro from \"unplugin-lingui-macro/vite\";\n\nexport default defineConfig({\n  plugins: [\n    linguiMacro({\n      linguiConfig: {\n        runtimeConfigModule: {\n          i18n: [\"@lingui/core\", \"i18n\"],\n        },\n      },\n    }),\n  ],\n});\n\n// Example of usage in a plain TS/JS module:\n// src/constants.ts\nimport { t } from \"@lingui/core/macro\";\n\nexport const pageTitle = t`Settings`;\nexport const welcomeMessage = (name: string) => t`Hello, ${name}!`;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Incorrect or missing bundler-specific suffix in the import path (e.g., `/vite`, `/rollup`, `/webpack`).","error":"Error: Cannot find module 'unplugin-lingui-macro/vite'"},{"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.","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.","error":"Internal server error: The macro you imported from \"@lingui/react/macro\" is not transformed."},{"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.","cause":"The `@lingui/core` package, which provides the `i18n` runtime, is either not installed or not correctly configured/imported at runtime.","error":"[plugin:unplugin-lingui-macro] ReferenceError: i18n is not defined"}],"ecosystem":"npm"}