Lingui

https://github.com/lingui/js-lingui
Admin
Lingui is a lightweight, open-source internationalization (i18n) library for JavaScript and...
Tokens:196,953
Snippets:1,344
Trust Score:8.8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Import macros from @lingui/core/macro (t, plural, select, msg) and @lingui/react/macro (Trans, Plural, Select, useLingui). The i18n object comes from @lingui/core and I18nProvider from @lingui/react.
- Do not import from the deprecated @lingui/macro package and do not rely on babel-plugin-macros; use the per-package macro entry points.
- Macros are expanded at build time: register @lingui/babel-plugin-lingui-macro in the Babel config or @lingui/swc-plugin in the SWC config (for example in next.config.js).
- Do not call t, plural or select at module level, they return a fixed string once. Use msg or defineMessage for module-level constants and translate them with i18n._ where rendered.
- Wrap the React tree in I18nProvider with an i18n instance that has a catalog loaded and a locale activated (i18n.load then i18n.activate, or i18n.loadAndActivate).
- In React components, use Trans for text with markup and the t returned by the useLingui macro for strings outside JSX such as attributes, so the component re-renders when the locale changes.
- Message IDs are generated from the source text by default; do not invent keys. If the project uses explicit ids, follow its convention.
- After adding or changing messages run lingui extract to update the PO catalogs, then lingui compile to produce the runtime catalogs before building. Configuration lives in lingui.config.js or lingui.config.ts.
- In React Server Components, call setI18n from @lingui/react/server in every page and layout; Trans and useLingui from @lingui/react/macro then work in both server and client components.
- Catalogs are PO files by default. Translators edit the .po files; the compiled catalogs are build output and should not be edited by hand.
- Lingui 6 requires Node.js 22.19 or newer and ships ESM-only packages.

================
CODE SNIPPETS
================
### Install @lingui/vite-plugin, @lingui/swc-plugin, and @lingui/react for SWC setup

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Install the required packages for using Lingui with Vite and SWC. @lingui/vite-plugin and @lingui/swc-plugin are development dependencies, @lingui/react is a runtime dependency.

```bash
npm install --save-dev @lingui/vite-plugin @lingui/swc-plugin
npm install --save @lingui/react
```

--------------------------------

### Install @lingui/vite-plugin, @rolldown/plugin-babel, and @lingui/react for Rolldown setup

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Install the required packages for using Lingui with Vite 8+ and Rolldown. @lingui/vite-plugin and @rolldown/plugin-babel are development dependencies, @lingui/react is a runtime dependency.

```bash
npm install --save-dev @lingui/vite-plugin @rolldown/plugin-babel
npm install --save @lingui/react
```

--------------------------------

### Install @lingui/react with npm

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/react.md

Install the @lingui/react package using npm. This is the standard installation command for the React integration.

```bash
npm install --save @lingui/react
```

--------------------------------

### Install @lingui/babel-plugin-lingui-macro

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Install the Babel macro plugin as a development dependency. Required for Babel-based setups unless a preset already includes the macros plugin.

```bash
npm install --save-dev @lingui/babel-plugin-lingui-macro
```

--------------------------------

### Install @lingui/metro-transformer

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/metro-transformer.mdx

Install the transformer as a development dependency.

```bash
npm install --save-dev @lingui/metro-transformer
```

--------------------------------

### Install @lingui/vite-plugin and @lingui/react

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Installation commands for the Vite plugin as a development dependency and the React runtime dependency.

```bash
npm install --save-dev @lingui/vite-plugin
npm install --save @lingui/react
```

--------------------------------

### Install @lingui/core and @lingui/solid

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/solid.md

Install the required Lingui packages for Solid projects using npm.

```bash
npm install --save @lingui/core @lingui/solid
```

--------------------------------

### Install @lingui/loader

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/loader.md

Install the loader as a development dependency.

```bash
npm install --save-dev @lingui/loader
```

--------------------------------

### Install @lingui/swc-plugin

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Install the SWC plugin as a development dependency. SWC is faster than Babel but plugin support is experimental.

```bash
npm install --save-dev @lingui/swc-plugin
```

--------------------------------

### Install ESLint

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/eslint-plugin.md

Install ESLint as a dev dependency. Required before installing the plugin.

```bash
npm install --save-dev eslint
```

--------------------------------

### Install @lingui/swc-plugin with npm

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/swc-plugin.md

Install the plugin as a development dependency using npm or yarn.

```bash
npm install --save-dev @lingui/swc-plugin
```

--------------------------------

### Legacy Config Recommended Setup

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/eslint-plugin.md

Enable all recommended rules for the plugin using the legacy .eslintrc format.

```json
{
  "extends": ["plugin:lingui/recommended"]
}
```

--------------------------------

### Install @lingui/core with npm

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/core.md

Install the core package using npm. This is the first step to use the i18n object.

```bash
npm install --save @lingui/core
```

--------------------------------

### Install Lingui dependencies

Source: https://github.com/lingui/js-lingui/blob/main/README.md

Install the core and React packages along with the CLI as a development dependency.

```bash
npm install @lingui/core @lingui/react
npm install --save-dev @lingui/cli
```

--------------------------------

### Install @lingui/native-tools

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/custom-extractor.md

