Lingui Best Practices

Lingui Best Practices

Lingui is a powerful internationalization (i18n) framework for JavaScript. This skill covers best practices for implementing i18n in React and vanilla JavaScript applications.

Quick Start Workflow

The standard Lingui workflow consists of these steps:

1. Wrap your app in I18nProvider
2. Mark messages for translation using macros (Trans, t, etc.)
3. Extract messages: lingui extract
4. Translate the catalogs
5. Compile catalogs: lingui compile
6. Load and activate locale in your app

Core Packages

Import from these packages:

// React macros (recommended)
import { Trans, Plural, Select, useLingui } from "@lingui/react/macro";

// Core macros for vanilla JS
import { t, msg, plural, select } from "@lingui/core/macro";

// Runtime (rarely used directly)
import { I18nProvider } from "@lingui/react";
import { i18n } from "@lingui/core";

Setup I18nProvider

Wrap your application with I18nProvider:

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

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

function App() {
  return (
    <I18nProvider i18n={i18n}>
      {/* Your app */}
    </I18nProvider>
  );
}

Translating UI Text

Choosing the Right Macro

Work through these questions in order:

1. Does the message depend on a count? → Plural (JSX) or plural (strings). Never wrap a count-dependent string in plain Trans — that bakes English plural rules into the message.
2. Is it JSX content? → Trans
3. Is it a string inside a component (attribute, alert, function argument)? → useLingui() + t`...`
4. Is it defined outside a component (module scope, constants, config)? → msg descriptor, resolved with t(descriptor) or _(descriptor) at render time
5. Is it in non-React code? → t from @lingui/core/macro

If the string needs a translator comment, take the object form of whichever macro the tree picks — t`…` and msg`…` have nowhere to attach one. Deciding that while you wrap costs nothing; converting a whole codebase afterwards does not. See the enhanced-message-context skill.

Some destinations expect a plain string and will not take a macro at all — a Zod message, a count inside an aria-label, a server function's return value, an Intl formatter. Those have their own recipes: integration-recipes.md.

Use Trans for JSX Content

The Trans macro is the primary way to translate JSX:

import { Trans } from "@lingui/react/macro";

// Simple text
<Trans>Hello World</Trans>

// With variables
<Trans>Hello {userName}</Trans>

// With components (rich text)
<Trans>
  Read the <a href="/docs">documentation</a> for more info.
</Trans>

// Extracted as: "Read the <0>documentation</0> for more info."

When to use: For any translatable text in JSX elements.

Use useLingui for Non-JSX

For strings outside JSX (attributes, alerts, function calls):

import { useLingui } from "@lingui/react/macro";

function MyComponent() {
  const { t } = useLingui();

  const handleClick = () => {
    alert(t`Action completed!`);
  };

  return (
    <div>
      <img src="..." alt={t`Image description`} />
      <button onClick={handleClick}>{t`Click me`}</button>
    </div>
  );
}

When to use: Element attributes, alerts, function parameters, any non-JSX string.

The macro hook returns i18n as well as t, and both are bound to the React context — so one hook covers reading the active locale, formatting against it, and subscribing the component to locale changes. One import covers it — the runtime useLingui from @lingui/react is for code that has no macro transform:

import { useLingui } from "@lingui/react/macro";

const { t, i18n } = useLingui();
i18n.locale;                       // "de-DE" — the active locale
new Intl.NumberFormat(i18n.locale) // format against it

Use msg for Lazy Translations

When you need to define messages at module level or in arrays/objects:

import { msg } from "@lingui/core/macro";
import { useLingui } from "@lingui/react";

// Module-level constants
const STATUSES = {
  active: msg`Active`,
  inactive: msg`Inactive`,
  pending: msg`Pending`,
};

function StatusList() {
  const { _ } = useLingui();
  
  return Object.entries(STATUSES).map(([key, message]) => (
    <div key={key}>{_(message)}</div>
  ));
}

When to use: Module-level constants, arrays of messages, conditional message selection.

Descriptors change the field's type

msg turns a string field into a MessageDescriptor, so TypeScript points at every consuming site — which is what makes this conversion safe to apply in bulk. Two things get through it:

React keys keep compiling. key={item.label} becomes an object key, which React stringifies to [object Object] — identical for every row, so reconciliation degrades and the only signal is a console warning. Key on an identifier, never on the copy:

// ❌ compiles; every key is now identical
{NAV.map((item) => <li key={item.label}>{t(item.label)}</li>)}

// ✅
{NAV.map((item) => <li key={item.to}>{t(item.label)}</li>)}

String methods become type errors with a tempting wrong fix. LABELS[k].toLowerCase() fails to compile — correctly — but t(LABELS[k]).toLowerCase() is not the repair. Lower-casing a translation breaks languages that capitalise by rule (German nouns) and is a no-op in scripts without case. If a lower-case variant is really needed, it is a second message with its own comment.

Pluralization

Use the Plural macro for quantity-dependent messages:

import { Plural } from "@lingui/react/macro";

<Plural 
  value={messageCount}
  one="You have # message"
  other="You have # messages"
/>

The # placeholder is replaced with the actual value.

Exact Matches

Use _N syntax for exact number matches (takes precedence over plural forms):

<Plural
  value={count}
  _0="No messages"
  one="One message"
  other="# messages"
/>

With Variables and Components

Combine with Trans for complex messages:

<Plural
  value={count}
  one={`You have # message, ${userName}`}
  other={
    <Trans>
      You have <strong>#</strong> messages, {userName}
    </Trans>
  }
/>

Formatting Dates and Numbers

Use Intl directly:

import { useLingui } from '@lingui/react/macro';

function MyComponent() {
  const { i18n } = useLingui();
  const lastLogin = new Date();
  const dateFormatter = useMemo(() => new Intl.DateTimeFormat(i18n.locale), [i18n.locale]);
  return <Trans>Last login: {dateFormatter.format(lastLogin)}</Trans>;
}

Message IDs and Context

Explicit IDs

Provide a custom ID for stable message keys:

<Trans id="header.welcome">Welcome to our app</Trans>

Context for Disambiguation

When the same text has different meanings, use context:

<Trans context="direction">right</Trans>
<Trans context="correctness">right</Trans>

These create separate catalog entries.

Use context only when the same text genuinely needs different translations — not as a namespacing scheme (auth.login, settings.title). Identical strings with identical meaning should share one catalog entry so they are translated once.

Comments for Translators

Add context for translators:

<Trans comment="Greeting shown on homepage">Hello World</Trans>

Configuration

Basic lingui.config.js:

import { defineConfig } from "@lingui/cli";

export default defineConfig({
  sourceLocale: "en",
  locales: ["en", "es", "fr", "de"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
      exclude: ["**/node_modules/**"],
    },
  ],
});

For detailed configuration patterns, see configuration.md.

Lingui 6 Notes

Lingui 6 (April 2026) is ESM-only and requires Node.js ≥ 22.19 (or ≥ 24). If the project can't meet that, pin all @lingui/* packages to ^5.

The deprecated string form format: "po" and the formatOptions option were removed in v6. Omit format entirely (PO remains the default), or pass a formatter instance to configure it:

import { defineConfig } from "@lingui/cli";
import { formatter } from "@lingui/format-po";

export default defineConfig({
  // ...
  format: formatter({ lineNumbers: false }),
});

lineNumbers: false keeps catalog diffs small — line-number comments change on almost every source edit.