Install the native-tools package to use the SWC-based extractor for Babel-free extraction.

```bash
npm install --save-dev @lingui/native-tools
```

--------------------------------

### Flat Config Recommended Setup

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/eslint-plugin.md

Enable all recommended rules for the plugin using the flat config format (ESLint 8+).

```js
import pluginLingui from "eslint-plugin-lingui";

export default [
  pluginLingui.configs["flat/recommended"],
  // Any other config...
];
```

--------------------------------

### PO file example with placeholders

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Shows how messages with placeholders are exported, including a comment indicating the placeholder mapping.

```po
#. placeholder {0}: user.name
msgid "Hello {0} {value}"
msgstr "Hello {0} {value}"

```

--------------------------------

### Example of t-macro usage

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/releases/migration-5.md

A basic example of using the t-macro with placeholders.

```js
t`Hello ${user.name} ${value}`;
```

--------------------------------

### PO file example with message context

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Shows how messages with context are exported, using msgctxt to specify the context.

```po
#: src/Inbox.js:12
msgctxt "my context"
msgid "msg.inbox"
msgstr "Message Inbox"

```

--------------------------------

### Install @lingui/format-json

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Install the JSON formatter package as a dev dependency using npm or yarn.

```bash
npm install --save-dev @lingui/format-json
```

--------------------------------

### Install @lingui/format-po-gettext

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Installs the PO Gettext formatter as a dev dependency using npm or yarn.

```bash
npm install --save-dev @lingui/format-po-gettext

```

--------------------------------

### Install @lingui/format-csv

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Install the CSV formatter package as a dev dependency using npm or yarn.

```bash
npm install --save-dev @lingui/format-csv
```

--------------------------------

### Install @lingui/cli

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/cli.md

Installs the Lingui CLI as a development dependency.

```bash
npm install --save-dev @lingui/cli
```

--------------------------------

### Install eslint-plugin-lingui

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/eslint-plugin.md

Install the Lingui ESLint plugin as a dev dependency. If ESLint is installed globally, the plugin must also be installed globally.

```bash
npm install --save-dev eslint-plugin-lingui
```

--------------------------------

### lingui compile --output-prefix examples

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/cli.md

Examples for customizing the header added to compiled catalogs. The default prefix is /*eslint-disable*/; use --output-prefix to provide a custom string for tools like Oxlint or Biome, or an empty string to remove it.

```shell
# For Oxlint
lingui compile --output-prefix "/*oxlint-disable*/"
```

```shell
# For Biome
lingui compile --output-prefix "/*biome-ignore lint: auto-generated*/"
```

```shell
# For no prefix at all
lingui compile --output-prefix ""
```

--------------------------------

### Install Lingui Agent Skills with Plugins CLI

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ai-tools.md

Auto-detects your installed agent tools and installs the Lingui skills through each one's native plugin system.

```shell
npx plugins add lingui/skills
```

--------------------------------

### Install @lingui/vite-plugin as a dev dependency

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/vite-plugin.md

Install the plugin using npm. This is the first step to integrate Lingui with Vite.

```bash
npm install --save-dev @lingui/vite-plugin
```

--------------------------------

### Detect locale with detect method

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/locale-detector.md

Use the detect method to get the first valid locale from multiple detectors. The example passes fromUrl, fromStorage, fromNavigator, and a fallback function that returns "en". The result is logged as "en".

```jsx
import { detect, fromUrl, fromStorage, fromNavigator } from "@lingui/detect-locale";

// can be a function with custom logic or just a string, `detect` method will handle it
const DEFAULT_FALLBACK = () => "en";

const result = detect(fromUrl("lang"), fromStorage("lang"), fromNavigator(), DEFAULT_FALLBACK);

console.log(result); // "en"
```

--------------------------------

### Install @lingui/extractor-vue

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/extractor-vue.md

Install the extractor as a dev dependency using npm.

```bash
npm install --save-dev @lingui/extractor-vue
```

--------------------------------

### I18nProvider setup with defaultComponent

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/react.md

Shows how to load and activate a locale, then wrap the app with I18nProvider, passing an optional defaultComponent for rendering translations.

```jsx
import React from "react";
import { I18nProvider } from "@lingui/react";
import { i18n } from "@lingui/core";
import { messages as messagesEn } from "./locales/en/messages.js";

i18n.load({
  en: messagesEn,
});
i18n.activate("en");

const DefaultI18n = ({ children }) => <span>{children}</span>;

const App = () => {
  return (
    <I18nProvider i18n={i18n} defaultComponent={DefaultI18n}>
      // rest of the app
    </I18nProvider>
  );
};
```

--------------------------------

### Flat Config Custom Setup

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/eslint-plugin.md

Load the plugin and configure only the rules you want to use in flat config format.

```js
import pluginLingui from "eslint-plugin-lingui";

export default [
  {
    plugins: {
      lingui: pluginLingui,
    },
    rules: {
      "lingui/t-call-in-function": "error",
    },
  },
  // Any other config...
];
```

--------------------------------

### Install @lingui/detect-locale

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/locale-detector.md

Install the @lingui/detect-locale package using npm. The package is lightweight (~1 kB Gzip) and provides locale detection methods.

```bash
npm install --save @lingui/detect-locale
```

--------------------------------

### Install Crowdin CLI

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/tools/crowdin.md

Installs the Crowdin CLI as a development dependency using npm.

```bash
npm install --save-dev @crowdin/cli
```

--------------------------------

### Configure esbuild bundler in lingui.config.ts

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/message-extraction.md

Example configuration using createEsbuildBundler in the experimental extractor. It shows how to include dependencies via includeDeps.

```typescript
import { defineConfig } from "@lingui/conf";
import { createEsbuildBundler } from "@lingui/cli/bundlers/esbuild";

export default defineConfig({
  locales: ["en", "fr"],
  catalogs: [],
  experimental: {
    extractor: {
      entries: ["<rootDir>/src/pages/**/*.tsx"],
      output: "<rootDir>/{entryDir}/locales/{entryName}/{locale}",
      bundler: createEsbuildBundler({
        includeDeps: ["@my-company/shared"],
      }),
    },
  },
});
```

--------------------------------

### Install a single Lingui Agent Skill

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ai-tools.md

Installs a single skill instead of the full set by passing `--skill` to the Skills CLI.

```shell
npx skills add lingui/skills --skill lingui-best-practices
```

--------------------------------

### Uninstalling plugins and updating Babel config

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/releases/migration-3.md

Instructions for removing legacy presets and installing the required macro dependencies.

```bash
npm uninstall @lingui/babel-preset-react
npm install --dev @lingui/macro babel-plugin-macros
```

```diff
{
   "presets": [
-      "@lingui/babel-preset-react"
   ],
   "plugins": [
+      "macros",
   ]
}
```

--------------------------------

### Install @lingui/format-po

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Install the PO format package using npm or yarn. This is required to use the PO catalog format.

```bash
npm install --save-dev @lingui/format-po
```

--------------------------------

### Install Lingui Agent Skills as Gemini CLI extension

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ai-tools.md

Installs the Lingui skills as a Gemini CLI extension.

```shell
gemini extensions install https://github.com/lingui/skills
```

--------------------------------

### Install Lingui Agent Skills with GitHub CLI

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ai-tools.md

Installs the Lingui skills for GitHub Copilot or any other supported agent. Use `--agent <name>` to target a specific tool, and `gh skill update` to pull newer versions.

```shell
gh skill install lingui/skills --all
```

--------------------------------

### compileNamespace window.i18n example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Shows the output when compileNamespace is set to 'window.i18n', assigning the compiled messages to the window object. The example uses the identifier 'i18n'.

```js
/* eslint-disable */window.i18n={messages: {"..."}}
```

--------------------------------

### Example usage of new macro imports

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/releases/migration-5.md

Demonstrates importing Trans from @lingui/react/macro and msg from @lingui/core/macro, and using them in a React component. This shows the new import paths in action.

```jsx
import { Trans } from "@lingui/react/macro";
import { msg } from "@lingui/core/macro";

const colors = [msg`Red`, msg`Yellow`, msg`Green`];

function MyComponent() {
  <Trans>Hi, my name is {name}</Trans>;
}
```

--------------------------------

### Install esbuild for message extraction

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/message-extraction.md

Install the esbuild package as a dev dependency. esbuild is the default bundler and requires no additional configuration.

```bash
npm install --save-dev esbuild
```

--------------------------------

### i18n.number formatting examples

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/core.md

Demonstrates i18n.number with default and currency formats for English and Czech locales, showing the returned strings.

```ts
import { i18n } from "@lingui/core";

i18n.activate("en");
i18n.number(12345.678);
// Returns "12,345.678"

i18n.number(12345.678, { style: "currency", currency: "USD" });
// Returns "$12,345.68"

i18n.activate("cs");
i18n.number(12345.678);
// Returns "12 345,678"

i18n.number(12345.678, { style: "currency", currency: "CZK" });
// Returns "12 345,68 Kč"
```

--------------------------------

### Legacy Config Custom Setup - Rules

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/eslint-plugin.md

Configure the rules you want to use in the rules section of .eslintrc.

```json
{
  "rules": {
    "lingui/no-unlocalized-strings": 2,
    "lingui/t-call-in-function": 2,
    "lingui/no-single-variables-to-translate": 2,
    "lingui/no-expression-in-message": 2,
    "lingui/no-single-tag-to-translate": 2,
    "lingui/no-trans-inside-trans": 2,
    "lingui/no-unnamed-tag-placeholders": 2
  }
}
```

--------------------------------

### Configure Lingui for Solid with defineConfig

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/solid.md

Use defineConfig from @lingui/solid/config to apply Solid-specific settings. This example sets locales, sourceLocale, and catalog paths.

```ts
import { defineConfig } from "@lingui/solid/config";

export default defineConfig({
  locales: ["en", "cs"],
  sourceLocale: "en",
  catalogs: [
    {
      path: "src/locales/{locale}",
      include: ["src"],
    },
  ],
});
```

--------------------------------

### Install Lingui Agent Skills with Skills CLI

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ai-tools.md

Installs the full set of Lingui Agent Skills using the Skills CLI. Works with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and other compatible agents.

```shell
npx skills add lingui/skills
```

--------------------------------

### Dynamic import of PO catalogs

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/loader.md

Example of dynamically importing a PO file using the configured loader.

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

--------------------------------

### Configure vite.config.ts for Vite 8+ with Rolldown

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Setup Lingui in vite.config.ts using @rolldown/plugin-babel with the preset linguiTransformerBabelPreset. This setup does not require Babel or SWC by default.

```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingui, linguiTransformerBabelPreset } from "@lingui/vite-plugin";
import babel from "@rolldown/plugin-babel";

export default defineConfig({
  plugins: [
    react(),
    lingui(),
    babel({
      presets: [linguiTransformerBabelPreset()],
    }),
  ],
});
```

--------------------------------

### Legacy Config Custom Setup - Plugins

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/eslint-plugin.md

Add the plugin to the plugins section of .eslintrc. The eslint-plugin- prefix can be omitted.

```json
{
  "plugins": ["lingui"]
}
```

--------------------------------

### compileNamespace json example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Shows the output when compileNamespace is set to 'json', producing a JSON file with a messages object.

```json
{"messages": {"..."}}
```

--------------------------------

### Equivalent plain Lingui config without defineConfig

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/tutorials/solid.md

This is the equivalent configuration to the defineConfig example, but written as a plain object. It includes the same locales, sourceLocale, and catalogs, plus macro and runtimeConfigModule settings.

```ts
export default {
  locales: ["en", "cs"],
  sourceLocale: "en",
  catalogs: [
    {
      path: "src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
  macro: {
    jsxPackage: ["@lingui/solid/macro"],
    jsxRuntime: "solid",
  },
  runtimeConfigModule: {
    Trans: ["@lingui/solid", "Trans"],
    useLingui: ["@lingui/solid", "useLingui"],
  },
};
```

--------------------------------

### Setup: Wrap app in I18nProvider (src/index.js)

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/tutorials/react.md

Imports required Lingui modules, loads and activates the English catalog, and wraps the Inbox component in I18nProvider to provide the i18n instance to React components.

```jsx
import React from "react";
import ReactDOM from "react-dom/client";

import { i18n } from "@lingui/core";
import { I18nProvider } from "@lingui/react";
import { messages } from "./locales/en/messages";
import Inbox from "./Inbox";

i18n.load("en", messages);
i18n.activate("en");

const App = () => (
  <I18nProvider i18n={i18n}>
    <Inbox />
  </I18nProvider>
);

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

--------------------------------

### Initialize project with npm run sync

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/tools/translation-io.md

Command to initialize the project and upload source text and existing translations.

```bash
npm run sync
```

--------------------------------

### Catalogs with {name} token in path

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Example configuration using the {name} token in the path and include patterns to create separate catalogs per component.

```json
{
  "catalogs": [
    {
      "path": "<rootDir>/components/{name}/locale/{locale}",
      "include": ["<rootDir>/components/{name}/"]
    }
  ]
}
```

--------------------------------

### Install rolldown for message extraction

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/message-extraction.md

Install the rolldown package as a dev dependency to use the rolldown bundler for message extraction.

```bash
npm install --save-dev rolldown
```

--------------------------------

### PO file example with comments and obsolete messages

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Shows the structure of a PO file with translator comments, source references, and an obsolete message.

```po
#: src/App.js:3
#. Comment for translators
msgid "messageId"
msgstr "Translated Message"

#: src/App.js:3
#, obsolete
msgid "obsoleteId"
msgstr "Obsolete Message"

```

--------------------------------

### setupI18n(options?)

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/core.md

Initializes and returns a new I18n instance. Typically called once and then the returned i18n object is used throughout the codebase.

```APIDOC
## setupI18n(options?)

### Description
Initializes and returns a new `I18n` instance. Typically, you should call this function only once and then use the returned `i18n` object throughout your entire codebase.

### Method
Function call

### Signature
`setupI18n([options])`

### Parameters
- **options** (object) - Optional - Configuration for the initial state of the `i18n` instance.
  - **locale** (string) - Optional - Initial active locale.
  - **locales** (string[]) - Optional - List of alternative locales (BCP-47 language tags) used for number and date formatting. If not set, the active locale is used.
  - **messages** (Messages) - Optional - Initial messages object.
  - **missing** (string | function) - Optional - A custom message to be returned when a translation is missing, or a function that receives the active locale and message ID as arguments.
  - **variables** (object) - Optional - Initial default message variables.

### Example
```ts
import { setupI18n } from "@lingui/core";

const i18n = setupI18n();
```

### Options Examples

#### options.locale
```tsx
import { setupI18n } from "@lingui/core";

const i18n = setupI18n({ locale: "en" });

// This is a shortcut for:
// const i18n = setupI18n()
// i18n.activate("en")
```

#### options.locales
```tsx
import { setupI18n } from "@lingui/core";

const i18n = setupI18n({
  locale: "ar",
  locales: ["en-UK", "ar-AS"],
});

// This is a shortcut for:
// const i18n = setupI18n()
// i18n.activate("ar", ["en-UK", "ar-AS"])
```

#### options.messages
```tsx
import { setupI18n } from "@lingui/core";

const messages = {
  en: require("./locale/en/messages").messages, // your path to compiled messages here
  cs: require("./locale/cs/messages").messages, // your path to compiled messages here
};
const i18n = setupI18n({ messages });

// This is a shortcut for:
// const i18n = setupI18n()
// i18n.load(messages)
```

#### options.missing
```tsx
import { setupI18n } from "@lingui/core";

const i18n = setupI18n({ missing: "🚨" });
i18n.t("missing translation") === "🚨"; // Returns the custom missing message
```

Alternatively, `missing` can be a function that receives the active locale and message ID as arguments:

```tsx
import { setupI18n } from "@lingui/core";

function missing(locale, id) {
  alert(`Translation in ${locale} for ${id} is missing!`);
  return id;
}

const i18n = setupI18n({ missing });
i18n.t("missing translation"); // Triggers an alert
```

#### options.variables
```tsx
import { setupI18n } from "@lingui/core";

const i18n = setupI18n({
  variables: {
    appName: "ExampleApp",
    version: "1.2.3",
  },
});

// This is a shortcut for:
// const i18n = setupI18n()
// i18n.setVariables({ appName: "ExampleApp", version: "1.2.3" })
```
```

--------------------------------

### Configure vite.config.ts for SWC (plugin-react-swc)

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Setup Lingui in vite.config.ts using @vitejs/plugin-react-swc with the SWC plugin linguiMacroSwcPlugin. SWC is significantly faster than Babel.

```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { lingui } from "@lingui/vite-plugin";
import { linguiMacroSwcPlugin } from "@lingui/swc-plugin/options";

export default defineConfig({
  plugins: [
    react({
      plugins: [linguiMacroSwcPlugin()],
    }),
    lingui(),
  ],
});
```

--------------------------------

### Detect multiple locales with multipleDetect method

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/locale-detector.md

Use the multipleDetect method to get an array of all locales detected by each detector. The example passes the same detectors as the detect example, and the result is logged as ["en", "es"].

```jsx
import { multipleDetect, fromUrl, fromStorage, fromNavigator } from "@lingui/detect-locale";

// can be a function with custom logic or just a string, `detect` method will handle it
const DEFAULT_FALLBACK = () => "en";

const result = multipleDetect(fromUrl("lang"), fromStorage("lang"), fromNavigator(), DEFAULT_FALLBACK);

console.log(result); // ["en", "es"]
```

--------------------------------

### CSV message example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Example CSV file with two columns: messageId and Message. The first row is a header, the second row shows a message with ID 'msg.common' and text 'String for translation'.

```csv
messageId,Message
msg.common,String for translation
```

--------------------------------

### Basic Message Formatting with Lingui

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/misc/react-intl.md

Example of using the Trans component in Lingui to achieve the same message formatting as react-intl.

```jsx
<Trans
  id="welcome"
  message={`Hello {name}, you have {unreadCount, number} {unreadCount, plural,
     one {message}
     other {messages}
   }`}
  values={{ name: <b>{name}</b>, unreadCount }}
/>
```

--------------------------------

### Memoize Intl.DateTimeFormat with useMemo in React

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/releases/migration-6.md

React example: memoize the Intl.DateTimeFormat formatter with useMemo so it updates when the locale changes. Uses useLingui() to get the i18n instance.

```tsx
const { i18n } = useLingui();
const dateFormatter = useMemo(() => new Intl.DateTimeFormat(i18n.locale, { dateStyle: "medium" }), [i18n.locale]);
```

--------------------------------

### Before: YAML configuration (.linguirc.yaml)

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/releases/migration-6.md

Example of the old YAML configuration format that is no longer supported in Lingui v6. Use this as a reference when migrating to the new JavaScript/TypeScript or JSON format.

```yaml
locales:
  - en
  - cs
sourceLocale: en
catalogs:
  - path: src/locales/{locale}/messages
    include:
      - src

```

--------------------------------

### JSX whitespace cleaning example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/releases/migration-5.md

Shows how JSX whitespace is cleaned in v5. The code is extracted as 'Hello◦◦◦world' without new lines at the start and end of the tag.

```jsx
// prettier-ignore
<Trans>
  Hello◦{"◦"}◦world
</Trans>
```

--------------------------------

### TypeScript flags invalid message IDs in t() and Trans

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/typed-message-ids.md

After setup, TypeScript will flag invalid IDs. The example shows valid usage with 'welcome.title', a type error for the misspelled 'welcme.title', and autocomplete in JSX with <Trans>. This snippet demonstrates the compile-time validation behavior.

```tsx
import { t } from "@lingui/core/macro";
import { Trans } from "@lingui/react";

// ✅ Valid — "welcome.title" exists in your catalog
const msg = t({ id: "welcome.title", message: "Welcome!" });

// ❌ Type error — "welcme.title" is not a known message ID
const bad = t({ id: "welcme.title", message: "Welcome!" });

// ✅ Autocomplete works in JSX too
<Trans id="welcome.title">Welcome!</Trans>;
```

--------------------------------

### Use lingui-set idPrefix with idPrefixLeader in JSX

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Shows how the idPrefixLeader affects explicit IDs in JSX. IDs starting with "." get the prefix (e.g., ".withPrefix" becomes "myPrefix.withPrefix"), while other IDs remain unchanged.

```jsx
// source
import { Trans } from "@lingui/react/macro"

// lingui-set idPrefix="myPrefix"
<Trans id=".withPrefix">With prefix</Trans> // id="myPrefix.withPrefix"
<Trans id="unprefixed">Unprefixed</Trans> // id="unprefixed"
```

--------------------------------

### SaveButton.tsx - Using useLingui and Trans in a shared package

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/monorepo.md

Example of a shared package component that uses useLingui to get the t function bound to the provider's i18n instance, and Trans for translation. This avoids using the global t from @lingui/core/macro, which would render untranslated text.

```tsx
import { Trans, useLingui } from "@lingui/react/macro";

export function SaveButton() {
  const { t } = useLingui(); // bound to the provider's i18n, not the global one
  return (
    <button aria-label={t`Save changes`}>
      <Trans>Save</Trans>
    </button>
  );
}
```

--------------------------------

### Optimized bundle structure (build directory listing)

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/dynamic-loading-catalogs.md

Shows the separate chunks generated for each language after building, demonstrating that only the main bundle and the first language bundle are loaded initially, with the second language bundle loaded on demand.

```bash
i18n-0.c433b3bd.chunk.js
i18n-1.f0cf2e3d.chunk.js
main.ab4626ef.js
```

--------------------------------

### Configure rolldown bundler in lingui.config.ts

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/message-extraction.md

Example configuration using createRolldownBundler in the experimental extractor. It sets locales, catalogs, and extractor entries/output.

```typescript
import { defineConfig } from "@lingui/conf";
import { createRolldownBundler } from "@lingui/cli/bundlers/rolldown";

export default defineConfig({
  locales: ["en", "fr"],
  catalogs: [],
  experimental: {
    extractor: {
      entries: ["<rootDir>/src/pages/**/*.tsx"],
      output: "<rootDir>/{entryDir}/locales/{entryName}/{locale}",
      bundler: createRolldownBundler(),
    },
  },
});
```

--------------------------------

### Lingui JSON catalog example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/catalog-formats.md

Outputs all internal data in JSON format, including translation, default message, description, origin, and obsolete flag.

```json
{
  "messageId": {
    "translation": "Translated message",
    "message": "Default message",
    "description": "Comment for translators",
    "origin": [["src/App.js", 3]]
  },
  "obsoleteId": {
    "translation": "Obsolete message",
    "origin": [["src/App.js", 3]],
    "obsolete": true
  }
}
```

--------------------------------

### i18next Basic Setup and Translation Retrieval

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/misc/i18next.md

Initializes i18next with an English translation for the key "key" and then renders the translation into an element. The second block shows how to retrieve the translation using i18next.t("key").

```js
import i18next from "i18next";

i18next.init({
  lng: "en",
  resources: {
    en: {
      translation: {
        key: "Hello world",
      },
    },
  },
});
```

```js
import i18next from "i18next";

document.getElementById("output").innerHTML = i18next.t("key");
```

--------------------------------

### Test Crowdin CLI version

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/tools/crowdin.md

Verifies that the Crowdin CLI is installed and accessible via npm scripts.

```bash
npm run crowdin --version
```

--------------------------------

### Example output of raw message ID in production

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/optimizing-bundle-size.md

Shows the raw message ID that users see in production when a message was not extracted before building.

```text
z3fd2
```

--------------------------------

### Non-macro usage examples for i18n.t and i18n._

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/message-extraction.md

Shows supported non-macro calls that the extractor matches by name, including member expressions like ctx.i18n.t(). The extractor does not verify imports from Lingui packages.

```ts
i18n.t("message.id");
i18n.t({ id: "message.id" });

ctx.i18n._("message.id");
ctx.i18n.t("message.id");

ctx.request.i18n.t("message.id");

// and so on
```

--------------------------------

### Custom compilerBabelOptions with jsescOption.minimal false

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Example configuration that sets jsescOption.minimal to false, causing the compiler to generate escaped ASCII characters.

```JSON
{
  "compilerBabelOptions": {
    "jsescOption": {
      "minimal": false
    }
  }
}
```

--------------------------------

### createRolldownBundler with macroTransform

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/message-extraction.md

Example of configuring the createRolldownBundler function with a macroTransform option to override macro and parser settings during bundling.

```APIDOC
## createRolldownBundler({ macroTransform })

### Description
Creates a Rolldown bundler for message extraction with optional macro transform overrides. The macroTransform option allows overriding macro options and SWC parser options.

### Method
Function call

### Endpoint
createRolldownBundler(options)

### Parameters
#### Options Object
- **macroTransform** (object) - Optional - Overrides for macro and parser options.
  - **macro** (object) - Optional - Overrides for macro options derived from Lingui configuration. Possible fields: `corePackage`, `jsxPackage`, `jsxPlaceholderAttribute`, `jsxPlaceholderDefaults`, `runtimeModules`, `idPrefixLeader`. The `descriptorFields` option is always `"all"` during extraction and cannot be overridden.
  - **parser** (object) - Optional - SWC parser options, same as `jsc.parser` in `.swcrc`. Syntax and JSX support are inferred from file name. Decorators are enabled by default. A custom parser replaces defaults, so set `decorators: true` if needed.

### Request Example
```ts
import { createRolldownBundler } from "@lingui/cli/bundlers/rolldown";

createRolldownBundler({
  macroTransform: {
    macro: {
      jsxPlaceholderAttribute: "_t",
    },
    parser: {
      syntax: "typescript",
      decorators: true,
    },
  },
});
```

### Response
No response value. The function returns a bundler instance.
```

--------------------------------

### I18nProvider setup with defaultComponent

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/solid.md

Sets up the I18nProvider with a loaded and activated locale, and a default component for rendering translations. The provider ensures children render only after locale activation and subscribes to i18n updates.

```jsx
import { I18nProvider } from "@lingui/solid";
import { i18n } from "@lingui/core";
import { messages as messagesEn } from "./locales/en/messages.js";

i18n.load({
  en: messagesEn,
});
i18n.activate("en");

const DefaultI18n = (props) => <span>{props.children}</span>;

const App = () => {
  return (
    <I18nProvider i18n={i18n} defaultComponent={DefaultI18n}>
      // rest of the app
    </I18nProvider>
  );
};
```

--------------------------------

### Direct Trans Component Usage Examples

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/react.md

Direct usage of the Trans component without macros. Shows how to pass id, message, values, comment, and components props for various translation scenarios.

```jsx
import React from "react";
import { Trans } from "@lingui/react";

const MyComponent = () => {
  return (
    <div>
      {/* Simple translation without dynamic values */}
      <Trans id="my.message" message="Hello World" />

      {/* Translation with dynamic values */}
      <Trans id="greeting" message="Hello {name}" values={{ name: "Arthur" }} />

      {/* Translation with a comment for translators */}
      <Trans id="hello.world" message="Hello world" comment="A message that greets the user" />

      {/* Translation with a component for formatting */}
      <Trans
        id="link"
        message="Read <link>Description</link> below."
        components={{ link: <a href="/docs">Documentation</a> }}
      />
    </div>
  );
};
```

--------------------------------

### Generated file header example with custom prefix

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/cli.md

Shows the output file header when using a custom --output-prefix. The prefix is placed before the exported messages constant, which parses an empty JSON object.

```js
/*your-prefix-here*/ export const messages = JSON.parse("{}");
```

--------------------------------

### ICU MessageFormat example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/optimizing-bundle-size.md

An example of a message using ICU MessageFormat syntax.

```js
"{count, plural, one {# item} other {# items}}";
```

--------------------------------

### Trans component usage

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/react.md

Examples of using the Trans component directly from @lingui/react, including simple translations, dynamic values, comments, components, and plurals.

```APIDOC
## Trans Component

### Description
Renders a translated message. The `id` prop identifies the message, `message` provides the default message, `values` interpolates dynamic values, `components` allows embedding React components, and `comment` provides context for translators.

### Props
- **id** (string) - Required - Key, the message ID
- **message** (string) - Optional - Default message
- **values** (object) - Optional - Variables to interpolate into the message
- **components** (object) - Optional - Components used for formatting the translation
- **comment** (string) - Optional - Context for translators

### Usage Examples

#### Simple translation without dynamic values
```jsx
import React from "react";
import { Trans } from "@lingui/react";

const MyComponent = () => {
  return (
    <div>
      <Trans id="my.message" message="Hello World" />
    </div>
  );
};
```

#### Translation with dynamic values
```jsx
import React from "react";
import { Trans } from "@lingui/react";

const MyComponent = () => {
  return (
    <div>
      <Trans id="greeting" message="Hello {name}" values={{ name: "Arthur" }} />
    </div>
  );
};
```

#### Translation with a comment for translators
```jsx
import React from "react";
import { Trans } from "@lingui/react";

const MyComponent = () => {
  return (
    <div>
      <Trans id="hello.world" message="Hello world" comment="A message that greets the user" />
    </div>
  );
};
```

#### Translation with a component for formatting
```jsx
import React from "react";
import { Trans } from "@lingui/react";

const MyComponent = () => {
  return (
    <div>
      <Trans
        id="link"
        message="Read <link>Description</link> below."
        components={{ link: <a href="/docs">Documentation</a> }}
      />
    </div>
  );
};
```

#### Plurals using ICU MessageFormat
```jsx
import React from "react";
import { Trans } from "@lingui/react";

const CarCount = ({ cars }) => {
  return (
    <Trans
      id="application.pages.carsList"
      message="{count, plural, =1 {# car} other {# cars}}"
      values={{ count: cars.length }}
    />
  );
};
```
```

--------------------------------

### Example PO catalog entry

Source: https://github.com/lingui/js-lingui/blob/main/README.md

The compiled PO file uses tags like <0> to represent HTML elements, ensuring translators do not modify markup.

```po
#: src/App.jsx:12
msgid "Read the <0>documentation</0> for more info."
msgstr "Přečtěte si <0>dokumentaci</0> pro více informací."
```

--------------------------------

### Trans component usage examples

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/solid.md

Demonstrates direct usage of the Trans component with id, message, values, comment, and components props for simple translations, dynamic values, translator comments, and component formatting.

```jsx
import { Trans } from "@lingui/solid";

const MyComponent = () => {
  return (
    <div>
      {/* Simple translation without dynamic values */}
      <Trans id="my.message" message="Hello World" />

      {/* Translation with dynamic values */}
      <Trans id="greeting" message="Hello {name}" values={{ name: "Arthur" }} />

      {/* Translation with a comment for translators */}
      <Trans id="hello.world" message="Hello world" comment="A message that greets the user" />

      {/* Translation with a component for formatting */}
      <Trans
        id="link"
        message="Read <link>Description</link> below."
        components={{
          link: (props) => <a href="/docs">{props.children}</a>,
        }}
      />
    </div>
  );
};
```

--------------------------------

### i18next Interpolation Example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/misc/i18next.md

Shows i18next interpolation with a named placeholder {{name}} and an explicit ID. The placeholder in the JSON file and the { name } in the call are matched by hand.

```js
import i18next from "i18next";

i18next.t("My name is {{name}}", { name: "Tom" });
i18next.t("msg.name", { name: "Tom" });
```

--------------------------------

### select macro usage and compiled output

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/macro.mdx

Example of using select to choose a pronoun based on gender, followed by the compiled i18n._ call with the ICU message format.

```js
import { select } from "@lingui/core/macro";
const message = select(gender, {
  male: "he",
  female: "she",
  other: "they",
});

// ↓ ↓ ↓ ↓ ↓ ↓

import { i18n } from "@lingui/core";

const message = i18n._(
  /** i18n */ {
    id: "VRptzI",
    message: "{gender, select, male {he} female {she} other {they}}",
    values: { gender },
  }
);
```

--------------------------------

### setupI18n basic usage

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/core.md

Initializes a new I18n instance with setupI18n. Typically called once and the returned i18n object is used throughout the codebase.

```ts
import { setupI18n } from "@lingui/core";

const i18n = setupI18n();
```

--------------------------------

### View Crowdin CLI help

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/tools/crowdin.md

Displays the full list of available commands and options for the Crowdin CLI.

```bash
npm run crowdin -h
```

--------------------------------

### Vite configuration with Lingui plugin (vite.config.ts)

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

Sets up the Lingui Vite plugin with macroTransform: true, enabling native macro transformation. This setup works with @vitejs/plugin-react and @vitejs/plugin-react-swc.

```typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingui } from "@lingui/vite-plugin";

export default defineConfig({
  plugins: [react(), lingui({ macroTransform: true })],
});
```

--------------------------------

### catalogsMergePath configuration example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Shows how to set catalogsMergePath in the configuration to merge separate catalogs into a single file per locale. The diff shows the configuration change and the resulting file structure, with removed files marked by '-' and added files by '+'.

```diff
{
  "catalogs": [
    {
      "path": "/locale/{locale}/{name}",
      "include": ["components/{name}/"]
    }
  ],
+ "catalogsMergePath": "locales/{locale}"
}
```

```diff
.
  ├── locale/
  │   ├── en/
  │   │   ├── RegistrationForm.po
- │   │   ├── RegistrationForm.js
  │   │   ├── LoginForm.po
- │   │   └── LoginForm.js
  │   └── cs/
  │       ├── RegistrationForm.po
- │       ├── RegistrationForm.js
  │       ├── LoginForm.po
- │       └── LoginForm.js
+ ├── locales/
+ │   ├── en.js
+ │   └── cs.js
  └── components/
      ├── RegistrationForm/
      │   ├── RegistrationForm.test.js
      │   └── RegistrationForm.js
      └── LoginForm/
          ├── LoginForm.test.js
          └── LoginForm.js
```

--------------------------------

### Install Lingui Agent Skills as Claude Code plugin

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ai-tools.md

Adds the Lingui skills as a Claude Code plugin. All skills load automatically and stay up to date via `/plugin marketplace update`.

```text
/plugin marketplace add lingui/skills
/plugin install lingui@lingui-skills
```

--------------------------------

### Use React Compiler with Lingui in Rolldown setup

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/installation.mdx

When using React Compiler with Lingui, place the React Compiler preset before the Lingui preset. Presets are applied in reverse order, so Lingui will be applied first.

```js
plugins: [
  react(),
  lingui(),
  babel({ presets: [reactCompilerPreset(), linguiTransformerBabelPreset()] }),
],
```

--------------------------------

### compile output example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/cli.md

Shows the structure of a compiled catalog file: a TypeScript export that parses a JSON string containing the messages object. The values are the translations keyed by translation IDs.

```ts
export const messages = JSON.parse(`{
// object with keys (translation ids) and values (translations)
}`);
```

--------------------------------

### extractorParserOptions configuration example

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Example configuration for the deprecated extractorParserOptions option. It shows the default values for tsExperimentalDecorators and flow, both set to false.

```JSON
{
  "extractorParserOptions": {
    "tsExperimentalDecorators": false,
    "flow": false
  }
}
```

--------------------------------

### Directory layout for app and package catalogs

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/guides/monorepo.md

Shows the expected folder structure for the app and the shared UI package, with separate locales directories and the merged output location.

```bash
apps/admin/
├── lingui.config.ts
├── locales/            # en.po, cs.po: the app's own messages
└── src/i18n/           # en.ts, cs.ts: merged, compiled output
packages/ui/
├── locales/            # en.po, cs.po: translated once, shared by every app
└── src/
```

--------------------------------

### Import Trans and useLingui from custom config

Source: https://github.com/lingui/js-lingui/blob/main/website/docs/ref/conf.md

Shows how to import the Trans and useLingui macros from a custom module in advanced scenarios.

```jsx
import { Trans, useLingui } from "./custom-config";
```
Tokens:
Raw