# Lingui

> Lingui is a lightweight, open-source internationalization (i18n) library for JavaScript and TypeScript. It brings compile-time macros and a CLI for message extraction to React, React Native, Vue, SolidJS, Astro, Svelte, and Node.js.


## Introduction

- [Introduction](https://lingui.dev/introduction.md): What Lingui is and how it works. A lightweight i18n library for JavaScript and TypeScript with compile-time macros and a message extraction CLI

## Installation

- [Installation and Setup](https://lingui.dev/installation.md): Learn how to install Lingui in your project

## Tutorials

- [JavaScript Apps Internationalization](https://lingui.dev/tutorials/javascript.md): Learn how to use Lingui's internationalization features in your vanilla JavaScript application
- [React Apps Internationalization](https://lingui.dev/tutorials/react.md): Learn how to add internationalization to a React application using Lingui
- [React Native Apps Internationalization](https://lingui.dev/tutorials/react-native.md): Learn how to add internationalization to a React Native application using Lingui
- [Next.js App Router i18n with React Server Components](https://lingui.dev/tutorials/react-rsc.md): Add internationalization to a Next.js App Router app with Lingui. Set up the SWC plugin, load catalogs in server and client components and switch languages
- [Solid Apps Internationalization](https://lingui.dev/tutorials/solid.md): Learn how to add internationalization to a SolidJS application using Lingui

## Guides

- [Custom Extractor](https://lingui.dev/guides/custom-extractor.md): Learn how to write a custom message extractor for your project
- [Custom Formatter](https://lingui.dev/guides/custom-formatter.md): Learn how to write a custom localization message formatter for your project
- [Dynamic Loading of Message Catalogs](https://lingui.dev/guides/dynamic-loading-catalogs.md): Learn how to set up dynamic loading of message catalogs in Lingui to reduce bundle size and improve performance
- [Explicit vs Generated IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md): Compare explicit and generated message IDs in Lingui i18n, understand the trade-offs, and choose the best approach for your localization workflow
- [Lazy Translations](https://lingui.dev/guides/lazy-translations.md): Lazy translations allow you to defer translation of a message until it is actually displayed
- [Message Extraction](https://lingui.dev/guides/message-extraction.md): Learn about message extraction in i18n and how to use Lingui to extract messages from your application
- [ICU MessageFormat](https://lingui.dev/guides/message-format.md): The ICU MessageFormat syntax Lingui uses for messages. Variables, plurals, select and ordinals explained with examples
- [Monorepo](https://lingui.dev/guides/monorepo.md): How to organize message catalogs, extraction and the shared runtime when Lingui is used across several apps and packages in a monorepo
- [Keeping Your Bundle Small: How Lingui Optimizes for Performance](https://lingui.dev/guides/optimizing-bundle-size.md): How Lingui keeps your bundle small by compiling messages to compact IDs and dropping the message compiler in production, and how to configure that behavior
- [Pluralization](https://lingui.dev/guides/plurals.md): Learn about pluralization and how to use it in your application with Lingui
- [Pseudolocalization](https://lingui.dev/guides/pseudolocalization.md): Learn how to use pseudolocalization to test the internationalization aspects of your application with Lingui
- [Testing](https://lingui.dev/guides/testing.md): How to test React components that use Trans or useLingui by wrapping them in I18nProvider with React Testing Library
- [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md): Write Lingui messages that give translators and AI the context they need - whole sentences, named placeholders and tags, comments, and context - and enforce it with ESLint
- [Typed Message IDs](https://lingui.dev/guides/typed-message-ids.md): Learn how to opt in to type-safe message IDs for autocomplete and compile-time validation

## API Reference

- [Catalog Formats](https://lingui.dev/ref/catalog-formats.md): Learn about the different catalog formats supported by Lingui
- [Lingui CLI](https://lingui.dev/ref/cli.md): Learn how to set up and use Lingui CLI to extract, check, merge and compile message catalogs
- [Configuration](https://lingui.dev/ref/conf.md): Learn how to configure Lingui for your project
- [Core API Reference](https://lingui.dev/ref/core.md): The package provides the main i18n object, which manages message catalogs, active locale, and message translation and formatting
- [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md): Lingui ESLint Plugin helps you find and prevent common i18n mistakes in your code
- [Vue.js Extractor](https://lingui.dev/ref/extractor-vue.md): Extract messages from Vue single-file components with @lingui/extractor-vue. Installation, configuration and options
- [Webpack-compatible loader](https://lingui.dev/ref/loader.md): Import PO catalogs directly and compile them on the fly with @lingui/loader in Webpack, Rspack and Rsbuild, instead of running lingui compile
- [Locale Detection](https://lingui.dev/ref/locale-detector.md): Detect the user's locale with the `@lingui/detect-locale` package
- [Macros](https://lingui.dev/ref/macro.md): Transform JavaScript objects and JSX elements into ICU MessageFormat messages
- [Metro Transformer](https://lingui.dev/ref/metro-transformer.md): Use Lingui with React Native and compile your message catalogs on the fly
- [React API Reference](https://lingui.dev/ref/react.md): Reference for the Lingui React API and components
- [Solid API Reference](https://lingui.dev/ref/solid.md): Reference for the Lingui SolidJS API and components
- [SWC Plugin](https://lingui.dev/ref/swc-plugin.md): Use Lingui Macros in your SWC project
- [Vite Plugin](https://lingui.dev/ref/vite-plugin.md): Use Lingui with Vite and compile your message catalogs on the fly

## Examples

- [Examples](https://lingui.dev/examples.md): Examples of using Lingui for internationalization (i18n) in various frameworks and libraries

## Sync & Collaboration Tools

- [Crowdin](https://lingui.dev/tools/crowdin.md): Translate a Lingui project with Crowdin. Sync PO catalogs with the Crowdin CLI or the GitHub, GitLab and Bitbucket integrations and deliver them over the air
- [Sync & Collaboration Tools](https://lingui.dev/tools/introduction.md): How to manage translations for a Lingui project. Manual catalog editing versus translation management systems, and the tools that integrate with Lingui
- [Translation.io](https://lingui.dev/tools/translation-io.md): Sync Lingui catalogs with Translation.io. Push source messages, pull translations, and give translators ICU syntax highlighting and plural management

## i18n with AI

- [i18n with AI](https://lingui.dev/ai-tools.md): Give AI coding agents accurate, up-to-date Lingui knowledge with Agent Skills, llms.txt context files, and the Context7 MCP server

## Comparisons

- [Lingui vs i18next](https://lingui.dev/misc/i18next.md): How Lingui compares with i18next and react-i18next. Message syntax, plurals, extraction tooling, catalog formats, bundle size and React Server Components
- [Lingui vs react-intl](https://lingui.dev/misc/react-intl.md): How Lingui compares with react-intl from FormatJS. Both use ICU MessageFormat, so the differences are in rich text, macros, extraction tooling and bundle size

## Optional
- [GitHub repository](https://github.com/lingui/js-lingui): Source code, issues and discussions
- [npm: @lingui/core](https://www.npmjs.com/package/@lingui/core): The runtime package; @lingui/react adds the React bindings and @lingui/cli the command line tool
- [Agent Skills](https://github.com/lingui/skills): Lingui best practices packaged as Agent Skills for coding agents
- [Context7](https://context7.com/lingui/js-lingui): The current documentation served over MCP


---

# Full Documentation Content

# i18n with AI

AI coding agents and chat tools have become an essential part of the development workflow, and internationalization is no exception. However, most AI models have limited or outdated knowledge of Lingui's APIs and best practices. This page covers the resources available to give your AI tools accurate, up-to-date Lingui knowledge so they can help you ship localized products faster.

## Agent Skills[​](#agent-skills "Direct link to Agent Skills")

[Lingui Agent Skills](https://github.com/lingui/skills) are reusable, procedural knowledge packages for AI coding agents. They provide best practices, common patterns, and troubleshooting guides that agents can follow when working with Lingui - reducing hallucinations and incorrect API usage.

### Installation[​](#installation "Direct link to Installation")

The skills follow the [Agent Skills format](https://agentskills.io) and work with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and other compatible agents. Use whichever installer matches your tool - each one installs the whole set.

**Skills CLI:**

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

**Claude Code plugin** - all skills load automatically and stay up to date via `/plugin marketplace update`:

```
/plugin marketplace add lingui/skills

/plugin install lingui@lingui-skills
```

**Plugins CLI** - auto-detects your installed agent tools and installs through each one's native plugin system:

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

**Gemini CLI extension:**

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

**GitHub CLI** (v2.90+) - installs for GitHub Copilot or any other supported agent. Use `--agent <name>` to target a specific tool, and `gh skill update` to pull newer versions:

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

To install a single skill instead of the full set, pass `--skill` to the Skills CLI:

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

See the [Lingui Skills](https://github.com/lingui/skills) repository for more details about the available skills and their usage.

## Context Files[​](#context-files "Direct link to Context Files")

Lingui follows the [llms.txt specification](https://llmstxt.org/) and publishes two files optimized for AI consumption: [`llms.txt`](https://lingui.dev/llms.txt), an index of the documentation pages with a short summary of each, and [`llms-full.txt`](https://lingui.dev/llms-full.txt), the full docs content in a single streamlined Markdown file. Both are regenerated with every docs build, and some AI tools auto-discover them if you provide `https://lingui.dev` as a docs source.

While these files are easy to parse, `llms-full.txt` is large and uses a lot of tokens when loaded directly into context, and a copy saved into your repository goes stale over time. They are best used as a fallback when the AI tool cannot access the latest documentation in other ways. The [Context7 MCP server](#context7-mcp) searches the same documentation on demand and returns only the relevant parts, making it the preferred option when available.

tip

Every documentation page is also available as plain Markdown: append `.md` to its URL, for example [`https://lingui.dev/ref/macro.md`](https://lingui.dev/ref/macro.md) for the Macros reference. A single page costs a fraction of the tokens of `llms-full.txt`, so when you know which part of the docs the agent needs, give it that URL instead. The links in `llms.txt` already point to these Markdown versions.

## Context7 MCP[​](#context7-mcp "Direct link to Context7 MCP")

[Context7](https://context7.com/lingui/js-lingui) is an MCP (Model Context Protocol) server that provides AI tools with real-time access to up-to-date library documentation - including Lingui. Unlike static context files, Context7 indexes the latest docs and lets agents search them on demand, keeping token usage low.

### Usage[​](#usage "Direct link to Usage")

Add `use context7` to any prompt and Context7-enabled agents will automatically pull relevant Lingui documentation:

```
Add i18n to my React app using Lingui. use context7
```

### MCP Server Configuration[​](#mcp-server-configuration "Direct link to MCP Server Configuration")

If your AI tool supports MCP server configuration, you can add Context7 directly:

```
{

  "mcpServers": {

    "context7": {

      "command": "npx",

      "args": ["-y", "@upstash/context7-mcp"]

    }

  }

}
```

For tool-specific setup instructions (including remote server and other clients), visit the [Context7 page for Lingui](https://context7.com/lingui/js-lingui).


---

# Examples

To help you get started with Lingui, we've provided some example projects that demonstrate how Lingui can be integrated into various frameworks and libraries. These projects demonstrate Lingui's versatility and show you how to use it in real-world scenarios.

Check out the example projects below:

* [Vanilla JS](https://github.com/lingui/js-lingui/tree/main/examples/js)
* [Next.js App Router with SWC](https://github.com/lingui/js-lingui/tree/main/examples/nextjs-swc)
* [Next.js Pages Router with Babel](https://github.com/lingui/js-lingui/tree/main/examples/nextjs-babel)
* [React Native (uses Expo)](https://github.com/lingui/js-lingui/tree/main/examples/react-native)
* [React with Vite and Babel](https://github.com/lingui/js-lingui/tree/main/examples/vite-project-react-babel)
* [React with Vite and SWC](https://github.com/lingui/js-lingui/tree/main/examples/vite-project-react-swc)
* [Solid with Vite](https://github.com/lingui/js-lingui/tree/main/examples/vite-project-solid)
* [Rspack with SWC](https://github.com/lingui/js-lingui/tree/main/examples/rspack)
* [Remix with Vite and Babel](https://github.com/lingui/js-lingui/tree/main/examples/remix-vite-babel)
* [Tanstack Start with Vite and Babel](https://github.com/lingui/js-lingui/tree/main/examples/tanstack-start)
* [React Webpack with gettext-style PO files](https://github.com/lingui/js-lingui/tree/main/examples/react-webpack-gettext)


---

# Custom Extractor

Lingui's default extractor is based on Babel and supports JavaScript (Stage 3), TypeScript, and Flow out of the box, covering most standard and modern syntax features. To extract without Babel, use the [native extractor](#native-extractor). If your project relies on experimental ECMAScript syntax or custom file formats, a custom extractor gives you the flexibility to handle these scenarios.

### Why It Doesn't Use Your Babel Config?[​](#why-it-doesnt-use-your-babel-config "Direct link to Why It Doesn't Use Your Babel Config?")

Babel plugins from your configuration define transformations, and some of these may interfere with or slow down the extraction process. The extractor doesn't have to transform your code, it just analyzes it. Therefore, it's designed to understand different syntax without worrying about how the code is transpiled or down-levelled.

info

We are constantly updating the extractor to keep up with the latest ECMAScript features. However, if you find that a recently added Stage 3 feature doesn't work as expected, please [create an issue](https://github.com/lingui/js-lingui/issues/new/choose).

## Native Extractor[​](#native-extractor "Direct link to Native Extractor")

[`@lingui/native-tools`](https://www.npmjs.com/package/@lingui/native-tools), the toolchain behind the [native macro transform](https://lingui.dev/ref/vite-plugin.md#native-macro-transform), also provides an SWC-based extractor for `lingui extract`. Use it to extract messages without Babel:

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/native-tools
```

```
pnpm add --save-dev @lingui/native-tools
```

lingui.config.ts

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

import { createSwcExtractor } from "@lingui/native-tools";



export default defineConfig({

  // [...]

  extractors: [createSwcExtractor()],

});
```

It handles `.js`, `.jsx`, `.ts`, `.tsx` files and their `.mjs`, `.cjs`, `.mts`, `.cts` variants. Macro options are read from your Lingui configuration.

Differences from the default extractor:

* [`extractorParserOptions`](https://lingui.dev/ref/conf.md#extractorparseroptions) doesn't apply. Pass SWC `parser` options instead, the same as [`jsc.parser`](https://swc.rs/docs/configuration/compilation#jscparser) in `.swcrc`. Syntax and JSX are inferred from the file name, Decorators are enabled by default.
* Flow is not supported.

note

`@lingui/cli` still depends on Babel for the default extractor and `lingui compile`, so Babel stays in your dependency tree until the next major release.

## Experimental ECMAScript Syntax[​](#experimental-ecmascript-syntax "Direct link to Experimental ECMAScript Syntax")

If you are using experimental features (Stage 0 - Stage 2), you'll need to configure a custom list of parser plugins. This can be done by overriding the default extractor and using the `extractFromFileWithBabel()` function:

lingui.config.ts

```
import { extractFromFileWithBabel, defineConfig } from "@lingui/cli/api";

import type { ParserPlugin } from "@babel/parser";



export function getBabelParserOptions(filename: string) {

  // https://babeljs.io/docs/en/babel-parser#latest-ecmascript-features

  const parserPlugins: ParserPlugin[] = ["importAttributes", "explicitResourceManagement"];



  if ([/\.ts$/, /\.mts$/, /\.cts$/, /\.tsx$/].some((r) => filename.match(r))) {

    parserPlugins.push("typescript");

  }



  if ([/\.js$/, /\.jsx$/, /\.tsx$/].some((r) => filename.match(r))) {

    parserPlugins.push("jsx");

  }



  return parserPlugins;

}



export default defineConfig({

  // [...]

  extractors: [

    {

      match(filename: string) {

        return filename.match(/\.[cm][tj]sx?$/);

      },

      async extract(filename, code, onMessageExtracted, ctx) {

        return extractFromFileWithBabel(filename, code, onMessageExtracted, ctx, {

          // https://babeljs.io/docs/babel-parser#plugins

          plugins: getBabelParserOptions(filename),

        });

      },

    },

  ],

});
```

## Other Frameworks or Custom Syntax[​](#other-frameworks-or-custom-syntax "Direct link to Other Frameworks or Custom Syntax")

If you're working with files that aren't valid JavaScript, you can create a custom extractor to handle them:

./my-custom-extractor.ts

```
import { extractor as defaultExtractor } from "@lingui/cli/api";



export const extractor: ExtractorType = {

  match(filename: string) {

    return filename.endsWith(".custom");

  },

  extract(filename: string, code: string, onMessageExtracted, ctx: ExtractorCtx) {

    // Transform the file to plain JS + Sourcemaps

    const { code: transformedCode, sourcemaps } = transformMyCustomFileToJs(filename, code);



    // Access Lingui config via `ctx.linguiConfig`

    // Reuse the default CLI extractor

    return defaultExtractor.extract(filename, transformedCode, onMessageExtracted, {

      sourcemaps,

      ...ctx,

    });

  },

};
```

### Adding the Custom Extractor to the Configuration[​](#adding-the-custom-extractor-to-the-configuration "Direct link to Adding the Custom Extractor to the Configuration")

To use the custom extractor, you need to add it to your Lingui configuration file:

lingui.config.ts

```
import { extractor } from "./my-custom-extractor.ts";

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



export default defineConfig({

  // [...]

  extractors: [extractor],

});
```

Important

If you are using TypeScript to create your extractor, you should use the `.ts` extension for your Lingui configuration file.


---

# Custom Formatter

If your project requires a message catalog format that Lingui doesn't [natively support](https://lingui.dev/ref/catalog-formats.md), you can create a custom formatter to handle it. A custom formatter allows you to define how extracted strings are formatted into a custom catalog format, providing flexibility for specialized workflows and integration with unique file structures.

## Overview[​](#overview "Direct link to Overview")

A formatter is an object with two main functions, `parse` and `serialize`, which define how catalogs are read from and written to your custom format.

The formatter can be configured directly in your `lingui.config.{ts,js}` file - no separate package is needed:

lingui.config.{ts,js}

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

import { extractor } from "./my-custom-extractor.ts";



export default defineConfig({

  // [...]

  format: {

    catalogExtension: "json",

    parse: (content: string): CatalogType => JSON.parse(content),

    serialize: (catalog: CatalogType): string => JSON.stringify(catalog),

  },

});
```

## Reference[​](#reference "Direct link to Reference")

The shape of formatter is the following:

```
export type CatalogFormatter = {

  catalogExtension: string;

  /**

   * Set extension used when extract to template

   * Omit if the extension is the same as catalogExtension

   */

  templateExtension?: string;

  parse(

    content: string,

    ctx: { locale: string | null; sourceLocale: string; filename: string }

  ): Promise<CatalogType> | CatalogType;

  serialize(

    catalog: CatalogType,

    ctx: { locale: string | null; sourceLocale: string; filename: string; existing: string | null }

  ): Promise<string> | string;

};
```

Lingui Catalog is an object with the following structure:

```
export type CatalogType = {

  [msgId: string]: MessageType;

};



type CatalogExtra = Record<string, unknown>;



export type MessageType<Extra = CatalogExtra> = {

  message?: string;

  origin?: MessageOrigin[];

  comments?: string[];

  obsolete?: boolean;

  context?: string;

  translation?: string;



  /**

   * the generic field where

   * formatters can store additional data

   */

  extra?: Extra;

};
```

Important

If you are using TypeScript to create your formatter, you should use the `.ts` extension for your Lingui configuration file.


---

# Dynamic Loading of Message Catalogs

Internationalization in modern applications requires careful handling of localized messages to avoid bloating the initial bundle size. By default, Lingui makes it easy to load all strings for a single active locale. For even greater efficiency, developers can selectively load only the messages needed on demand using [`i18n.load`](https://lingui.dev/ref/core.md#i18n.load), ensuring minimal resource usage.

The [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider) component doesn't make assumptions about your app's structure, giving you the freedom to load only the necessary messages for the currently selected language.

This guide shows how to set up dynamic loading of message catalogs, ensuring only the needed catalogs are loaded, which reduces bundle size and improves performance.

## Final i18n Loader Helper[​](#final-i18n-loader-helper "Direct link to Final i18n Loader Helper")

The following code defines the complete logic for dynamically loading and activating message catalogs based on the selected locale. It ensures that only the required catalog is loaded at runtime, optimizing performance:

i18n.ts

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



export const locales = {

  en: "English",

  cs: "Česky",

};

export const defaultLocale = "en";



/**

 * We do a dynamic import of just the catalog that we need

 * @param locale any locale string

 */

export async function dynamicActivate(locale: string) {

  const { messages } = await import(`./locales/${locale}/messages`);

  i18n.load(locale, messages);

  i18n.activate(locale);

}
```

Important

Even the "default" locale requires a catalog to be loaded. Lingui aims to keep the internationalization footprint to a minimum by dropping default messages from the production build. This way, only the catalog for the active language is loaded, avoiding duplication.

Without this optimization, switching from the default language (e.g. EN) to another (e.g. FR) would require loading both language catalogs. This strategy ensures efficiency by loading only the necessary messages for one language at a time.

### Usage in Your Application[​](#usage-in-your-application "Direct link to Usage in Your Application")

To use the `dynamicActivate` function in your application, you must call it on application startup. The following example shows how to use it in a React application:

```
import React, { useEffect } from "react";

import App from "./App";



import { I18nProvider } from "@lingui/react";

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

import { defaultLocale, dynamicActivate } from "./i18n";



const I18nApp = () => {

  useEffect(() => {

    // With this method we dynamically load the catalogs

    dynamicActivate(defaultLocale);

  }, []);



  return (

    <I18nProvider i18n={i18n}>

      <App />

    </I18nProvider>

  );

};
```

### Optimized Bundle Structure[​](#optimized-bundle-structure "Direct link to Optimized Bundle Structure")

Looking at the contents of the build directory, we find a separate chunk for each language:

```
i18n-0.c433b3bd.chunk.js

i18n-1.f0cf2e3d.chunk.js

main.ab4626ef.js
```

When the page is first loaded, only the main bundle and the bundle for the first language are loaded:

![Requests during the first render](/assets/images/dynamic-loading-catalogs-1-142e71bb089432f649766b3077d504c3.png)

After changing the language in the UI, the second language bundle is loaded:

![Requests during the second render](/assets/images/dynamic-loading-catalogs-2-eade7ea8527b393f9da2a5053a493aa3.png)

## Dependency Tree Extractor (experimental)[​](#dependency-tree-extractor-experimental "Direct link to Dependency Tree Extractor (experimental)")

The Dependency Tree Extractor is an experimental feature designed to improve message extraction by analyzing the dependency tree of your application. This tool improves the efficiency of loading localized messages by identifying only the necessary messages for each component or page, rather than extracting all messages into a single catalog.

This allows for a more granular extraction process, resulting in smaller and more relevant message catalogs.

For detailed guidance on message extraction, refer to the [Message Extraction](https://lingui.dev/guides/message-extraction.md) guide.


---

# Explicit vs Generated IDs

When internationalizing your application, you may need to decide whether to use explicit or generated IDs for your messages.

In this guide, we explore the basic concepts of explicit and generated IDs, and then delve into a comprehensive comparison, highlighting the advantages and disadvantages of each approach.

## Differences Between Explicit and Generated IDs[​](#differences-between-explicit-and-generated-ids "Direct link to Differences Between Explicit and Generated IDs")

### Explicit ID[​](#explicit-id "Direct link to Explicit ID")

An explicit ID, often referred to as a user-defined or custom ID, is a manually assigned identifier associated with a specific message. These IDs are typically chosen by developers and are explicitly specified within your code. The typical explicit ID may look like `index.header.title` or `modal.buttons.cancel`.

Example:

```
<Trans id="index.header.title">Lingui example</Trans>



// extracted as

{

  id: "index.header.title",

  message: "Lingui example",

}
```

### Generated IDs[​](#generated-ids "Direct link to Generated IDs")

On the other hand, generated IDs are created automatically by the internationalization library. In Lingui, such IDs are created based on the source message and [context](#context).

Example:

```
<Trans>Lingui example</Trans>



// extracted as

{

  id: "MbT6FE",

  message: "Lingui example",

}
```

### Benefits of Generated IDs[​](#benefits-of-generated-ids "Direct link to Benefits of Generated IDs")

* **Avoiding the "naming things" problem:** you don't need to come up with a name for each single phrase in the app. Lingui generates the IDs (in the form of short hashes) from the messages.
* **Better developer experience:** developers can focus on coding without needing to manually assign IDs, leading to a more streamlined development process. Searching for a user-facing string will lead to the place in code where it's used, as opposed to taking you to a (typically JSON) file full of translations.
* **Avoiding duplicates:** duplicate messages are merged together automatically. Translators will not have to translate the same phrases again and again. This could lead to cost savings, especially if translators charge by word count.
* **Smaller bundle:** Lingui generates short IDs such as `MbT6FE` which are typically shorter than manually crafted IDs like `index.header.title`. This results in a smaller bundle size, optimizing your application's performance.
* **Preventing ID collisions:** as your application scales, explicit IDs can potentially lead to conflicts. Lingui's generated IDs help avoid such collisions.
* **Readability is a non-issue:** even though generated IDs aren't human-readable, you would hardly see them. Translators work with the source string in the catalog, while the IDs remain behind the scenes.

### Benefits of Explicit IDs[​](#benefits-of-explicit-ids "Direct link to Benefits of Explicit IDs")

* **Control:** developers have full control over the naming and assignment of explicit IDs. This control allows for precise targeting and easy maintenance of internationalization keys.
* **Loose coupling:** explicit IDs are loosely coupled with the messages (as opposed to when they are generated from the messages). This means that if the message changes, the ID remains the same. When your team uses a TMS (Translation Management System), this makes it easier even for non-technical people to update the strings.
* **Readability:** explicit IDs often have meaningful names, making it easier for developers, translators, and content creators to understand their purpose within the codebase.
* **Predictability:** since explicit IDs are manually assigned, they remain stable across different versions of your application, reducing the likelihood of breaking changes during updates.

tip

If you use explicit IDs, you can opt in to [Typed Message IDs](https://lingui.dev/guides/typed-message-ids.md) for autocomplete and compile-time validation of your message identifiers.

The choice between these two strategies depends on your project requirements and priorities. However, it's important to note that Lingui provides the full range of benefits, especially with generated IDs.

## Context[​](#context "Direct link to Context")

By default, when using generated IDs, the same text elements are extracted with the same ID, and then translated once. However, this might not always be desirable since the same text can have different meanings and translations. For example, consider the word "right" and its two possible meanings:

* correct as in "you are right"
* direction as in "turn right"

To distinguish these two cases, you can add `context` to messages. The same text elements with different contexts are extracted with different IDs. Then, they can be translated differently and merged back into the application as different translation entries.

Regardless of whether you use generated IDs or not, adding context makes the translation process less challenging and helps translators interpret the source accurately. You, in return, get translations of better quality faster and decrease the number of context-related issues you would need to solve. See [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md) for the other ways to give translators context.

Examples:

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



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

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



// ↓ ↓ ↓ ↓ ↓ ↓



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



<Trans id={"d1wX4r"} message="right" />;

<Trans id={"16eaSK"} message="right" />;
```

or with non-JSX macro:

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



const ex1 = msg({

  message: `right`,

  context: "direction",

});



const ex2 = msg({

  message: `right`,

  context: "correctness",

});



// ↓ ↓ ↓ ↓ ↓ ↓



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



const ex1 = {

  id: "d1wX4r",

  message: `right`,

};

const ex2 = {

  id: "16eaSK",

  message: `right`,

};
```

## Using Generated IDs[​](#using-generated-ids "Direct link to Using Generated IDs")

### With JSX Macro[​](#with-jsx-macro "Direct link to With JSX Macro")

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



function render() {

  return (

    <>

      <h1>

        <Trans>Lingui example</Trans>

      </h1>

      <p>

        <Trans>

          Hello <a href="/profile">{name}</a>.

        </Trans>

      </p>

    </>

  );

}
```

In the example code above, the content of [`Trans`](https://lingui.dev/ref/macro.md#trans) is transformed into a message in MessageFormat syntax. By default, this message is used for generating the ID. Considering the example above, the catalog would contain these entries:

```
const catalog = [

  {

    id: "MbT6FE",

    message: "Lingui example",

  },

  {

    id: "9_omjw",

    message: "Hello <0>{name}</0>.",

  },

];
```

### With Core Macro[​](#with-core-macro "Direct link to With Core Macro")

In the following example, the message `Hello World` will be extracted and used to create an ID:

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



msg`Hello World`;
```

tip

Enforce generated IDs with the Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) rule [`require-implicit-id`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/require-implicit-id.md).

## Using Explicit IDs[​](#using-explicit-ids "Direct link to Using Explicit IDs")

### With JSX Macro[​](#with-jsx-macro-1 "Direct link to With JSX Macro")

To use custom IDs in JSX macros, pass the ID as a prop to the component:

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



function render() {

  return (

    <>

      <h1>

        <Trans id="msg.header">Lingui example</Trans>

      </h1>

      <p>

        <Trans id="msg.hello">

          Hello <a href="/profile">{name}</a>.

        </Trans>

      </p>

    </>

  );

}
```

The messages with IDs `msg.header` and `msg.hello` will be extracted with their default values as `Lingui example` and `Hello <0>{name}</0>.` respectively.

### With Core Macro[​](#with-core-macro-1 "Direct link to With Core Macro")

To use custom IDs in non-JSX macros, call the [`msg`](https://lingui.dev/ref/macro.md#definemessage) function with a message descriptor object, passing the ID using the `id` property:

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



msg({ id: "msg.greeting", message: `Hello World` });
```

Message `msg.greeting` will be extracted with default value `Hello World`.

For all other js macros ([`plural`](https://lingui.dev/ref/macro.md#plural), [`select`](https://lingui.dev/ref/macro.md#select), [`selectOrdinal`](https://lingui.dev/ref/macro.md#selectordinal), use them inside [`msg`](https://lingui.dev/ref/macro.md#definemessage) macro to pass ID (in this case, `'msg.caption'`).

```
import { msg, plural } from "@lingui/core/macro";



msg({

  id: "msg.caption",

  message: plural(count, {

    one: "# image caption",

    other: "# image captions",

  }),

});
```

tip

Enforce explicit IDs with the Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) rule [`require-explicit-id`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/require-explicit-id.md).

## See Also[​](#see-also "Direct link to See Also")

* [Message Extraction](https://lingui.dev/guides/message-extraction.md)
* [Macros Reference](https://lingui.dev/ref/macro.md)


---

# Lazy Translations

Lazy translation allows you to defer translation of a message until it's rendered, giving you flexibility in how and where you define messages in your code. With lazy translation, you can tag a string with the [`msg`](https://lingui.dev/ref/macro.md#definemessage) macro to create a *message descriptor* that can be saved, passed around as a variable, and rendered later.

## Usage Example[​](#usage-example "Direct link to Usage Example")

To render the message descriptor as a string-only translation, pass it to the [`i18n.t()`](https://lingui.dev/ref/core.md#i18n.t) method:

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

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



const favoriteColors = [msg`Red`, msg`Orange`, msg`Yellow`, msg`Green`];



export function getTranslatedColorNames() {

  return favoriteColors.map((color) => i18n.t(color));

}
```

## Usage in React[​](#usage-in-react "Direct link to Usage in React")

To render the message descriptor in a React component, pass its `id` to the [`Trans`](https://lingui.dev/ref/react.md#trans) component as a value of the `id` prop:

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

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



const favoriteColors = [msg`Red`, msg`Orange`, msg`Yellow`, msg`Green`];



export default function ColorList() {

  return (

    <ul>

      {favoriteColors.map((color) => (

        <li>

          <Trans id={color.id} />

        </li>

      ))}

    </ul>

  );

}
```

Important

Please note that we import the `<Trans>` component from `@lingui/react` to use the runtime version, as the message is already defined and we don't need the compile-time macro here.

### Picking a Message Based on a Variable[​](#picking-a-message-based-on-a-variable "Direct link to Picking a Message Based on a Variable")

Sometimes you need to choose between different messages to display depending on the value of a variable. For example, imagine you have a numeric "status" code that comes from an API, and you need to display a message that represents the current status.

An easy way to do this is to create an object that maps the possible values of "status" to message descriptors (tagged with the [`msg`](https://lingui.dev/ref/macro.md#definemessage) macro) and render them as needed with deferred translation:

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

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



const statusMessages = {

  ["STATUS_OPEN"]: msg`Open`,

  ["STATUS_CLOSED"]: msg`Closed`,

  ["STATUS_CANCELLED"]: msg`Cancelled`,

  ["STATUS_COMPLETED"]: msg`Completed`,

};



export default function StatusDisplay({ statusCode }) {

  const { _ } = useLingui();

  return <div>{_(statusMessages[statusCode])}</div>;

}
```

### Memoization Pitfall[​](#memoization-pitfall "Direct link to Memoization Pitfall")

In the following contrived example, we document how a welcome message will or will not be updated when locale changes. The documented behavior may not be intuitive at first, but it is expected, because of the way the `useMemo` dependencies work.

To avoid bugs with stale translations, use the `t` function returned from the [`useLingui`](https://lingui.dev/ref/macro.md#uselingui) macro: it is safe to use with memoization because its reference changes whenever the Lingui context updates.

Keep in mind that `useMemo` is primarily a performance optimization tool in React. Because of this, there might be no need to memoize your translations. Additionally, this issue is not present when using the `Trans` component, which we recommend using whenever possible.

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

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

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



const welcomeMessage = msg`Welcome!`;



// ❌ Bad! This code won't work

export function Welcome() {

  const buggyWelcome = useMemo(() => {

    return i18n.t(welcomeMessage);

  }, []);



  return <div>{buggyWelcome}</div>;

}



// ❌ Bad! This code won't work either because the reference to i18n does not change

export function Welcome() {

  const { i18n } = useLingui();



  const buggyWelcome = useMemo(() => {

    return i18n.t(welcomeMessage);

  }, [i18n]);



  return <div>{buggyWelcome}</div>;

}



// ✅ Good! `useMemo` consumes the `t` function from the `useLingui` macro

export function Welcome() {

  const { t } = useLingui();



  const welcome = useMemo(() => {

    return t(welcomeMessage);

  }, [t]);



  return <div>{welcome}</div>;

}
```


---

# Message Extraction

Message extraction is a key part of the internationalization process. It involves scanning your codebase to identify and extract all the defined messages, ensuring that your message catalogs stay synchronized with the source code.

In practice, developers define messages directly in the source code, and the extraction tool automatically collects these messages and stores them in a message catalog for translation.

Read more about the [`lingui extract`](https://lingui.dev/ref/cli.md#extract) command.

## Supported Patterns[​](#supported-patterns "Direct link to Supported Patterns")

The extractor operates at a static level, meaning that it analyzes the source code without executing it. As a result, it doesn't support complex patterns or dynamic code, and only simple, statically defined messages are collected.

### Macros Usage[​](#macros-usage "Direct link to Macros Usage")

> Macros are JavaScript transformers that run at build time. The value returned by a macro is inlined into the bundle instead of the original function call.

The Lingui Macro provides powerful macros to transform JavaScript objects and JSX elements into [ICU MessageFormat](https://lingui.dev/guides/message-format.md) messages at compile time.

Extractor supports all macro usage, such as the following examples:

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

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



t`Message`;



t({

  id: "custom.id",

  message: "Message with custom ID",

});



const jsx = <Trans>Hi, my name is {name}</Trans>;
```

The extractor matches the `t` and `Trans` macro calls and extracts the messages from them.

For more usage examples, see to the [Macros](https://lingui.dev/ref/macro.md) reference.

### Non-Macros Usage[​](#non-macros-usage "Direct link to Non-Macros Usage")

Non-macro use is also supported, but it's not common. It's recommended to use macros.

The extractor matches `i18n._` or `i18n.t` function calls. It also matches when these functions are called from other member expressions, such as `ctx.i18n.t()`.

caution

The extractor only matches calls by name. It doesn't check if they are really imported from Lingui packages.

For example:

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

To ignore a specific call expression during extraction, you can add a `lingui-extract-ignore` comment:

```
/* lingui-extract-ignore */

ctx.i18n.t("Message");
```

Messages marked with this comment will be excluded from extraction.

### `lingui-set` Comment Directive[​](#lingui-set-comment-directive "Direct link to lingui-set-comment-directive")

You can use the `lingui-set` comment directive to set `context` and/or `comment` for subsequent macro calls without passing them to every call:

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



// lingui-set context="settings" comment="Settings page"

const msg1 = t`Save`;

const msg2 = t`Cancel`;
```

Both messages will be extracted with `context="settings"` and `comment="Settings page"`. The directive values persist for all subsequent macros until overridden by another directive or cleared with `lingui-reset`.

See [`lingui-set` Comment Directive](https://lingui.dev/ref/macro.md#lingui-directive) in the Macros reference for full details and examples, and [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md#set-context-once-per-file) for when to use directives.

### Explicitly Marking Messages[​](#explicitly-marking-messages "Direct link to Explicitly Marking Messages")

In addition to call expressions, which are the most commonly used method, the extractor tool also supports simple string literals and message descriptors with explicit annotations.

To do this, simply prefix your expression with the `/** i18n */` or ( `/* i18n */`, both variants are supported) comment, like so:

```
const messageDescriptor: MessageDescriptor = /** i18n */ { id: "Description", comment: "description" };

const stringLiteral = /** i18n */ "Message";
```

## Unsupported Patterns[​](#unsupported-patterns "Direct link to Unsupported Patterns")

The extractor is limited to extracting messages from code that is written a certain way. It cannot extract messages from variables or function calls. It also cannot follow the program structure and get the value of a variable defined elsewhere.

This means that in order for a message to be extracted, it must be defined directly in the function call:

```
// ❌ This message will not be extracted

const message = "Message";

i18n.t(message);



// ✅ This message will be extracted

i18n.t("Message");
```

## Defining Sources for Analyzing[​](#defining-sources-for-analyzing "Direct link to Defining Sources for Analyzing")

The extractor can locate source files in two ways: by specifying a glob pattern or by crawling the dependency tree.

### Glob Pattern[​](#glob-pattern "Direct link to Glob Pattern")

By default, `lingui extract` uses a glob pattern to search for source files containing messages.

The pattern is defined in the [`catalogs`](https://lingui.dev/ref/conf.md#catalogs) property of the Lingui configuration file in your project's root directory.

![Scheme of discovering by glob pattern](/assets/images/extractor-glob-scheme-450bc42bb7a09c538a20e45badbf087f.svg)

### Dependency Tree Crawling[​](#dependency-tree-crawling "Direct link to Dependency Tree Crawling")

While the glob-based extraction process works well for most projects, it can be challenging for multi-page applications (MPAs) such as Next.js. In such cases, the glob approach generates a single catalog that includes all messages from each page, which may not be ideal for effectively managing translations.

This means that the entire catalog must be loaded for each page or navigation, resulting in unnecessary loading of messages that aren't utilized on that specific page.

To address this issue, an `experimental-extractor` has been introduced in Lingui v4.

Experimental

This is an experimental feature. Experimental features are not covered by semver and may be subject to change.

This extractor uses the dependency tree of files, rather than just a glob pattern, to crawl imports and discover files more accurately.

By doing so, it creates a more optimized catalog that only contains the messages needed for each page.

The catalogs would still contain duplicate messages for common components, but it would be much better than the current approach.

![Scheme of discovering by dependencies](/assets/images/extractor-deps-scheme-a1918925811db3a4184d2a616a262e8f.svg)

To start using `experimental-extractor`, add the following section to your Lingui configuration:

```
/**

 *

 * @type {import('@lingui/conf').LinguiConfig}

 */

module.exports = {

  // remove everethying from `catalogs` property

  catalogs: [],

  experimental: {

    extractor: {

      // glob pattern of entrypoints

      // this will find all nextjs pages

      entries: ["<rootDir>/src/pages/**/*.tsx"],

      // output pattern, this instruct extractor where to store catalogs

      // src/pages/faq.tsx -> src/pages/locales/faq/en.po

      output: "<rootDir>/{entryDir}/locales/{entryName}/{locale}",

    },

  },

};
```

Then run the following command in your terminal:

```
lingui extract-experimental
```

#### Configuring the Bundler[​](#configuring-the-bundler "Direct link to Configuring the Bundler")

The experimental extractor uses a bundler under the hood to resolve dependencies and apply tree-shaking. By default, it uses [esbuild](https://esbuild.github.io/), but you can configure it to use [rolldown](https://rolldown.rs/) or implement your own bundler integration.

##### Rolldown[​](#rolldown "Direct link to Rolldown")

If your project uses Vite-based tooling, rolldown is the recommended choice. Vite is powered by rolldown (or rollup), so the extraction results will more closely match what Vite produces in your actual builds. You can even reuse parts of your Vite configuration.

Rolldown also has more powerful tree-shaking capabilities, which results in smaller and more accurate catalogs compared to esbuild. By default, the rolldown bundler uses the standard tree-shaking preset, but you can experiment with the `smallest` preset for even more aggressive dead code elimination. Since the bundler is only used for message extraction (not producing runtime code), the typical side-effect concerns around aggressive tree-shaking don't apply in most cases.

* npm
* Yarn
* pnpm

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

```
yarn add --dev rolldown
```

```
pnpm add --save-dev rolldown
```

lingui.config.ts

```
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(),

    },

  },

});
```

If your project uses path aliases (e.g. `@/` mapped in `tsconfig.json`), you need to include the alias prefix in `includeDeps` and enable `tsconfig` resolution. This is necessary because the extractor's external-module filter runs before rolldown resolves tsconfig path mappings:

lingui.config.ts

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



createRolldownBundler({

  includeDeps: ["@/"],

  resolveRolldownOptions: (options) => ({

    ...options,

    tsconfig: true,

  }),

});
```

To use the `smallest` tree-shaking preset:

lingui.config.ts

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



createRolldownBundler({

  resolveRolldownOptions: (options) => ({

    ...options,

    treeshake: "smallest",

  }),

});
```

##### esbuild[​](#esbuild "Direct link to esbuild")

esbuild is the default bundler and doesn't require any additional configuration. You can also configure it explicitly if you need to customize its behavior:

* npm
* Yarn
* pnpm

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

```
yarn add --dev esbuild
```

```
pnpm add --save-dev esbuild
```

lingui.config.ts

```
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"],

      }),

    },

  },

});
```

##### Custom Bundler[​](#custom-bundler "Direct link to Custom Bundler")

You can implement your own bundler by conforming to the `ExperimentalExtractorBundler` interface:

caution

Your bundler implementation must:

* Apply the Lingui macro transform to each file **during** bundling, not after. The macro transform is designed to work on authored source code — once files are bundled together, the transform will not work correctly.
* Produce **inline sourcemaps** in the output files. The extractor uses sourcemaps to map messages back to their original file and line number — without them, catalog origins (`#:` references) will point to the bundled output instead of the source.

See the built-in esbuild and rolldown bundlers for reference on how to integrate the transform as a bundler plugin.

lingui.config.ts

```
import { defineConfig } from "@lingui/conf";

import type { ExperimentalExtractorBundler, BundleChunk } from "@lingui/conf";



const myBundler: ExperimentalExtractorBundler = {

  async bundle(entryPoints, outDir, linguiConfig) {

    // Your bundling logic here.

    // Must apply the Lingui macro transform (e.g. `transform` from @lingui/native-tools,

    // @lingui/babel-plugin-lingui-macro or @lingui/swc-plugin) during the transform phase.



    // Return a chunk graph — the CLI traverses it to determine

    // which entry points depend on each shared chunk.

    const chunks: BundleChunk[] = [

      {

        id: "about.page.jsx",

        filePath: `${outDir}/about.page.jsx`,

        entryPoint: "/abs/path/to/src/pages/about.page.tsx",

        imports: ["shared-chunk.jsx"],

      },

      {

        id: "shared-chunk.jsx",

        filePath: `${outDir}/shared-chunk.jsx`,

        // no entryPoint — this is a shared chunk

        imports: [],

      },

    ];



    return { chunks };

  },

};



export default defineConfig({

  experimental: {

    extractor: {

      entries: ["<rootDir>/src/pages/**/*.tsx"],

      output: "<rootDir>/{entryDir}/locales/{entryName}/{locale}",

      bundler: myBundler,

    },

  },

});
```

##### Bundler Options Reference[​](#bundler-options-reference "Direct link to Bundler Options Reference")

Both `createEsbuildBundler` and `createRolldownBundler` accept the following common options:

| Option              | Description                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `includeDeps`       | Package names to bundle instead of marking as external. Use this for internal packages that contain messages            |
| `excludeExtensions` | File extensions to externalize (e.g., `css`, `svg`). Has sensible defaults                                              |
| `macroTransform`    | Options for the native macro transform applied during bundling. See [Macro Transform Options](#macro-transform-options) |

Additionally, each bundler accepts a resolver function for full control over bundler-specific options:

* `createEsbuildBundler({ resolveEsbuildOptions: (opts) => opts })`
* `createRolldownBundler({ resolveRolldownOptions: (opts) => opts })`

##### Macro Transform Options[​](#macro-transform-options "Direct link to Macro Transform Options")

Both built-in bundlers transform Lingui macros natively with [`@lingui/native-tools`](https://www.npmjs.com/package/@lingui/native-tools) while bundling. Macro options are read from your Lingui configuration, so in most cases nothing needs to be configured. Use `macroTransform` when you need to override them:

lingui.config.ts

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



createRolldownBundler({

  macroTransform: {

    macro: {

      jsxPlaceholderAttribute: "_t",

    },

    parser: {

      syntax: "typescript",

      decorators: true,

    },

  },

});
```

* `macro` - overrides for the macro options derived from your Lingui configuration, such as `corePackage`, `jsxPackage`, `jsxPlaceholderAttribute`, `jsxPlaceholderDefaults`, `runtimeModules` or `idPrefixLeader`. The `descriptorFields` option is always `"all"` during extraction and cannot be overridden.
* `parser` - SWC parser options, the same as [`jsc.parser`](https://swc.rs/docs/configuration/compilation#jscparser) in `.swcrc`. The actual syntax (ECMAScript or TypeScript) and JSX support are inferred from the file name, Decorators are enabled by default. A custom `parser` replaces the defaults, so set `decorators: true` yourself if you need them.

`createEsbuildBundler` accepts the same `macroTransform` option with the same meaning.

#### Important Notes[​](#important-notes "Direct link to Important Notes")

It's worth noting that the accuracy of the catalog depends heavily on tree-shaking, a technique used by modern bundlers to remove unused code from the final bundle.

If the code passed to the extractor is written in a tree-shakeable way, the user will get highly accurate catalogs.

While you may think that your code is tree-shakeable, in practice tree-shaking may work differently than you expect, and some unwanted strings may be included in the catalogs.

To illustrate, let's consider the following code:

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



export const species = {

  Cardano: [

    {

      startsAt: 0,

      name: msg`Ghost`,

      icon: "Ghost",

    },

    {

      startsAt: 0.000001,

      name: msg`Plankton`,

      icon: "Plankton",

    },

  ],

};
```

On the surface, it may appear that this code can be safely removed from the final bundle if it isn't used. However, the `msg` function call may have a side effect that prevents the bundler from removing the entire `species` object from the final bundle. As a result, messages defined in this snippet may be included in more catalogs than expected.

tip

To avoid this issue, one solution is to wrap the `species` object inside an *Immediately Invoked Function Expression* (IIFE) and add the `/* @__PURE__ */` annotation.

By adding this annotation to the IIFE, we tell the bundler that the entire `species` object can be safely removed if it is not used or exported elsewhere in the code.

## Supported Source Types[​](#supported-source-types "Direct link to Supported Source Types")

The extractor supports TypeScript, Flow, and JavaScript (Stage 3) out of the box.

If you are using some experimental features (Stage 0 - Stage 2) or frameworks with custom syntax such as Vue.js or Svelte, you may want to implement your own custom extractor.

Visit [Custom Extractor](https://lingui.dev/guides/custom-extractor.md) to learn how to create a custom extractor.

## See Also[​](#see-also "Direct link to See Also")

* [Lingui CLI Reference](https://lingui.dev/ref/cli.md)
* [Macros Reference](https://lingui.dev/ref/macro.md)
* [Catalog Formats](https://lingui.dev/ref/catalog-formats.md)


---

# ICU MessageFormat

ICU MessageFormat is a flexible and powerful syntax designed to express the grammatical nuances of different languages. Its flexibility ensures that your application can handle grammatical variations, making it essential for effective internationalization.

## Overview[​](#overview "Direct link to Overview")

### Simple text[​](#simple-text "Direct link to Simple text")

Example: `Refresh inbox`

### Variables[​](#variables "Direct link to Variables")

Example: `Attachment {name} saved`

### Plurals[​](#plurals "Direct link to Plurals")

> Using language specific plural forms (`one`, `other`):

```
{count, plural, one {Message} other {Messages}}
```

> Using exact matches for specific counts (`=0`):

```
{count, plural, =0 {No messages}

                one {# message}

                other {# messages}}
```

> Offsetting plural forms:

```
{count, plural, offset:1

                =0 {Nobody read this message}

                =1 {Only you read this message}

                one {You and # friend read this message}

                other {You and # friends read this message}
```

### Select[​](#select "Direct link to Select")

```
{gender, select, male {He replied to your message}

                 female {She replied to your message}

                 other {They replied to your message}}
```

### Ordinals[​](#ordinals "Direct link to Ordinals")

```
{count, selectOrdinal, one {#st message}

                       two {#nd message}

                       few {#rd message}

                       other {#th message}}
```

## See Also[​](#see-also "Direct link to See Also")

* [Pluralization](https://lingui.dev/guides/plurals.md)
* [ICU Playground](https://format-message.github.io/icu-message-format-for-translators/editor.html)


---

# Monorepo

Lingui has no monorepo-specific mode. Everything on this page is regular configuration; what changes in a monorepo is where you put it. You need to decide three things:

1. Where the catalogs live: one catalog per app, or one per package.
2. Where extraction runs: which `lingui.config` scans which sources.
3. How the runtime is shared: one `I18nProvider` and one copy of `@lingui/react`.

The examples use the layout below. It works the same with pnpm, Yarn or npm workspaces, with or without Turborepo or Nx on top.

```
.

├── apps/

│   ├── web/

│   └── admin/

└── packages/

    └── ui/     # shared components that render <Trans>
```

## Choose a Strategy[​](#choose-a-strategy "Direct link to Choose a Strategy")

| Your setup                                                                           | Strategy                                                                   |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Internal (unpublished) packages, one or a few apps                                   | [One catalog per app](#one-catalog-per-app). Start here                    |
| Several apps share many strings that should be translated once                       | [Catalog per package, merged per app](#catalog-per-package-merged-per-app) |
| Shared packages, and each app catalog should contain only what the app actually uses | [Dependency-based extraction](#dependency-based-extraction), experimental  |
| Packages published to npm and used outside the monorepo                              | [Published packages](#published-packages)                                  |

## One Catalog per App[​](#one-catalog-per-app "Direct link to One Catalog per App")

Each app owns a `lingui.config.ts`, its catalogs and the `extract` and `compile` scripts. Shared packages have no Lingui config. The app includes their source directories, so their messages land in the catalog of every app that uses them:

apps/web/lingui.config.ts

```
import { defineConfig } from "@lingui/conf";



export default defineConfig({

  sourceLocale: "en",

  locales: ["en", "cs"],

  catalogs: [

    {

      path: "<rootDir>/src/locales/{locale}",

      include: ["<rootDir>/src", "<rootDir>/../../packages/ui/src"],

    },

  ],

});
```

Run [`lingui extract`](https://lingui.dev/ref/cli.md#extract) and [`lingui compile`](https://lingui.dev/ref/cli.md#compile) from `apps/web` through the app's `package.json` scripts:

apps/web/package.json

```
{

  "scripts": {

    "extract": "lingui extract",

    "compile": "lingui compile"

  }

}
```

Scripts run with the package as the working directory, so the CLI finds the app's config. From another directory, pass `--config apps/web/lingui.config.ts`. Every catalog contains exactly what its app renders. Any bundler plugin works unchanged.

The trade-off is that a string from `packages/ui` is translated once per app. A translation management system with translation memory removes most of that cost.

Derive the include list from workspace dependencies

Instead of listing packages by hand, read them from the app's `package.json`. The catalog then follows the dependency graph automatically:

apps/web/lingui.config.ts

```
import { readFileSync } from "node:fs";

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



const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));



const workspacePackages = Object.keys(pkg.dependencies ?? {})

  .filter((name) => name.startsWith("@acme/"))

  .map((name) => `<rootDir>/../../packages/${name.split("/")[1]}/src`);



export default defineConfig({

  sourceLocale: "en",

  locales: ["en", "cs"],

  catalogs: [

    {

      path: "<rootDir>/src/locales/{locale}",

      include: ["<rootDir>/src", ...workspacePackages],

    },

  ],

});
```

## Catalog per Package, Merged per App[​](#catalog-per-package-merged-per-app "Direct link to Catalog per Package, Merged per App")

Every package with messages gets its own catalog, kept next to its sources and translated once. Each app lists its own catalog and those of the packages it uses, and merges them at compile time with [`catalogsMergePath`](https://lingui.dev/ref/conf.md#catalogsmergepath):

apps/admin/lingui.config.ts

```
import { defineConfig } from "@lingui/conf";



export default defineConfig({

  sourceLocale: "en",

  locales: ["en", "cs"],

  catalogs: [

    {

      path: "<rootDir>/locales/{locale}",

      include: ["<rootDir>/src"],

    },

    {

      path: "<rootDir>/../../packages/ui/locales/{locale}",

      include: ["<rootDir>/../../packages/ui/src"],

    },

  ],

  catalogsMergePath: "<rootDir>/src/i18n/{locale}",

  compileNamespace: "ts",

});
```

`lingui extract` from `apps/admin` updates `apps/admin/locales/*.po` and `packages/ui/locales/*.po`. `lingui compile` merges the messages of the app and its dependencies into one file per locale in `apps/admin/src/i18n/`. Several apps can list the same package. Each extraction writes the same messages into its catalog.

```
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/
```

`catalogsMergePath` applies only to `lingui compile`. The [Vite plugin](https://lingui.dev/ref/vite-plugin.md) and [webpack loader](https://lingui.dev/ref/loader.md) compile one `.po` file per import and do not merge. With them, call [`i18n.load`](https://lingui.dev/ref/core.md#i18n.load) once for the app's catalog and once per package. It merges messages of the same locale:

apps/admin/src/activate.ts

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



export async function activate(locale: string) {

  const app = await import(`../locales/${locale}.po`);

  const ui = await import(`../../../packages/ui/locales/${locale}.po`);

  i18n.load(locale, app.messages);

  i18n.load(locale, ui.messages);

  i18n.activate(locale);

}
```

Both tools compile a `.po` file from any directory, as long as the app's config lists its catalog.

## Dependency-Based Extraction[​](#dependency-based-extraction "Direct link to Dependency-Based Extraction")

Both strategies above tell Lingui which directories to scan. The [experimental extractor](https://lingui.dev/guides/message-extraction.md#dependency-tree-crawling) starts from the app's entry point instead, bundles it and follows every import, including workspace packages. There is no include list to maintain. Unused exports are tree-shaken away, so each catalog contains only the messages its app renders.

Experimental

This is an experimental feature. Experimental features are not covered by semver and may be subject to change.

apps/web/lingui.config.ts

```
import { defineConfig } from "@lingui/conf";

import { createEsbuildBundler } from "@lingui/cli/bundlers/esbuild";



export default defineConfig({

  sourceLocale: "en",

  locales: ["en", "cs"],

  catalogs: [],

  experimental: {

    extractor: {

      entries: ["<rootDir>/src/main.tsx"],

      output: "<rootDir>/src/locales/{locale}",

      bundler: createEsbuildBundler({ includeDeps: ["@acme"] }),

    },

  },

});
```

`includeDeps` lists the package scopes to follow. Other package imports are treated as external and skipped. Run `lingui extract-experimental` from the app. The shared packages need no configuration. Path aliases from `tsconfig.json` and the rolldown bundler are covered in [Configuring the Bundler](https://lingui.dev/guides/message-extraction.md#configuring-the-bundler).

## Published Packages[​](#published-packages "Direct link to Published Packages")

Consumers of an npm package cannot see its sources by default. The package either brings its translations along or leaves translation to the consumer. Three patterns work, from simplest to most flexible:

* Keep translations out of the package. Accept already-translated text as props (`label`, `placeholder`, `aria-label`) and let the consuming app translate it with its own catalog. This suits a few components, not a whole component library.
* One catalog for the whole library, shipped compiled. Extract all library packages into a single catalog and compile it in the library's build. Publish the compiled catalogs inside the library or as a dedicated package such as `@acme/translations`. The host app loads two catalogs with `i18n.load`, its own and the library's, as in the [example above](#catalog-per-package-merged-per-app) but from the library's compiled files. The library catalog also contains messages of components the app never renders, usually a small cost.
* Ship the sources next to the compiled output. Publish `src/` alongside `dist/`. The consuming app adds the package's source directory to `include`, for example `<rootDir>/node_modules/@acme/ui/src`, and translates the library's messages like its own. List each package directory explicitly. A wildcard such as `@acme/*/src` does not descend into the symlinks package managers create under `node_modules`.

In every case, declare `@lingui/react` and `@lingui/core` as `peerDependencies` so the package uses the consumer's copy, and rely on the consumer's `I18nProvider`.

## Sharing the Runtime[​](#sharing-the-runtime "Direct link to Sharing the Runtime")

The runtime setup is the same for every strategy:

* One `I18nProvider`, owned by the app. Shared packages render `<Trans>` and call `useLingui`, but never create a provider or load catalogs themselves. In components, take `t` from `useLingui()` rather than the global `t` from `@lingui/core/macro`. The global `t` uses the global `i18n` instance, not the one the provider passes down. It can then render untranslated text while the rest of the app is fine.

  packages/ui/src/SaveButton.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>

    );

  }
  ```

* Import macros directly in every package, from `@lingui/react/macro` and `@lingui/core/macro`. If you re-export them from a shared package instead, add that package to [`macro.corePackage`](https://lingui.dev/ref/conf.md#macrocorepackage) and [`macro.jsxPackage`](https://lingui.dev/ref/conf.md#macrojsxpackage). Without that, messages behind the re-export are silently skipped during extraction.

* Exactly one copy of `@lingui/react` and `@lingui/core`. Declare them in every package that uses them, with the same version. pnpm's `catalog:` protocol or a root-level override keeps versions aligned. Two copies mean two React contexts, and shared components throw an error about a missing `I18nProvider`.

* Optionally, a shared `i18n` instance. By default every package imports the same `i18n` singleton from `@lingui/core`, so there is nothing to do. If you create your own with `setupI18n`, export it from a workspace package such as `@acme/i18n` and set [`runtimeConfigModule`](https://lingui.dev/ref/conf.md#runtimeconfigmodule) to `["@acme/i18n", "i18n"]`. The value becomes an import in every transformed file, so a relative path such as `./i18n` would resolve from only one directory.

## Build Tooling[​](#build-tooling "Direct link to Build Tooling")

* **Babel.** `@lingui/babel-plugin-lingui-macro` searches for `lingui.config` upward from the build's working directory, not from the file being compiled. Files from sibling packages therefore get the app's config, which is what you want. Some Nx executors run the build from the repository root. In that case, point the `LINGUI_CONFIG` environment variable at the app's config file, or pass the plugin a `linguiConfig` option created with `getConfig` from `@lingui/conf`.

* **SWC.** [`@lingui/swc-plugin`](https://lingui.dev/ref/swc-plugin.md) does not read `lingui.config` at all. If you changed `runtimeConfigModule`, mirror it as `runtimeModules` in each app's SWC configuration.

* **Turborepo.** The app's `extract` task reads sources outside its package. Declare them as inputs with `$TURBO_ROOT$`, or the cached task will not rerun when a shared package changes:

  turbo.json

  ```
  {

    "tasks": {

      "extract": {

        "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/packages/*/src/**"],

        "outputs": ["src/locales/*.po"]

      }

    }

  }
  ```

  Nx users can express the same dependency with target `inputs`.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

* **Provider error from shared components.** `Trans component was rendered without I18nProvider` or `useLingui hook was used without I18nProvider` is thrown although the app renders a provider. There are two copies of `@lingui/react`. Run `pnpm why @lingui/react` (or `npm ls`, `yarn why`) and align the versions of `@lingui/*`, React and TypeScript across packages. A mismatch in any of them can make pnpm install a second copy.
* **Shared components stay untranslated.** They render source text or message IDs while the app is translated. They use the global `t` from `@lingui/core/macro`, but the app loads its catalogs into a different `i18n` instance. Use `useLingui()` in components, or load the catalogs into the global instance too.
* **Shared-package messages missing or obsolete.** The app's config does not include the package sources. Add its `src` directory to `include`, or switch to a catalog per package.
* **Paths differ between repo root and app.** Prefix every path with [`<rootDir>`](https://lingui.dev/ref/conf.md#rootdir). Paths without it resolve against the current working directory. Also run `extract` from the same directory each time. The source references in `.po` files are relative to it.
* **Nested `node_modules` or `dist` gets extracted.** `include` points at a whole package directory outside the app. Relative `exclude` patterns, including the default `node_modules` one, do not match files outside the working directory. Include the package's `src` directory instead, or prefix the `exclude` patterns with `<rootDir>` too.


---

# Keeping Your Bundle Small: How Lingui Optimizes for Performance

When you're building a modern app with internationalization (i18n), it's easy to end up with a bloated bundle. The more languages and messages you have, the more it can grow — fast.

Lingui helps you avoid this by aggressively optimizing how translations are handled in your code and in production builds. But these optimizations can also surprise you if you're not aware of how they work.

This guide walks you through:

* How Lingui shrinks your bundle
* What tradeoffs are involved
* Why development and production behave differently
* How to avoid common pitfalls
* And how to configure Lingui to fit your workflow

## Why does this matter?[​](#why-does-this-matter "Direct link to Why does this matter?")

Imagine you have a simple message:

```
<Trans>Hello world</Trans>
```

If this message is included *as-is* in your code and translations, you might end up with:

* The message string `"Hello world"` in your source code
* The same string as a key in your translation catalog
* And again as a value in your default language catalog

That's three copies of the same thing — and you'll have that for *every* message.

Now multiply that by hundreds of messages and a few languages, and you can see where this is going.

## So how does Lingui fix that?[​](#so-how-does-lingui-fix-that "Direct link to So how does Lingui fix that?")

### 1. It replaces messages with compact IDs[​](#1-it-replaces-messages-with-compact-ids "Direct link to 1. It replaces messages with compact IDs")

When you build your app, Lingui transforms:

```
<Trans>Hello world</Trans>
```

into something like:

```
<Trans id="zfhb1" />
```

The message is no longer part of the bundle. Instead, it's replaced by a short ID. This does two things:

* Saves space (IDs are shorter than full strings)
* Prevents duplication (only the translation needs to exist, not the original text)

### 2. It removes the message compiler from production[​](#2-it-removes-the-message-compiler-from-production "Direct link to 2. It removes the message compiler from production")

Messages like this:

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

use [ICU MessageFormat](https://formatjs.io/docs/core-concepts/icu-syntax), which needs to be *compiled* into something the Lingui runtime can use.

Lingui includes a message compiler for this, but it's not small.

Instead of sending that to the browser, Lingui compiles messages **ahead of time** during your build when you compile your catalogs. That way, you don't need the compiler in production at all.

That's why you need to always compile your catalogs, even if they are in JSON format (not `.po` files). Compilation isn't about converting file formats — it's about transforming messages into a form the runtime can execute.

note

✅ Tip: If you use the `@lingui/vite-plugin`, `@lingui/loader` or `@lingui/metro-transformer`, you don't need to run `lingui compile` manually — these plugins compile your catalogs automatically when you import catalogs.

## But wait... why does everything still work in development?[​](#but-wait-why-does-everything-still-work-in-development "Direct link to But wait... why does everything still work in development?")

Here's the clever part: Lingui works differently in dev vs prod.

In **development**, Lingui:

* Keeps the original message (`Hello world`) in the bundle
* Includes the message compiler so new messages work immediately

This makes it fast to iterate. You can add a new `<Trans>` and see the string in the browser right away — even if you haven't extracted or compiled anything yet.

In **production**, Lingui:

* Strips out all original messages
* Removes the message compiler completely

This means you **must** extract and compile all messages ahead of time — otherwise, Lingui won't know how to render them.

## Common Problem: “Why am I seeing weird message IDs in production?”[​](#common-problem-why-am-i-seeing-weird-message-ids-in-production "Direct link to Common Problem: “Why am I seeing weird message IDs in production?”")

Let's say you add a new message:

```
<Trans>This is a new message</Trans>
```

Everything looks fine locally, but when you deploy, users see something like:

```
z3fd2
```

This usually means one thing: the message wasn't extracted before building.

When Lingui compiles your catalogs, it tries to match each message ID to a source message. If the message isn't there, there's nothing to fall back to — and the raw ID ends up in the UI.

### ✅ Solution: Always extract before building[​](#-solution-always-extract-before-building "Direct link to ✅ Solution: Always extract before building")

Make sure your build script extracts the latest messages:

```
"build": "lingui extract-template && vite build"
```

This ensures your catalogs are in sync with your source code.

## But what if I want to load translations dynamically?[​](#but-what-if-i-want-to-load-translations-dynamically "Direct link to But what if I want to load translations dynamically?")

That's where the tradeoffs come in.

Lingui's design is optimized for build-time static analysis. It's great for most apps, but it can get tricky if you want to:

* Load translations from a CMS
* Support over-the-air (OTA) delivery of catalogs
* Inject new messages at runtime

In these cases, you can't rely on precompiled catalogs alone — you'll need the **runtime message compiler** again.

To bring it back, use:

```
import { compileMessage } from "@lingui/message-utils/compileMessage";



i18n.setMessagesCompiler(compileMessage);
```

Just keep in mind that this will increase your bundle size again.

## Configuring Lingui for your needs[​](#configuring-lingui-for-your-needs "Direct link to Configuring Lingui for your needs")

Here are a few ways to customize Lingui's behavior depending on your goals:

### 1. I want production to behave like development[​](#1-i-want-production-to-behave-like-development "Direct link to 1. I want production to behave like development")

You want to keep original messages, context, and use runtime compilation, even in production — maybe for debugging or dynamic catalogs.

**How to configure:**

```
// Macro config

descriptorFields: "message";



// Runtime setup

i18n.setMessagesCompiler(compileMessage);
```

This keeps `id`, `message`, and `context` in the output. The `context` is preserved because it is required for correct message ID generation.

### 2. I want full consistency between dev and prod[​](#2-i-want-full-consistency-between-dev-and-prod "Direct link to 2. I want full consistency between dev and prod")

You want everything to be stripped in both environments. Useful for catching issues early.

**How to configure:**

```
// Macro config

descriptorFields: "id-only";



// Runtime setup

i18n.setMessagesCompiler(null);
```

### 3. I want to use default Lingui behavior[​](#3-i-want-to-use-default-lingui-behavior "Direct link to 3. I want to use default Lingui behavior")

You don't change anything. Lingui automatically strips messages in production (`descriptorFields: "auto"`) and keeps them in development.

Just make sure to always run `extract-template` before building.

## Macro Configuration: A quick note[​](#macro-configuration-a-quick-note "Direct link to Macro Configuration: A quick note")

Depending on your setup, Lingui macros can be used in different ways:

* As a standalone **Babel plugin**
* As a [**SWC plugin**](https://github.com/lingui/swc-plugin)
* Through [**babel-plugin-macros**](https://github.com/kentcdodds/babel-plugin-macros/blob/main/other/docs/user.md#config)

Each one configures slightly differently, so check their docs for details.


---

# Pluralization

Pluralization is essential for effective internationalization, allowing applications to display messages or select options based on the number. In this article, we explore various categories of pluralization, see implementation examples, and learn how to customize your application for different languages.

Lingui uses the [CLDR Plural Rules](https://www.unicode.org/cldr/charts/42/supplemental/language_plural_rules.html) to determine the correct plural form for each language.

In general, there are 6 plural forms (taken from the [CLDR Plurals](https://cldr.unicode.org/index/cldr-spec/plural-rules) page):

* zero
* one (singular)
* two (dual)
* few (paucal)
* many (also used for fractions if they have a separate class)
* other (required — general plural form — also used if the language only has a single form)

info

Only the *other* form is required, because it's the only common plural form used in all languages.

All other plural forms depend on the language. For example, English has only two forms: *one* and *other* (1 book vs. 2 books). In Czech, we have four: *one*, *few*, *many* and *other* (1 kniha, 2 knihy, 1,5 knihy, 5 knih). Some languages have even more, such as Arabic.

## Using Plural Forms[​](#using-plural-forms "Direct link to Using Plural Forms")

The good thing is that **as developers, we only need to know the plural forms of the source language**.

When we use English in the source code, we'll only use *one* and *other*:

```
plural(numBooks, {

  one: "# book",

  other: "# books",

});
```

When `numBooks == 1`, this will render as *1 book* and for `numBook == 2` it will be *2 books*. Interestingly, for `numBooks == -1`, it will be *-1 book*. This is because the "one" plural form also applies to -1. It is therefore important to remember that the plural forms (such as "one" or "two") do not represent the numbers themselves, but rather *categories* of numbers.

Under the hood, the [`plural`](https://lingui.dev/ref/macro.md#plural) macro is replaced with a low-level [`i18n._`](https://lingui.dev/ref/core.md#i18n._) call. In production, the example will look like this:

```
i18n._({

  id: "d1wX4r",

  // stripped on production

  // message: '{numBooks, plural, one {# book} other {# books}}',

  values: { numBooks },

});
```

When we extract messages from the source code using the [Lingui CLI](https://lingui.dev/ref/cli.md), we get:

```
{numBooks, plural, one {# book} other {# books}}
```

This is then translated by our Czech translator as:

```
{numBooks, plural, one {# kniha} few {# knihy} many {# knihy} other {# knih}}
```

Important

The important thing is that *we don't have to change our code to support languages with different plural rules*.

## Source Code in Language Other than English[​](#source-code-in-language-other-than-english "Direct link to Source Code in Language Other than English")

As developers, we only need to be aware of the plural forms for the source language. Check the [plural forms](https://www.unicode.org/cldr/charts/42/supplemental/language_plural_rules.html) for your language, and then you can use them accordingly. Here's an example in Czech:

```
plural(numBooks, {

  one: "# kniha",

  few: "# knihy",

  many: "# knihy",

  other: "# knih",

});
```

This makes Lingui also valuable for monolingual projects, meaning that you can benefit from it even if you don't translate your application. Pluralization, along with number and date formatting, is relevant to all languages.


---

# Pseudolocalization

Pseudo-localization is a method used to check the software's readiness to be localized. This method shows how the product's UI will look after translation. Use this feature to reduce potential rework by checking whether any source strings should be altered before the translation process begins.

It also makes it easy to identify hard-coded strings and improperly concatenated strings so that they can be localized properly.

> Example: Ţĥĩś ţēxţ ĩś ƥśēũďōĺōćàĺĩźēď

## Configuration[​](#configuration "Direct link to Configuration")

To configure pseudolocalization, add the [`pseudoLocale`](https://lingui.dev/ref/conf.md#pseudolocale) property to your Lingui configuration file:

lingui.config.{ts,js}

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



export default defineConfig({

  locales: ["en", "pseudo-LOCALE"],

  pseudoLocale: { locale: "pseudo-LOCALE" },

  fallbackLocales: {

    "pseudo-LOCALE": "en",

  },

});
```

To generate several pseudolocales at once, for example one left-to-right and one right-to-left, pass an array:

lingui.config.{ts,js}

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



export default defineConfig({

  locales: ["en", "pseudo-LOCALE", "pseudo-RTL"],

  pseudoLocale: [{ locale: "pseudo-LOCALE" }, { locale: "pseudo-RTL", rightToLeft: true }],

  fallbackLocales: {

    "pseudo-LOCALE": "en",

    "pseudo-RTL": "en",

  },

});
```

The `pseudoLocale.locale` option must be set to any string that matches a value in the [`locales`](https://lingui.dev/ref/conf.md#locales) configuration. If this is not set correctly, no folder or pseudolocalization will be created.

caution

`pseudoLocale` also accepts a plain string (e.g. `pseudoLocale: "pseudo-LOCALE"`), but this form is deprecated and will be removed in a future major release. Use the object or array form instead.

The object form also lets you configure the underlying pseudolocalization library (markers, string length, and more). You can also provide an array of objects to configure multiple pseudolocales with different options. See the [`pseudoLocale`](https://lingui.dev/ref/conf.md#pseudolocale) reference for all available options.

If the `fallbackLocales` is configured, the pseudolocalization will be generated from the translated fallback locale instead.

## Generate Pseudolocalization[​](#generate-pseudolocalization "Direct link to Generate Pseudolocalization")

After running the [`extract`](https://lingui.dev/ref/cli.md#extract) command, verify that the folder for the pseudolocale has been created.

Pseudolocalization is automatically generated during the [`compile`](https://lingui.dev/ref/cli.md#compile) process, using the messages.

## Switch Browser Into Specified Pseudolocale[​](#switch-browser-into-specified-pseudolocale "Direct link to Switch Browser Into Specified Pseudolocale")

You can switch your browser to a pseudolocale either by adjusting the browser settings or by using extensions. Extensions provide flexibility by allowing you to use any locale, while browser settings are usually limited to valid language tags (BCP 47).

In such cases, the pseudolocale must be a standard locale that isn't already used in your application. For example, you could use `zu-ZA` (Zulu - South Africa).

Chrome:

* With extension (valid locale) - [Locale Switcher](https://chrome.google.com/webstore/detail/locale-switcher/kngfjpghaokedippaapkfihdlmmlafcc).
* Without extension (valid locale) - <chrome://settings/?search=languages>.

Firefox:

* With extension (any string) - [Quick Accept-Language Switcher](https://addons.mozilla.org/en-GB/firefox/addon/quick-accept-language-switc/?src=search).
* Without extension (valid locale) - [about](about:preferences#general)
  <!-- -->
  [:preferences](about:preferences#general)
  <!-- -->
  [#general](about:preferences#general) > *Language*.


---

# Testing

In a React application, components that use [`Trans`](https://lingui.dev/ref/react.md#trans) or [`useLingui`](https://lingui.dev/ref/react.md#uselingui) need access to the context provided by [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider). How you wrap your component with the I18nProvider depends on the testing library you're using.

Below is an example using [react-testing-library](https://testing-library.com/docs/react-testing-library/intro/) and its [wrapper-property](https://testing-library.com/docs/react-testing-library/api#wrapper):

index.js

```
import React from "react";

import { getByText, render, act } from "@testing-library/react";

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

import { I18nProvider } from "@lingui/react";



import { messages } from "./locales/en/messages";

import { messages as csMessages } from "./locales/cs/messages";

import App from "./App";



i18n.load({

  en: messages,

  cs: csMessages,

});



const TestingProvider = ({ children }: any) => <I18nProvider i18n={i18n}>{children}</I18nProvider>;



test("Content should be translated correctly in English", () => {

  act(() => {

    i18n.activate("en");

  });

  const { getByTestId, container } = render(<App />, { wrapper: TestingProvider });

  expect(getByTestId("h3-title")).toBeInTheDocument();

  expect(getByText(container, "Language switcher example:")).toBeDefined();

});



test("Content should be translated correctly in Czech", () => {

  act(() => {

    i18n.activate("cs");

  });

  const { getByTestId, container } = render(<App />, { wrapper: TestingProvider });

  expect(getByTestId("h3-title")).toBeInTheDocument();

  expect(getByText(container, "Příklad přepínače jazyků:")).toBeDefined();

});
```

To avoid repeating the `TestingProvider` setup in multiple tests, consider defining a custom renderer. You can find more about this in the [react testing library - Custom Render](https://testing-library.com/docs/react-testing-library/setup#custom-render) documentation.


---

# Translator-friendly Messages

Translators rarely see your UI. They see a catalog: one message at a time, out of order, with no screen around it. AI translation tools see exactly the same thing. Everything they can't learn from the message itself is a guess, and every guess is a bug you find only after release.

Lingui gives you several ways to put that missing knowledge into the message. This guide walks through them, from the sentence itself down to a single placeholder, and shows how to enforce each one with the [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) so quality doesn't depend on code review.

## Keep the Sentence Whole[​](#keep-the-sentence-whole "Direct link to Keep the Sentence Whole")

The most common context loss is splitting a sentence into pieces. Word order, grammar, and agreement differ between languages, so a translator needs the entire sentence to produce a correct one.

Don't build sentences from fragments:

```
// ❌ Three unrelated messages; nothing can be reordered in translation

<Trans>You have</Trans> {count} <Trans>unread messages</Trans>
```

Use one message with placeholders, and let ICU handle the plural forms:

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



<Plural value={count} one="You have # unread message" other="You have # unread messages" />;
```

The same applies to markup. [`Trans`](https://lingui.dev/ref/macro.md#trans) extracts a sentence with inline elements as a single string, so the translator can move the link to wherever their language needs it:

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



<Trans>

  Read the <a href="/docs">docs</a> before you start.

</Trans>;



// extracted message: "Read the <0>docs</0> before you start."
```

Use [`select`](https://lingui.dev/ref/macro.md#select) for grammatical variations such as gender instead of branching in code, so the whole sentence stays in one message for every variant. See [Pluralization](https://lingui.dev/guides/plurals.md) for the full set of ICU options.

Enforce with ESLint

[`no-single-variables-to-translate`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-single-variables-to-translate.md) catches `` t`${value}` `` and `<Trans>{value}</Trans>`, [`no-single-tag-to-translate`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-single-tag-to-translate.md) catches `<Trans><b>{value}</b></Trans>`, and [`no-trans-inside-trans`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-trans-inside-trans.md) catches a sentence that was split into nested `Trans` elements. All three are part of the recommended config.

## Name Your Placeholders[​](#name-your-placeholders "Direct link to Name Your Placeholders")

Simple variables become named placeholders automatically. Any other expression becomes a positional one:

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



t`Hello ${name}`; // Hello {name}

t`Hello ${user.name}`; // Hello {0}

t`Hello ${getUserName()}`; // Hello {0}
```

`{0}` says nothing about what will be inserted. Is it a name, a number, a date? Does it need an article, or a specific case? A named placeholder answers those questions for free.

Use the [`ph`](https://lingui.dev/ref/macro.md#ph) macro to label any expression:

```
import { t, ph } from "@lingui/core/macro";



t`Hello ${ph({ name: user.name })}`; // Hello {name}

t`Due ${ph({ dueDate: formatDate(task.due) })}`; // Due {dueDate}
```

It works everywhere expressions are accepted, including [`plural`](https://lingui.dev/ref/macro.md#plural), [`select`](https://lingui.dev/ref/macro.md#select), and JSX macros:

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

import { ph } from "@lingui/core/macro";



<Trans>Welcome back, {ph({ username: getUser().name })}!</Trans>;



// extracted message: "Welcome back, {username}!"
```

Extracting the expression into a well-named variable first gives the same result and is often the more readable choice.

note

Because variable names become placeholder names, renaming a variable changes the message and therefore its generated ID. `ph` decouples the two: the label stays stable even when the code around it is refactored.

### Placeholder Values in Catalog Comments[​](#placeholder-values-in-catalog-comments "Direct link to Placeholder Values in Catalog Comments")

For positional placeholders that remain, Lingui prints the source expression as a comment in the PO catalog, so translators at least see where the value comes from:

```
#. placeholder {0}: user.name

msgid "Hello {0}"

msgstr ""
```

This is on by default and controlled by the [`printPlaceholdersInComments`](https://lingui.dev/ref/catalog-formats.md#po-configuration) formatter option. Treat it as a safety net, not a replacement for naming: a comment is easier to overlook than the placeholder itself, and it is not shown by every translation tool.

Enforce with ESLint

[`no-expression-in-message`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-expression-in-message.md) reports member expressions and function calls inside messages. It accepts plain identifiers, `ph()`, and nested `plural`, `select`, and `selectOrdinal` calls. It is part of the recommended config.

## Name Your Tags[​](#name-your-tags "Direct link to Name Your Tags")

Inline elements inside `Trans` are indexed by default: `<0>`, `<1>`, and so on. In a sentence with two or three elements, the translator has to guess which index is the link and which is the emphasis, and reordering the elements in code silently changes the message.

Configure semantic names once in the Lingui config:

lingui.config.ts

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



export default defineConfig({

  // [...]

  macro: {

    jsxPlaceholderAttribute: "_t",

    jsxPlaceholderDefaults: {

      a: "link",

      strong: "bold",

      em: "emphasis",

      br: "br",

    },

  },

});
```

[`macro.jsxPlaceholderDefaults`](https://lingui.dev/ref/conf.md#macrojsxplaceholderdefaults) maps tag names to placeholder names, and [`macro.jsxPlaceholderAttribute`](https://lingui.dev/ref/conf.md#macrojsxplaceholderattribute) lets you name an individual element inline. The attribute is stripped from the compiled output:

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



<Trans>

  Click <a href="/">here</a> and <em>read carefully</em>.

</Trans>;

// Click <link>here</link> and <emphasis>read carefully</emphasis>.



<Trans>

  Read the{" "}

  <a _t="docs" href="/docs">

    docs

  </a>{" "}

  or the{" "}

  <a _t="faq" href="/faq">

    FAQ

  </a>

  .

</Trans>;

// Read the <docs>docs</docs> or the <faq>FAQ</faq>.
```

An explicit attribute wins over a default, and a default wins over the numeric index.

One name per distinct element

A placeholder name can be used only once per message. Two `<a>` elements with different props in the same sentence both map to `link` and the macro throws instead of numbering them. Give at least one of them an explicit `_t`, as in the second example above. Identical elements, such as two `<br />` with no props, share a single placeholder without error.

In TypeScript projects, declare the attribute so it type-checks on every element:

lingui.d.ts

```
import "react";



declare module "react" {

  interface Attributes {

    _t?: string;

  }

}
```

Named tags are supported by the Babel macro and the [SWC Plugin](https://lingui.dev/ref/swc-plugin.md#jsx-placeholder-naming-in-trans).

Enforce with ESLint

[`no-unnamed-tag-placeholders`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-unnamed-tag-placeholders.md) reports any element inside `Trans` that would still be extracted as a numeric tag. It is not in the recommended config, so enable it once your project has the config above.

## Explain What the Message Means[​](#explain-what-the-message-means "Direct link to Explain What the Message Means")

Placeholders and tags tell the translator what goes into the sentence. Two more pieces of information tell them what the sentence is for.

### Comment[​](#comment "Direct link to Comment")

A [`comment`](https://lingui.dev/ref/macro.md#comment) is a free-form note for the translator. It ends up in the catalog and in your TMS, and is removed from production code:

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

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



t({

  message: "Post",

  comment: "Verb: button that publishes the article. Keep it short, max 8 characters.",

});



<Trans comment="Shown in the empty state of the inbox, next to an illustration">No mail yet</Trans>;
```

Good comments say what the UI element is, where it appears, any length limits, and whether a word is a noun or a verb. Short strings such as "Back", "Post", "Save", or "Open" are exactly the ones that need it most.

### Context[​](#context "Direct link to Context")

[`context`](https://lingui.dev/guides/explicit-vs-generated-ids.md#context) disambiguates identical source strings. Two messages with the same text and different contexts get different IDs and can be translated differently:

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



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

<Trans context="correctness">right</Trans>;
```

Use `comment` when the text is unambiguous and you want to add information. Use `context` when the same text needs two translations. Context also changes the generated ID, so adding it to an already translated message creates a new entry in the catalog.

Enforce with ESLint

[`require-comment`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/require-comment.md) requires every message to carry a comment, either directly or from a `lingui-set` directive. It is strict by design and works best on new code or with `text-restrictions`-style exceptions for well-known strings.

## Set Context Once per File[​](#set-context-once-per-file "Direct link to Set Context Once per File")

Passing `comment` and `context` to every macro in a component gets noisy fast, and tagged templates such as `` t`Save` `` have no place to pass them at all. The [`lingui-set` and `lingui-reset` comment directives](https://lingui.dev/ref/macro.md#lingui-directive) apply values to every macro that follows them in the same file:

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

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



// lingui-set context="settings" comment="Account settings page"

const title = t`Account`;

const save = t`Save`;



function Page() {

  return <Trans>Delete account</Trans>;

}

// lingui-reset
```

All three messages are extracted with `context="settings"` and the comment. A later `lingui-set` merges into the current values, so you can set a base context at the top of the file and refine it per section. Explicit values on a macro always override the directive.

Directives are the cheapest way to add context to a legacy file where wrapping every call is impractical, and the only way to comment a tagged template literal. See the [reference](https://lingui.dev/ref/macro.md#lingui-directive) for merging, unsetting, and the `idPrefix` parameter.

Enforce with ESLint

A `lingui-set` that is never reset applies to every message added to the file later. [`require-directive-reset`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/require-directive-reset.md) requires each `lingui-set` to be closed with a `lingui-reset`.

## Point to the Source[​](#point-to-the-source "Direct link to Point to the Source")

The PO formatter records where each message is used:

```
#: src/pages/Settings.tsx:42

#. Account settings page

msgctxt "settings"

msgid "Save"

msgstr ""
```

The origin comment is enabled by default through the [`origins`](https://lingui.dev/ref/catalog-formats.md#po-configuration) and `lineNumbers` options. Translators working in a TMS that shows source references can open the file and see the surrounding code, which is often enough to resolve an ambiguity without a round trip to you. If your team prefers catalogs that don't change on every unrelated edit, set `lineNumbers: false` and keep `origins` on.

Translation platforms add context of their own on top of the catalog, such as screenshots and in-context editing. See [Sync & Collaboration Tools](https://lingui.dev/tools/introduction.md) for what each integration supports.

## Checklist[​](#checklist "Direct link to Checklist")

Use this as a review checklist for new messages, and turn as much of it as possible into lint rules:

| Practice                                      | Enforced by                                                                                           |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| One sentence per message, plurals via ICU     | `no-single-variables-to-translate`, `no-single-tag-to-translate`, `no-trans-inside-trans`             |
| Named placeholders, no `{0}`                  | `no-expression-in-message`                                                                            |
| Named tags, no `<0>`                          | `no-unnamed-tag-placeholders` with `macro.jsxPlaceholderAttribute` and `macro.jsxPlaceholderDefaults` |
| A comment on every short or ambiguous message | `require-comment`, or a `lingui-set comment` directive                                                |
| Context for identical strings                 | Review; `lingui-set context` per file                                                                 |
| Directives closed                             | `require-directive-reset`                                                                             |
| Source references in the catalog              | `origins` formatter option, on by default                                                             |

## See Also[​](#see-also "Direct link to See Also")

* [Explicit vs Generated IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md)
* [Pluralization](https://lingui.dev/guides/plurals.md)
* [Macros Reference](https://lingui.dev/ref/macro.md)
* [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md)
* [Catalog Formats](https://lingui.dev/ref/catalog-formats.md)


---

# Typed Message IDs

Lingui supports opt-in typed message IDs via TypeScript module augmentation. When enabled, all functions and components that accept a message `id` (i.e. `i18n._()`, `i18n.t()`, and `<Trans>`) will be narrowed to your specific set of known IDs, giving you autocomplete and compile-time errors for invalid IDs.

Without augmentation, `id` remains `string` and existing behavior is unchanged.

## Setup[​](#setup "Direct link to Setup")

Create a declaration file that augments the `Register` interface from `@lingui/core`:

src/lingui.d.ts

```
import type enMessages from "./locales/en/messages.json";



declare module "@lingui/core" {

  interface Register {

    messageIds: keyof typeof enMessages;

  }

}
```

The `messageIds` key must resolve to a union of string literal types. When `Register` is augmented with `messageIds`, the `MessageId` type resolves to that union. When `Register` is empty (the default), `MessageId` falls back to `string`.

## Usage[​](#usage "Direct link to Usage")

Once set up, TypeScript will flag invalid IDs:

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

## Notes[​](#notes "Direct link to Notes")

* This feature is **fully opt-in**. Without the `.d.ts` augmentation, all existing code continues to work with `string` IDs.
* There is **no runtime impact**. The `Register` interface and `MessageId` type are erased at compile time.
* You can point `messageIds` at any source that produces a string union, such as a compiled catalog JSON import, a hand-maintained union type, or a generated `.d.ts` file.


---

# Installation and Setup

Lingui is more than just a package; it's a comprehensive suite of tools designed to simplify internationalization. You have the flexibility to choose the specific tools that best fit your project's needs.

Learn how to install Lingui in your project, whether you use JavaScript, React (including Next.js and React Server Components) or React Native. Lingui also supports various transpilers and build tools, such as Babel, SWC, and Vite.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* Make sure you have [Node.js](https://nodejs.org/) installed (v22.19 or higher).
* Install [Lingui CLI](https://lingui.dev/ref/cli.md) to manage your translations and catalogs.

tip

Don't miss the [Lingui ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) which can help you find and prevent common i18n mistakes in your code.

## Choosing a Transpiler[​](#choosing-a-transpiler "Direct link to Choosing a Transpiler")

> A transpiler converts code within a language, transforming newer features into older equivalents for compatibility, or expanding concise syntax into more verbose implementations.

Lingui needs a transpiler to work. It's responsible for transforming Lingui's JS/JSX components into [ICU MessageFormat](https://lingui.dev/guides/message-format.md) and extracting message IDs. Both Babel and SWC transpilers are supported. Follow the Babel or SWC setup depending on what transpiler your project already uses. If you use Vite, you can skip this step: the [Vite plugin](#vite) transforms macros natively without Babel or SWC.

* Babel
* SWC

> Babel is a JavaScript transpiler that converts modern code into backward-compatible versions and allows custom syntax transformations.

Lingui requires `@lingui/babel-plugin-lingui-macro` (recommended) or [`babel-plugin-macros`](https://github.com/kentcdodds/babel-plugin-macros) (deprecated as of V6) to perform the transformation.

If you are using a framework that doesn't allow you to change the Babel configuration (e.g. Create React App > 2.0), these frameworks may support `babel-plugin-macros` out of the box.

Follow these steps to set up Lingui with Babel:

1. Install the `@lingui/babel-plugin-lingui-macro` package as a development dependency:

   * npm
   * Yarn
   * pnpm

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

   ```
   yarn add --dev @lingui/babel-plugin-lingui-macro
   ```

   ```
   pnpm add --save-dev @lingui/babel-plugin-lingui-macro
   ```

2. Add `@lingui/babel-plugin-lingui-macro` to the top of the `plugins` section of your Babel config (e.g. `.babelrc`):

   ```
   {

     "plugins": ["@lingui/babel-plugin-lingui-macro"]

   }
   ```

tip

When using a preset, first check if it includes the `macros` plugin. If so, then you don't need to install and set up `@lingui/babel-plugin-lingui-macro`. For example, `react-scripts` already includes the `macros` plugin.

caution

If you're using [React Compiler](https://react.dev/learn/react-compiler), make sure that `@lingui/babel-plugin-lingui-macro` comes **before** the React Compiler plugin in the Babel plugins list. This ensures macros are expanded correctly before the compiler processes the code.

> SWC is an extensible Rust-based platform for the next generation of fast developer tools.

Lingui supports SWC with a dedicated plugin [`@lingui/swc-plugin`](https://lingui.dev/ref/swc-plugin.md). SWC is significantly faster than Babel and is a good choice for large projects.

Follow these steps to set up Lingui with SWC:

1. Install `@lingui/swc-plugin` as a development dependency:

   * npm
   * Yarn
   * pnpm

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

   ```
   yarn add --dev @lingui/swc-plugin
   ```

   ```
   pnpm add --save-dev @lingui/swc-plugin
   ```

2. [Add necessary configurations](https://lingui.dev/ref/swc-plugin.md#usage).

caution

SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions is not guaranteed. See the [SWC compatibility](https://lingui.dev/ref/swc-plugin.md#swc-compatibility) for more information.

caution

If you're using [React Compiler](https://react.dev/learn/react-compiler) with SWC, the `@lingui/swc-plugin` must run **before** the React Compiler plugin. This is necessary because Lingui macros need to be expanded before the React Compiler processes your code.

However, in Next.js, the React Compiler is enabled via a simple boolean flag (`reactCompiler: true`) in `next.config.js`, and there's currently no way to control plugin ordering. As a result, Lingui may not work correctly with the React Compiler in SWC-based setups like Next.js.

## Basic Configuration[​](#basic-configuration "Direct link to Basic Configuration")

Lingui needs a configuration file to work. The configuration file specifies the source files, message catalogs, and other settings.

Let's create a basic configuration file in the root of your project (next to `package.json`):

lingui.config.js

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



export default defineConfig({

  sourceLocale: "en",

  locales: ["cs", "en"],

  catalogs: [

    {

      path: "<rootDir>/src/locales/{locale}/messages",

      include: ["src"],

    },

  ],

});
```

The configuration above specifies the source locale as English and the target locales as Czech and English.

According to this configuration, Lingui will extract messages from source files in the `src` directory and write them to message catalogs in `src/locales` (the English catalog would be in `src/locales/en/messages.po`, for example). See [Configuration](https://lingui.dev/ref/conf.md) for a complete reference.

note

Replace `src` with the name of the directory where you have the source files.

The PO format is the default and recommended format for message catalogs. See the [Catalog Formats](https://lingui.dev/ref/catalog-formats.md) for other available formats.

## Build Tools[​](#build-tools "Direct link to Build Tools")

### Vite[​](#vite "Direct link to Vite")

> Vite is a blazing fast frontend build tool powering the next generation of web applications.

Lingui supports Vite with a dedicated plugin [`@lingui/vite-plugin`](https://lingui.dev/ref/vite-plugin.md). This plugin compiles message catalogs on the fly and, with `macroTransform: true`, transforms Lingui macros natively. This is the recommended setup: it doesn't need `@lingui/babel-plugin-lingui-macro` or `@lingui/swc-plugin` and works with `@vitejs/plugin-react`, `@vitejs/plugin-react-swc` and Vite 8+ with Rolldown.

1. Install `@lingui/vite-plugin` as a development dependency and `@lingui/react` as a runtime dependency:

   * npm
   * Yarn
   * pnpm

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

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

   ```
   yarn add --dev @lingui/vite-plugin

   yarn add @lingui/react
   ```

   ```
   pnpm add --save-dev @lingui/vite-plugin

   pnpm add @lingui/react
   ```

2. Setup Lingui in `vite.config.ts`:

   vite.config.ts

   ```
   import { defineConfig } from "vite";

   import react from "@vitejs/plugin-react";

   import { lingui } from "@lingui/vite-plugin";



   export default defineConfig({

     plugins: [react(), lingui({ macroTransform: true })],

   });
   ```

Macro options are read from your Lingui configuration. See the [Native Macro Transform](https://lingui.dev/ref/vite-plugin.md#native-macro-transform) reference for the available overrides.

info

If you use React Compiler through `@rolldown/plugin-babel`, keep the Babel plugin for the compiler only and place `lingui()` before it in the `plugins` array:

```
plugins: [

  react(),

  lingui({ macroTransform: true }),

  babel({ presets: [reactCompilerPreset()] }),

],
```

#### Transforming Macros with Babel or SWC[​](#transforming-macros-with-babel-or-swc "Direct link to Transforming Macros with Babel or SWC")

If you prefer to keep transforming macros with your existing Babel or SWC pipeline, or you need an option the native transform doesn't support (for example `macro.jsxRuntime: "solid"`), use one of the setups below. Choose the one that fits your project.

* Babel (plugin-react)
* SWC (plugin-react-swc)
* Vite 8+ with Rolldown

The `@vitejs/plugin-react` plugin uses Babel to transform your code. To use Lingui with Vite and Babel, follow these steps:

1. Follow the [Choosing a Transpiler](#choosing-a-transpiler) instructions.

2. Install `@lingui/vite-plugin` as a development dependency and `@lingui/react` as a runtime dependency:

   * npm
   * Yarn
   * pnpm

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

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

   ```
   yarn add --dev @lingui/vite-plugin

   yarn add @lingui/react
   ```

   ```
   pnpm add --save-dev @lingui/vite-plugin

   pnpm add @lingui/react
   ```

3. Setup Lingui in `vite.config.ts`:

   vite.config.ts

   ```
   import { defineConfig } from "vite";

   import react from "@vitejs/plugin-react";

   import { lingui } from "@lingui/vite-plugin";



   export default defineConfig({

     plugins: [

       react({

         babel: {

           plugins: ["@lingui/babel-plugin-lingui-macro"],

         },

       }),

       lingui(),

     ],

   });
   ```

info

The `@vitejs/plugin-react` does not use the Babel config (e.g. `babel.rc`) from your project by default. You have to enable it manually or specify Babel options directly in `vite.config.ts`.

The `@vitejs/plugin-react-swc` plugin uses SWC to transform your code, which is significantly faster than Babel. To use Lingui with Vite and SWC, follow these steps:

1. Follow the [Choosing a Transpiler](#choosing-a-transpiler) instructions.

2. Install `@lingui/vite-plugin`, `@lingui/swc-plugin` as development dependencies and `@lingui/react` as a runtime dependency:

   * npm
   * Yarn
   * pnpm

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

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

   ```
   yarn add --dev @lingui/vite-plugin @lingui/swc-plugin

   yarn add @lingui/react
   ```

   ```
   pnpm add --save-dev @lingui/vite-plugin @lingui/swc-plugin

   pnpm add @lingui/react
   ```

3. Setup Lingui in `vite.config.ts`:

   vite.config.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(),

     ],

   });
   ```

Vite 8+ uses Rolldown to transpile and bundle your code. By default, it doesn't require Babel or SWC. If you don't want to use the native macro transform, you can transform Lingui macros with Babel through `@rolldown/plugin-babel` and the preset exported from `@lingui/vite-plugin`:

1. Install `@lingui/vite-plugin` and `@rolldown/plugin-babel` as development dependencies and `@lingui/react` as a runtime dependency:

   * npm
   * Yarn
   * pnpm

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

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

   ```
   yarn add --dev @lingui/vite-plugin @rolldown/plugin-babel

   yarn add @lingui/react
   ```

   ```
   pnpm add --save-dev @lingui/vite-plugin @rolldown/plugin-babel

   pnpm add @lingui/react
   ```

2. Setup Lingui in `vite.config.ts`:

   vite.config.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()],

       }),

     ],

   });
   ```

info

If you want to use React Compiler together with Lingui, place the React Compiler preset **before** the Lingui preset. Presets are applied in reverse order, so Lingui will be applied first.

```
plugins: [

  react(),

  lingui(),

  babel({ presets: [reactCompilerPreset(), linguiTransformerBabelPreset()] }),

],
```

### Next.js[​](#nextjs "Direct link to Next.js")

Next.js compiles with SWC by default, so Lingui macros need the [`@lingui/swc-plugin`](https://lingui.dev/ref/swc-plugin.md) registered in the Next.js config file. If your project has a Babel config, Next.js uses Babel instead and the Babel setup above applies. The Lingui configuration from the [Basic Configuration](#basic-configuration) section works unchanged.

next.config.mjs

```
import { linguiMacroSwcPlugin } from "@lingui/swc-plugin/options";



/** @type {import('next').NextConfig} */

const nextConfig = {

  experimental: {

    swcPlugins: [linguiMacroSwcPlugin()],

  },

};



export default nextConfig;
```

Routing by locale, loading catalogs in server and client components and switching the language are covered in the [Next.js App Router i18n tutorial](https://lingui.dev/tutorials/react-rsc.md). The [examples](https://github.com/lingui/js-lingui/tree/main/examples) directory has working Next.js projects for both the SWC and the Babel setup.

## See Also[​](#see-also "Direct link to See Also")

* [React i18n Tutorial](https://lingui.dev/tutorials/react.md)
* [Next.js App Router i18n Tutorial](https://lingui.dev/tutorials/react-rsc.md)
* [React Native i18n Tutorial](https://lingui.dev/tutorials/react-native.md)
* [JavaScript i18n Tutorial](https://lingui.dev/tutorials/javascript.md)


---

# Introduction

📖 Lingui is a lightweight, open-source internationalization (i18n) library for JavaScript and TypeScript. It brings compile-time macros and a CLI for message extraction to React, React Native, Vue, SolidJS, Astro, Svelte, and Node.js.

You wrap text in macros like `Trans` and `t`, and the CLI extracts it into PO catalogs that any translation tool can open. Once translated, the catalogs are compiled into small modules that your app loads at runtime.

> **Internationalization** is the design and development of a product, application or document content that enables easy **localization** for target audiences that vary in culture, region, or language.
>
> — [W3C Web Internationalization FAQ](https://www.w3.org/International/questions/qa-i18n)

[![GitHub stars](https://img.shields.io/github/stars/lingui/js-lingui.svg?style=social\&label=Stars)](https://github.com/lingui/js-lingui/)

## Design Decisions[​](#design-decisions "Direct link to Design Decisions")

Three design decisions shape how Lingui feels to use.

Messages are compiled at build time by a [Babel or SWC plugin](https://lingui.dev/installation.md#choosing-a-transpiler). Most frameworks already run one of the two, so setup is usually one line in your Next.js, Vite or Babel config. The runtime stays around 2 kB and ships no message parser.

Message IDs are generated from the source text. You never name a key, duplicate messages are merged, and searching for a UI string leads straight to the code. When the source text changes, the message is treated as new and goes back to translators; for strings that change often, [explicit IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md) keep the ID stable.

Catalogs are PO files by default, so any translation tool opens them and comments and context travel with each message. [JSON and CSV formats](https://lingui.dev/ref/catalog-formats.md) are available if your team already works with them.

If you are weighing Lingui against a library you already use, see [Lingui vs i18next](https://lingui.dev/misc/i18next.md) and [Lingui vs react-intl](https://lingui.dev/misc/react-intl.md).

## Key Features[​](#key-features "Direct link to Key Features")

### Clean and Readable[​](#clean-and-readable "Direct link to Clean and Readable")

Keep your code clean and readable, while the library uses battle-tested and powerful **ICU MessageFormat** under the hood.

### Lightweight and Optimized[​](#lightweight-and-optimized "Direct link to Lightweight and Optimized")

Core library [![@lingui/core](https://deno.bundlejs.com/?q=%40lingui%2Fcore\&treeshake=%5B%7Bi18n%7D%5D\&badge=)](https://bundlejs.com/?q=%40lingui%2Fcore), React components [![@lingui/react](https://deno.bundlejs.com/?q=%40lingui%2Freact\&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22%40lingui%2Fcore%22%5D%7D%7D\&badge=)](https://bundlejs.com/?q=%40lingui%2Freact\&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22%40lingui%2Fcore%22%5D%7D%7D).

### Universal[​](#universal "Direct link to Universal")

Use it everywhere. [`@lingui/core`](https://lingui.dev/ref/core.md) is the framework-agnostic layer: it loads compiled catalogs, keeps track of the active locale, and formats messages with ICU MessageFormat - the same behavior in the browser, on a Node server, or in a small script.

If you are not using a UI framework, the [JavaScript tutorial](https://lingui.dev/tutorials/javascript.md) shows how to wire up core macros and catalogs from scratch.

For React apps, [`@lingui/react`](https://lingui.dev/ref/react.md) adds components and hooks that follow the renderer's lifecycle, including [React Server Components](https://lingui.dev/tutorials/react-rsc.md). For React Native, the [React Native tutorial](https://lingui.dev/tutorials/react-native.md) uses the same extract-and-compile workflow. For SolidJS apps, [`@lingui/solid`](https://lingui.dev/ref/solid.md) provides native bindings with reactive `Trans` components and a `useLingui` hook - follow the [SolidJS tutorial](https://lingui.dev/tutorials/solid.md) to get started. Lingui is also compatible with Astro and Svelte via community-supported packages.

### Full Rich-text Support[​](#full-rich-text-support "Direct link to Full Rich-text Support")

Seamlessly use React components within localized messages, without any restrictions. Creating rich-text messages feels just like writing JSX.

This keeps message catalogs in sync with the source code, preventing obsolete messages and lowering translation costs.

### Powerful Tooling[​](#powerful-tooling "Direct link to Powerful Tooling")

Manage your intl workflow with the Lingui [CLI](https://lingui.dev/ref/cli.md), [Vite Plugin](https://lingui.dev/ref/vite-plugin.md), and [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md). The CLI extracts, compiles and validates messages, while the Vite plugin compiles catalogs on the fly, and the ESLint plugin helps catch common usage errors.

### Unopinionated[​](#unopinionated "Direct link to Unopinionated")

Integrate Lingui into your existing workflow. It supports explicit message keys as well as auto-generated ones. Translations are stored in a standard PO file, which is supported by almost all translation tools. You can also use CSV or JSON, or add a custom formatter of your own.

### Built for AI-assisted Workflows[​](#built-for-ai-assisted-workflows "Direct link to Built for AI-assisted Workflows")

For AI to do great translations for you, context is critical. Translating UI copy is difficult because it's usually a list of short strings without enough context. Lingui's localization formats allow developers to write descriptions of where and how their keys are used.

Install [`lingui/skills`](https://github.com/lingui/skills) to help your AI assistant understand Lingui patterns and apply them consistently across your project. For context files, MCP setup, and more, see [i18n with AI](https://lingui.dev/ai-tools.md).

### Active Community[​](#active-community "Direct link to Active Community")

Join the growing [community of developers](https://lingui.dev/community) who are using Lingui to build global products.

## Workflow[​](#workflow "Direct link to Workflow")

Using Lingui for internationalization is a straightforward cycle. You define messages in code, extract them into catalogs, translate, compile optimized runtime output, and ship localized builds.

<!-- -->

### Define Messages[​](#define-messages "Direct link to Define Messages")

Write user-facing text where it is used, using Lingui macros/components such as `Trans` and `t`. Keep messages close to the UI logic so they stay maintainable, and add context (for example comments or descriptions) for better translation quality.

### Extract[​](#extract "Direct link to Extract")

Run the Lingui CLI to scan your source files and collect translatable messages into catalog files (PO by default). Extraction updates existing catalogs, adds new messages, and marks removed ones so translators always work with the latest source text.

### Translate[​](#translate "Direct link to Translate")

Translate the extracted catalogs manually or with your localization platform. Translators work on stable message IDs/source messages, preserving placeholders and ICU syntax so runtime formatting remains correct.

### Compile[​](#compile "Direct link to Compile")

Compile catalogs into optimized JavaScript modules for runtime usage. Compilation validates message syntax and prepares only the data your app needs, reducing bundle size and startup overhead.

### Deploy[​](#deploy "Direct link to Deploy")

Ship compiled catalogs with your app and load the right locale based on user preference or app settings. In production, this gives users fast localized rendering and lets you repeat the same workflow whenever copy changes.

## Quick Overview[​](#quick-overview "Direct link to Quick Overview")

```
import React from "react";

import { ph } from "@lingui/core/macro";

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



export default function Lingui({ numUsers, user }) {

  const { t } = useLingui();



  return (

    <div>

      <h1>

        {/* Localized messages are wrapped in <Trans> */}

        <Trans>Internationalization in React</Trans>

      </h1>



      {/* Element attributes are translated using the t macro */}

      <img src="./logo.png" alt={t`Logo of Lingui Project`} />



      <p>

        {/*

          ph() gives placeholders explicit names when using expressions.

          This improves context for translators.

        */}

        <Trans>

          Hello {ph({ userName: user.name })}, Lingui is a readable, automated, and optimized i18n for JavaScript.

        </Trans>

      </p>



      {/* React elements inside messages work in the same way as in JSX */}

      <p>

        <Trans>

          Read the <a href="https://lingui.dev">documentation</a> for more info.

        </Trans>

      </p>



      {/*

        Plurals are managed using ICU plural rules.

        Nesting of i18n components is allowed.

        Syntactically valid message in ICU MessageFormat is guaranteed.

      */}

      <Plural

        value={numUsers}

        one={

          <span>

            Only <strong>one</strong> user is using this library!

          </span>

        }

        other={

          <span>

            <strong>{numUsers}</strong> users are using this library!

          </span>

        }

      />

    </div>

  );

}
```

## See Also[​](#see-also "Direct link to See Also")

* [Installation and Setup](https://lingui.dev/installation.md)
* [i18n with AI](https://lingui.dev/ai-tools.md)


---

# Lingui vs i18next

[i18next](https://www.i18next.com/) is one of the most widely used internationalization frameworks for JavaScript, with bindings for React, Vue, Angular, Svelte and many other frameworks and platforms. Both libraries solve the same problem, but they start from different ideas. With i18next you invent a key for each string, put the text in a JSON file and look the key up at runtime. With Lingui you write the text where it is displayed, the IDs are generated from it and the catalogs are compiled at build time.

That difference runs through everything else on this page: how messages are written, what translators receive and what ships to the browser.

## At a Glance[​](#at-a-glance "Direct link to At a Glance")

|                    | Lingui                                                                                                                         | i18next                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Writing messages   | The text stays in the code: `` t`Hello ${name}` ``. The catalog is generated from it                                           | You choose a key, add the text to a JSON file and reference the key: `t("greeting", { name })`                                         |
| Message IDs        | Generated from the source text, so there is nothing to name and duplicates merge on their own. Explicit IDs when you want them | Keys you define and keep unique yourself. Natural-language keys are possible with `keySeparator: false`                                |
| Message syntax     | ICU MessageFormat. Placeholders, plurals and selects stay inside one message                                                   | Own `{{name}}` syntax. Each plural form is a separate key (`key_one`, `key_other`). ICU needs the `i18next-icu` plugin                 |
| Extraction         | Built in. `lingui extract` finds every message, merges it into all catalogs and marks removed ones obsolete                    | Separate tools: `i18next-cli` (the successor of `i18next-parser`) or `i18next-scanner`                                                 |
| Translator context | Source locations, comments and context travel with each message in the PO file                                                 | JSON has no comments. Key locations need a custom `i18next-cli` metadata plugin                                                        |
| Catalog format     | PO by default, which every translation tool opens. JSON, CSV and custom formatters available                                   | JSON, bundled inline or loaded through backend plugins. YAML and JSON5 via `i18next-cli`                                               |
| Runtime            | Catalogs are compiled at build time and no message parser ships. Core about 2 kB gzipped                                       | Messages interpolated at runtime. Core about 14 kB gzipped                                                                             |
| React              | `@lingui/react` with macros. React Server Components through `@lingui/react/server`                                            | `react-i18next`. For React Server Components, `next-i18next` v16 adds `getT` and `useT`, or you create an i18next instance per request |
| Other frameworks   | React Native, Vue, SolidJS, Astro, Svelte, Node.js                                                                             | Vue, Angular, Svelte, SolidJS, Astro, Remix, Node.js and more                                                                          |
| TypeScript         | Written in TypeScript. Opt-in typed message IDs via module augmentation                                                        | Ships type definitions. Typed keys and interpolation values via `CustomTypeOptions`                                                    |

Bundle sizes were measured with [bundlejs](https://bundlejs.com/) in September 2026 for `@lingui/core` 6.6 and `i18next` 26.4.

## Basic Comparison[​](#basic-comparison "Direct link to Basic Comparison")

Here's a simple example of how to use i18next:

```
import i18next from "i18next";



i18next.init({

  lng: "en",

  resources: {

    en: {

      translation: {

        key: "Hello world",

      },

    },

  },

});
```

```
import i18next from "i18next";



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

To know what this line renders, you open the JSON file and look up `key`. The equivalent example with Lingui keeps the text in the code, and the CLI generates the catalog from it:

lingui.config.{js,ts}

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



export default defineConfig({

  sourceLocale: "en",

  locales: ["en", "cs", "fr"],

  catalogs: [

    {

      path: "<rootDir>/src/locales/{locale}/messages",

      include: ["src"],

    },

  ],

});
```

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



document.getElementById("output").innerHTML = t`Hello world`;
```

tip

This example uses a macro for the translation. Macros are a powerful feature of Lingui that allows you to write messages directly in your code. Read more about [Macros](https://lingui.dev/ref/macro.md).

If you prefer to define explicit IDs for your messages, you can follow this approach:

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



document.getElementById("output").innerHTML = t({ id: "msg.greeting", message: `Hello World` });
```

Read more about [Explicit vs Generated Message IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md).

## Interpolation[​](#interpolation "Direct link to Interpolation")

Interpolation is a key internationalization (i18n) feature that allows you to insert dynamic values into your translations. Both Lingui and i18next support interpolation.

i18next sample:

```
import i18next from "i18next";



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

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

Lingui sample:

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



const name = "Tom";



t`My name is ${name}`;

t({ id: "msg.name", message: `My name is ${name}` });
```

Lingui names the placeholder after the variable, so the message and the code cannot drift apart. With i18next, the `{{name}}` in the JSON file and the `{ name }` in the call are matched by hand.

## Formatting[​](#formatting "Direct link to Formatting")

Both Lingui and i18next formatting functions are based on the [Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).

### Numbers[​](#numbers "Direct link to Numbers")

i18next sample:

```
import i18next from "i18next";



i18next.t("intlNumber", { val: 1000 });

// --> Some 1,000



i18next.t("intlNumber", { val: 1000.1, minimumFractionDigits: 3 });

// --> Some 1,000.100



i18next.t("intlNumber", { val: 1000.1, formatParams: { val: { minimumFractionDigits: 3 } } });

// --> Some 1,000.100



i18next.t("intlNumberWithOptions", { val: 2000 });

// --> Some 2,000.00



i18next.t("intlNumberWithOptions", { val: 2000, minimumFractionDigits: 3 });

// --> Some 2,000.000
```

Lingui sample:

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



i18n.activate("en");

new Intl.NumberFormat(i18n.locale).format(12345.678);

// Returns "12,345.678"



new Intl.NumberFormat(i18n.locale, { style: "currency", currency: "USD" }).format(12345.678);

// Returns "$12,345.68"



i18n.activate("cs");

new Intl.NumberFormat(i18n.locale).format(12345.678);

// Returns "12 345,678"



new Intl.NumberFormat(i18n.locale, { style: "currency", currency: "CZK" }).format(12345.678);

// Returns "12 345,68 Kč"
```

### DateTime[​](#datetime "Direct link to DateTime")

i18next sample:

```
import i18next from "i18next";



i18next.t("intlDateTime", { val: new Date(Date.UTC(2012, 11, 20, 3, 0, 0)) });

// --> On the 12/20/2012



i18next.t("intlDateTime", {

  val: new Date(Date.UTC(2012, 11, 20, 3, 0, 0)),

  formatParams: {

    val: { weekday: "long", year: "numeric", month: "long", day: "numeric" },

  },

});

// --> On the Thursday, December 20, 2012
```

Lingui sample:

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



const d = new Date("2021-07-23T16:23:00");



i18n.activate("en");

new Intl.DateTimeFormat(i18n.locale).format(d);

// Returns "7/23/2021"



new Intl.DateTimeFormat(i18n.locale, { timeStyle: "medium" }).format(d);

// Returns "4:23:00 PM"



new Intl.DateTimeFormat(i18n.locale, { dateStyle: "medium", timeStyle: "medium" }).format(d);

// Returns "Jul 23, 2021, 4:23:00 PM"
```

## Plurals[​](#plurals "Direct link to Plurals")

Lingui uses the [ICU MessageFormat](https://lingui.dev/guides/message-format.md) syntax to handle plurals. All forms of a message stay together in one string that the translator sees as a whole.

For example:

```
plural(numBooks, {

  one: "# book",

  other: "# books",

});
```

Under the hood, the [`plural`](https://lingui.dev/ref/macro.md#plural) macro is replaced with a low-level [`i18n._`](https://lingui.dev/ref/core.md#i18n._) call. In production, the example will look like this:

```
i18n._({

  id: "d1wX4r",

  // stripped on production

  // message: '{numBooks, plural, one {# book} other {# books}}',

  values: { numBooks },

});
```

When we extract messages from the source code using the [Lingui CLI](https://lingui.dev/ref/cli.md), we get:

```
{numBooks, plural, one {# book} other {# books}}
```

i18next stores each plural form under its own key. The suffixes follow the CLDR plural categories returned by `Intl.PluralRules`, so English uses `_one` and `_other`, while Arabic adds `_zero`, `_two`, `_few` and `_many`:

```
{

  "key_one": "item",

  "key_other": "items"

}
```

```
import i18next from "i18next";



i18next.t("key", { count: 0 }); // -> "items"

i18next.t("key", { count: 1 }); // -> "item"

i18next.t("key", { count: 5 }); // -> "items"
```

In the catalog, `item` and `items` are two separate entries. Nothing ties them together or shows the translator the sentence they appear in. If you prefer ICU plurals with i18next, the [`i18next-icu`](https://github.com/i18next/i18next-icu) plugin switches the message syntax to ICU MessageFormat, at which point i18next's own interpolation and plural keys no longer apply.

## Context[​](#context "Direct link to Context")

By providing context, you can differentiate translations for the same sentences or provide translators with more details. Both i18next and Lingui have the context feature to differentiate messages.

i18next sample:

```
import i18next from "i18next";



i18next.t("Right", { context: "direction" });
```

Lingui sample:

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



msg({

  message: "Right",

  context: "direction",

});
```

tip

Lingui also writes the source locations of each message into the `.po` file, together with `msgctxt` when a context is given, so translators can see where a message is used:

en.po

```
#: src/App.js:5

msgctxt "direction"

msgid "Right"

msgstr "Right"
```

JSON has no comment syntax, so this information is not part of i18next catalogs by default. `i18next-cli` can record key locations through a custom metadata plugin.

## React Integration[​](#react-integration "Direct link to React Integration")

Both libraries provide React components for handling translations in React applications. Lingui provides a set of [React Macros](https://lingui.dev/ref/macro.md#react-macros) that simplify writing messages directly in your code. i18next provides a `Trans` component to handle translations in JSX.

i18next sample:

```
import { Trans } from "react-i18next";



const HelloWorld = () => {

  return <Trans i18nKey="welcome">Hello World!</Trans>;

};
```

The translation lives under `welcome` in the JSON file. The children are the fallback when the key is missing.

Lingui sample:

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



const HelloWorld = () => {

  return <Trans>Hello World!</Trans>;

};
```

Here the children are the message. The ID is derived from them, and `lingui extract` writes the entry to the catalog.

## Summary[​](#summary "Direct link to Summary")

Both libraries build on the same foundations: the `Intl` API for formatting, CLDR plural rules and one catalog per locale. They differ in how much of the bookkeeping is yours.

**Lingui:**

* Messages are written in the source with macros. There are no keys to invent and no JSON file to keep in sync, because `lingui extract` generates the catalog from the code.
* Plurals, selects and rich text stay inside one message, and React elements inside a message stay in one translatable string.
* Catalogs are PO files by default, which every translation tool opens and which carry source locations and comments for translators. JSON, CSV and [custom formatters](https://lingui.dev/guides/custom-formatter.md) are available. See [Catalog Formats](https://lingui.dev/ref/catalog-formats.md).
* Catalogs are compiled ahead of time, so the runtime ships without a message parser and stays around 2 kB gzipped.
* Works with vanilla JS, React (including React Server Components), React Native, Next.js, Vue, SolidJS, Astro, Svelte and Node.js.

**i18next:**

* Messages are looked up by key. Resources are plain JSON and can be loaded from the filesystem, over HTTP or from a translation platform through backend plugins.
* Has been around for more than a decade and covers nearly every i18n scenario, with an official CLI for extraction, type generation and linting.
* Has a large plugin ecosystem: language detectors, backends, post processors and alternative message formats such as ICU and Fluent.
* Has bindings or ports for many frameworks and platforms, including Vue, Angular, Svelte, .NET, Go, iOS and Android.

i18next's breadth is real, and if your organization already runs it across several stacks, that continuity counts. For a JavaScript or TypeScript codebase, Lingui covers the same ground with less to maintain by hand: no keys to name, no JSON to keep in sync, and catalogs that open in any translation tool.


---

# Lingui vs react-intl

[react-intl](https://formatjs.github.io/docs/react-intl/) is the React binding of [FormatJS](https://formatjs.github.io/), a long-standing i18n project that also ships a Vue binding, a CLI and `Intl` polyfills. [Lingui](https://github.com/lingui/js-lingui) is a close relative: both libraries use ICU MessageFormat for messages, and their low-level APIs look almost the same. The differences are in how much of the message syntax you write yourself, how much the tooling does for you, and what ships to the browser.

## At a Glance[​](#at-a-glance "Direct link to At a Glance")

|                   | Lingui                                                                                                                                | react-intl (FormatJS)                                                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Writing messages  | Macros generate the ICU message from JSX or a template literal: `<Trans>Hello {name}</Trans>`                                         | You write the ICU string yourself: `<FormattedMessage defaultMessage="Hello {name}" values={{ name }} />`                                                               |
| Rich text         | Components inside a message are plain JSX. The translator sees `Read the <0>documentation</0>`                                        | Each tag maps to a render function in `values`: `link: (chunks) => <a href="/docs">{chunks}</a>`                                                                        |
| Message IDs       | Generated from the source text by the macro, explicit IDs optional                                                                    | Explicit `id`, or a generated hash with the Babel or SWC plugin or the TypeScript transformer                                                                           |
| Extraction        | `lingui extract` merges new messages into every locale's catalog, keeps existing translations and marks removed ones obsolete         | `formatjs extract` writes the source messages to one JSON file. Translated files are handled separately, with formatters for Crowdin, Lokalise, Smartling and Transifex |
| Catalog format    | PO by default, which every translation tool opens. JSON, CSV and custom formatters available                                          | JSON, in the FormatJS layout or a translation platform's layout                                                                                                         |
| Runtime           | Catalogs are compiled at build time and no parser ships. Core and React bindings about 4 kB gzipped                                   | Messages parsed at runtime unless pre-compiled with `formatjs compile --ast`. About 15 kB gzipped                                                                       |
| Server Components | `@lingui/react/server`. `Trans` works in server and client components alike                                                           | `react-intl/server` with `createIntl`. `FormattedMessage` and `useIntl` are client-only                                                                                 |
| Beyond React      | `@lingui/core` for Node.js and plain JS, `@lingui/solid` for SolidJS. The same core and CLI serve React Native, Vue, Astro and Svelte | `@formatjs/intl` for plain JS, `vue-intl` for Vue                                                                                                                       |
| TypeScript        | Written in TypeScript. Opt-in typed message IDs via module augmentation                                                               | Written in TypeScript. Typed message IDs via the `FormatjsIntl` global namespace                                                                                        |

Bundle sizes were measured with [bundlejs](https://bundlejs.com/) in September 2026 for `@lingui/core` and `@lingui/react` 6.6 and `react-intl` 10.1, with `react` excluded.

## Basic Comparison[​](#basic-comparison "Direct link to Basic Comparison")

Here's an example from the react-intl docs:

```
<FormattedMessage

  id="welcome"

  defaultMessage={`Hello {name}, you have {unreadCount, number} {unreadCount, plural,

     one {message}

     other {messages}

   }`}

  values={{ name: <b>{name}</b>, unreadCount }}

/>
```

Looking at the low-level API of Lingui, there isn't much difference:

```
<Trans

  id="welcome"

  message={`Hello {name}, you have {unreadCount, number} {unreadCount, plural,

     one {message}

     other {messages}

   }`}

  values={{ name: <b>{name}</b>, unreadCount }}

/>
```

There's really no reason to reinvent the wheel when both libs are built on top of the same message syntax. The story doesn't end here, though.

## Translations with Rich-Text Markup[​](#translations-with-rich-text-markup "Direct link to Translations with Rich-Text Markup")

Suppose we have the following text:

```
<p>Read the <a href="/docs">documentation</a>.</p>
```

In react-intl, this would be translated as:

```
<FormattedMessage

  id="msg.docs"

  defaultMessage="Read the <link>documentation</link>."

  values={{

    link: (chunks) => <a href="/docs">{chunks}</a>,

  }}

/>
```

Each tag needs a function that receives the translated chunks and wraps them.

Lingui extends the ICU MessageFormat with tags. The above example would be:

```
<Trans id="msg.docs" message="Read the <link>documentation</link>." components={{ link: <a href="/docs" /> }} />
```

The element is passed as it is, with no wrapper function, and the translator gets the message in one piece: `Read the <link>documentation</link>`.

## Macros for Component-Based Message Syntax[​](#macros-for-component-based-message-syntax "Direct link to Macros for Component-Based Message Syntax")

Lingui provides powerful [Macros](https://lingui.dev/ref/macro.md) that automatically generate a message syntax.

Let's go back to the previous example:

```
<p>Read the <a href="/docs">documentation</a>.</p>
```

All we need to do is to wrap the message in a [`Trans`](https://lingui.dev/ref/macro.md#trans) macro:

```
<p>

  <Trans id="msg.docs">Read the <a href="/docs">documentation</a>.</Trans>

</p>
```

The macro will then parse the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro children and automatically generate `message` and `components` props in the form described in the previous section.

This is very useful when adding i18n to an existing project. All we need to do is wrap all messages in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro.

Let's compare it to the react-intl solution to see the difference:

```
<p>

  <FormattedMessage

    id="msg.docs"

    defaultMessage="Read the <link>documentation</link>."

    values={{

      link: (chunks) => <a href="/docs">{chunks}</a>,

    }}

  />

</p>
```

FormatJS also has Babel and SWC plugins, but they generate message IDs and pre-compile messages. The ICU string in `defaultMessage` is still written by hand.

note

It's also worth mentioning that the message IDs are completely optional. Lingui is unopinionated in this way and perfectly works with messages as IDs as well:

```
<p>

  <Trans>Read the <a href="/docs">documentation</a>.</Trans>

</p>
```

The message ID is `Read the <0>documentation</0>.` instead of `msg.docs`. Both solutions have pros and cons and the library lets you choose the one which works best for you.

Read more about [Explicit vs Generated Message IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md).

## Plurals[​](#plurals "Direct link to Plurals")

Another very common linguistic feature is pluralization.

Let's take a look at the original example from react-intl docs:

```
<FormattedMessage

  id="welcome"

  defaultMessage={`Hello {name}, you have {unreadCount, number} {unreadCount, plural,

     one {message}

     other {messages}

   }`}

  values={{ name: <b>{name}</b>, unreadCount }}

/>
```

Using Lingui macros, we could combine [`Trans`](https://lingui.dev/ref/macro.md#trans) and [`Plural`](https://lingui.dev/ref/macro.md#plural-1) components:

```
<Trans id="welcome">

  Hello <b>{name}</b>, you have {unreadCount} <Plural value={unreadCount} one="message" other="messages" />

</Trans>
```

and the final message would be very similar:

```
<Trans

  id="welcome"

  message={`Hello <0>{name}</0>, you have {unreadCount, number} {unreadCount, plural,

     one {message}

     other {messages}

   }`}

  values={{ name, unreadCount }}

/>
```

The only difference is the `<0>` tag in the message, since Lingui can handle components in variables as well as in the message itself.

note

It's worth mentioning here that this is not the best example of using plurals. Make your translators happy by moving plurals to the top of the message:

```
<Plural

  id="welcome"

  value={unreadMessages}

  one={

    <>

      Hello <b>{name}</b>, you have {unreadMessages} message.

    </>

  }

  other={

    <>

      Hello <b>{name}</b>, you have {unreadMessages} messages.

    </>

  }

/>
```

Even though both variants are syntactically valid in ICU MessageFormat, the second one is easier for translating, because (again) the translator gets the phrase in one piece.

## Text Attributes[​](#text-attributes "Direct link to Text Attributes")

Components can't be used in some contexts, e.g. to translate text attributes. react-intl provides `formatMessage` from the `useIntl` hook for this. Lingui provides the `t` macro, which the [`useLingui`](https://lingui.dev/ref/macro.md#uselingui) macro binds to the `i18n` instance from the React context:

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

import { plural } from "@lingui/core/macro";



function Flag({ name, count }) {

  const { t } = useLingui();



  return (

    <>

      <a title={t`The title of ${name}`}>{name}</a>

      <img alt={t`${plural(count, { one: "flag", other: "flags" })}`} src="..." />

    </>

  );

}
```

Custom IDs are supported as well:

```
<a title={t({ id: "link.title", message: `The title of ${name}` })}>{name}</a>

<img alt={t({ id: "img.alt", message: plural(count, { one: "flag", other: "flags" }) })} src="..." />
```

## External Message Catalog[​](#external-message-catalog "Direct link to External Message Catalog")

Let's say our application has been internationalized and we want to send the messages to the translator.

FormatJS ships a CLI: `formatjs extract` collects the source messages into a single JSON file, and `formatjs compile` turns the translated files you get back into the format react-intl consumes, verifying the ICU syntax on the way. Formatters for Crowdin, Lokalise, Smartling and Transifex are built in. Keeping the translated files in step with the source, and noticing which translations are stale, happens outside the CLI, usually in the translation platform.

Lingui's [CLI](https://lingui.dev/ref/cli.md) closes that loop itself. `lingui extract` merges new messages into every locale's catalog, keeps the existing translations and marks removed messages as obsolete, so each PO file always mirrors the current source and stale entries are visible at a glance. It supports both the Babel and SWC ecosystems for extracting messages.

## Compiling Messages[​](#compiling-messages "Direct link to Compiling Messages")

Parsing and formatting ICU messages is the largest part of an i18n runtime. Lingui compiles each message at build time into a small structure that the runtime fills with values, so neither a parser nor a MessageFormat compiler ships to the browser. This is what `lingui compile` does by default, with nothing to opt into. Plural rules come from `Intl.PluralRules`, so there is no locale data to load by hand.

react-intl parses messages at runtime by default. The FormatJS CLI can pre-compile messages to an AST with `formatjs compile --ast`, and pairing that with the parser-free build of `@formatjs/icu-messageformat-parser` cuts the bundle by about 40% according to the FormatJS docs. The formatter itself stays in the bundle.

## Summary[​](#summary "Direct link to Summary")

Both libraries use ICU MessageFormat and have similar low-level APIs, so porting from one to the other is mostly mechanical. What differs is how much of the work the library takes off your hands.

**Lingui:**

* Macros generate the message syntax from JSX and template literals. Rich text is written as plain JSX, and there is no ICU string to hand-write or keep in step with the code.
* Extraction and compilation are part of the core toolchain, and the CLI keeps every locale's catalog in step with the source. Catalogs are PO files by default, with JSON, CSV and custom formats available.
* Catalogs are compiled ahead of time. Core and React bindings together stay around 4 kB gzipped.
* The same core serves vanilla JS, Node.js, React Native, Vue, SolidJS, Astro and Svelte.

**react-intl:**

* Is one of the longest-standing i18n libraries for React, used in many production websites.
* Is part of FormatJS, whose `@formatjs/intl` core also powers `vue-intl` and whose polyfills fill gaps in the `Intl` API.
* Has lots of resources available online.

Because the message syntax is shared, an existing react-intl codebase can move to Lingui without rewriting its messages. Each `FormattedMessage` becomes a `Trans` with the same message, and from then on the ICU string is generated for you.


---

# Catalog Formats

Catalog format (configured by the [`format`](https://lingui.dev/ref/conf.md#format) option) refers to the offline catalog file format. This format is never used in production, because the catalog is compiled into a JS module.

The reason for this build step is that the choice of catalog format depends on the individual internationalization workflow. On the other hand, the runtime catalog should be as simple as possible so that it can be parsed quickly without additional overhead.

## PO[​](#po "Direct link to PO")

PO files are translation files used by [gettext](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) internationalization system. This is the **recommended** and the **default** catalog format in Lingui.

[![Version](https://img.shields.io/npm/v/@lingui/format-po.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-po) [![Downloads](https://img.shields.io/npm/dw/@lingui/format-po.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-po)

The advantages of this format are:

* readable even for large messages
* supports comments for translators
* supports metadata (origin, flags)
* supports contexts
* standard format supported by many localization tools

### Installation[​](#po-installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/format-po
```

```
pnpm add --save-dev @lingui/format-po
```

### Usage[​](#po-usage "Direct link to Usage")

lingui.config.{js,ts}

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

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



export default defineConfig({

  // [...]

  format: formatter({ lineNumbers: false }),

});
```

### Configuration[​](#po-configuration "Direct link to Configuration")

PO formatter accepts the following options:

| Option                        | Type                            | Default | Description                                                                                                                                                                                                                                                         |
| ----------------------------- | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `origins`                     | boolean                         | `true`  | Include comments in the PO file that indicate where each message is used in the source code. This provides additional context during the translation                                                                                                                |
| `lineNumbers`                 | boolean                         | `true`  | Include line numbers in the origin comments. This makes it easier to locate messages in the source code                                                                                                                                                             |
| `printLinguiId`               | boolean                         | `false` | Add a `js-lingui-id: hash` comment to each message in the PO file. This ID is a hash generated by Lingui                                                                                                                                                            |
| `explicitIdAsDefault`         | boolean                         | `false` | Use the `msgid` as is for messages with explicit IDs. The formatter will add the `js-lingui-explicit-id` flag for such strings                                                                                                                                      |
| `customHeaderAttributes`      | `{[key: string]: string}`       | `{}`    | Allows adding custom key-value pairs to the PO file header                                                                                                                                                                                                          |
| `printPlaceholdersInComments` | boolean \| `{ limit?: number }` | `true`  | Print values for unnamed placeholders as comments for each message. This can give translators more context for better translations. By default, the first 3 placeholders are displayed                                                                              |
| `foldLength`                  | number                          | `0`     | Maximum line width before folding long strings. When a string exceeds this length, it will be split across multiple lines. Set to `0` to disable folding (strings will only break on actual newlines)                                                               |
| `compactMultiline`            | boolean                         | `true`  | When `true`, multiline strings start with content on the first line. When `false`, uses GNU gettext's traditional format with an empty first line. The compact format is recommended as it's compatible with translation platforms that may strip empty first lines |

### Examples[​](#po-examples "Direct link to Examples")

```
#: src/App.js:3

#. Comment for translators

msgid "messageId"

msgstr "Translated Message"



#: src/App.js:3

#, obsolete

msgid "obsoleteId"

msgstr "Obsolete Message"
```

Messages with context are exported in the following way:

```
#: src/Inbox.js:12

msgctxt "my context"

msgid "msg.inbox"

msgstr "Message Inbox"
```

Messages with plurals are exported in [ICU MessageFormat](https://lingui.dev/guides/message-format.md):

```
msgid "{count, plural, one {Message} other {Messages}}"

msgstr "{count, plural, one {Message} other {Messages}}"
```

Messages with placeholders:

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

are exported as:

```
#. placeholder {0}: user.name

msgid "Hello {0} {value}"

msgstr "Hello {0} {value}"
```

## PO with gettext Plurals[​](#po-gettext "Direct link to PO with gettext Plurals")

When using localization backends that don't understand the ICU plural syntax exported by the default `po` formatter, **po-gettext** can be used to read and write to PO files using gettext-native plurals.

[![Version](https://img.shields.io/npm/v/@lingui/format-po-gettext.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-po-gettext) [![Downloads](https://img.shields.io/npm/dw/@lingui/format-po-gettext.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-po-gettext)

### Installation[​](#po-gettext-installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/format-po-gettext
```

```
pnpm add --save-dev @lingui/format-po-gettext
```

### Usage[​](#po-gettext-usage "Direct link to Usage")

lingui.config.{js,ts}

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

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



export default defineConfig({

  // [...]

  format: formatter({ lineNumbers: false }),

});
```

### Configuration[​](#po-gettext-configuration "Direct link to Configuration")

The PO Gettext formatter accepts the following options:

| Option                 | Type    | Default        | Description                                                                                                                                                              |
| ---------------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `origins`              | boolean | `true`         | Include comments in the PO file that indicate where each message is used in the source code. This provides additional context during the translation                     |
| `lineNumbers`          | boolean | `true`         | Include line numbers in the origin comments. This makes it easier to locate messages in the source code                                                                  |
| `disableSelectWarning` | boolean | `false`        | Disable warnings about unsupported `Select` features encountered in catalogs. This can be useful if you're aware of the limitation and want to suppress related warnings |
| `customICUPrefix`      | string  | `"js-lingui:"` | Override the default prefix for ICU and plural comments in the final PO catalog                                                                                          |
| `mergePlurals`         | boolean | `false`        | Combine plural entries that have the same content but different variables into a single PO entry                                                                         |
| `foldLength`           | number  | `0`            | Maximum line width before folding long strings. When a string exceeds this length, it will be split across multiple lines. Set to `0` to disable folding                 |
| `compactMultiline`     | boolean | `true`         | When `true`, multiline strings start with content on the first line. When `false`, uses GNU gettext's traditional format with an empty first line                        |

### Examples[​](#po-gettext-examples "Direct link to Examples")

With this format, plural messages are exported in the following ways, depending on whether an explicit ID is set:

* Message **with custom ID "my\_message"** that is pluralized on property "*someCount*".

  ```
  #. js-lingui:pluralize_on=someCount

  msgid "my_message"

  msgid_plural "my_message_plural"

  msgstr[0] "Singular case"

  msgstr[1] "Case number {someCount}"
  ```

  Note that `msgid_plural` was created by appending a `_plural` suffix.

* Message **without custom ID** that is pluralized on property "*anotherCount*".

  To allow matching this PO item to the appropriate catalog entry when deserializing, the original ICU message is also stored in the generated comment.

  ```
  #. js-lingui:icu=%7BanotherCount%2C+plural%2C+one+%7BSingular+case%7D+other+%7BCase+number+%7BanotherCount%7D%7D%7D&pluralize_on=anotherCount

  msgid "Singular case"

  msgid_plural "Case number {anotherCount}"

  msgstr[0] "Singular case"

  msgstr[1] "Case number {anotherCount}"
  ```

  Note how `msgid` and `msgid_plural` were extracted from the original message.

* Message **with a custom comment prefix**.

  Some TMS might modify the ICU comment by attempting to split lines to be 80 characters or less, or have trouble reading lingui comments because of the `js-lingui:` prefix. To change the prefix, set `customICUPrefix` to modify the prefix for ICU comments.

  ```
  # with default prefix

  #. js-

  #. lingui:icu=%7BanotherCount%2C+plural%2C+one+%7BSingular+case%7D+other+%7BCase+number+%7BanotherCount%7D%7D%7D&pluralize_on=anotherCount



  # customICUPrefix = jsi18n:

  #. jsi18n:icu=%7BanotherCount%2C+plural%2C+one+%7BSingular+case%7D+other+%7BCase+number+%7BanotherCount%7D%7D%7D&pluralize_on=anotherCount
  ```

#### Duplicate Plurals[​](#duplicate-plurals "Direct link to Duplicate Plurals")

When two calls to `plural` or `<Plural />` are made with identical strings, but pluralize on different variables, they will create separate PO entries. However, `msgid` will be the same. Some TMS might not allow duplicate `msgid`, even with different comments, and should use `mergePlurals` option to merge these entries into a single PO entry during extraction. During compilation, it will be re-expanded to multiple units.

```
plural(count, {

  one: "one book",

  other: "many books",

});

plural(anotherCount, {

  one: "one book",

  other: "many books",

});
```

Without `mergePlurals`:

```
#. js-lingui:icu={count, plural, one {one book} other {many books}}&pluralize_on=count

msgid "one book"

msgid_plural "many books"

msgstr[0] "one book"

msgstr[1] "many books"



#. js-lingui:icu={anotherCount, plural, one {one book} other {many books}}&pluralize_on=anotherCount

msgid "one book"

msgid_plural "many books"

msgstr[0] "one book"

msgstr[1] "many books"
```

With `mergePlurals`:

```
#. js-lingui:icu={$var, plural, one {one book} other {many books}}&pluralize_on=count,anotherCount

msgid "one book"

msgid_plural "many books"

msgstr[0] "one book"

msgstr[1] "many books"
```

### Limitations[​](#po-gettext-limitations "Direct link to Limitations")

This format comes with several caveats and should only be used when using ICU plurals in PO files is not an option:

* Nested/multiple plurals in a message as shown in [`plural`](https://lingui.dev/ref/macro.md#plural) are not supported because they cannot be expressed with gettext plurals. Messages containing nested/multiple formats will not be output correctly.
* A [`Plural`](https://lingui.dev/ref/macro.md#plural-1) nested inside a [`Trans`](https://lingui.dev/ref/macro.md#trans) (`<Trans>You have <Plural … /></Trans>`) is exported as a single ICU message rather than as `msgid`/`msgid_plural`. Keep the plural as the top-level translation unit; the [`no-plural-inside-trans`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-plural-inside-trans.md) ESLint rule catches this.
* The [`select`](https://lingui.dev/ref/macro.md#select) and [`selectOrdinal`](https://lingui.dev/ref/macro.md#selectordinal) cannot be expressed with gettext plurals, but the original ICU format is still stored in the `msgid`/`msgstr` properties. To disable the warning that this may not be the expected behavior, add `{ disableSelectWarning: true }` to the [`format`](https://lingui.dev/ref/conf.md#format) options.
* Source/development languages with more than two plurals could experience difficulties when no custom IDs are used, as gettext cannot have more than two plurals cases identifying an item (`msgid` and `msgid_plural`).
* Gettext doesn't support plurals for negative and fractional numbers even though some languages have special rules for these cases.

## JSON[​](#json "Direct link to JSON")

This format is used to store messages in a JSON file. There are two types of JSON format: [minimal](#minimal-style) and [lingui](#lingui-style).

[![Version](https://img.shields.io/npm/v/@lingui/format-json.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-json) [![Downloads](https://img.shields.io/npm/dw/@lingui/format-json.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-json)

### Installation[​](#json-installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/format-json
```

```
pnpm add --save-dev @lingui/format-json
```

### Usage[​](#json-usage "Direct link to Usage")

lingui.config.{js,ts}

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

import { formatter } from "@lingui/format-json";



export default defineConfig({

  // [...]

  format: formatter({ style: "lingui" }),

});
```

### Configuration[​](#json-configuration "Direct link to Configuration")

JSON formatter accepts the following options:

| Option        | Type                      | Default    | Description                                                                                                                                       |
| ------------- | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `style`       | `"lingui"` \| `"minimal"` | `"lingui"` | Specify the output style of the JSON file. `lingui` includes full Lingui-specific metadata, while `minimal` may output a more compact format      |
| `origins`     | boolean                   | `true`     | Include information in the JSON file about where each message is used in the source code. This provides additional context during the translation |
| `lineNumbers` | boolean                   | `true`     | Include line numbers in the origin comments. This makes it easier to locate messages in the source code                                           |
| `indentation` | number                    | `2`        | Set the number of spaces to use for indentation in the output JSON file. This affects the readability of the file when opened in a text editor    |

### Examples[​](#json-examples "Direct link to Examples")

#### Minimal style[​](#minimal-style "Direct link to Minimal style")

A simple JSON file where each key is a message ID and the value is the translation. The JSON is flat, and there's no reason to use nested keys. The usual motivation behind nested JSON is to save file space, but this file format is only used offline.

The downside of this format is that all metadata about the message is lost. This includes the default message, the origin of the message, and any message flags (obsolete, fuzzy, etc.).

```
{

  "messageId": "translation"

}
```

#### Lingui style[​](#lingui-style "Direct link to Lingui style")

This file format simply outputs all internal data in JSON format. It's the original file format used by Lingui before support for other catalog formats was added. It might be useful for tools build on top of Lingui CLI which needs to further process catalog data.

```
{

  "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

  }

}
```

## CSV[​](#csv "Direct link to CSV")

The CSV format is a simple format that can be used to import and export messages from spreadsheets or other tools that support CSV files. It has two columns: message ID and message (source or translation).

[![Version](https://img.shields.io/npm/v/@lingui/format-csv.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-csv) [![Downloads](https://img.shields.io/npm/dw/@lingui/format-csv.svg?cacheSeconds=86400)](https://www.npmjs.com/package/@lingui/format-csv)

### Installation[​](#csv-installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/format-csv
```

```
pnpm add --save-dev @lingui/format-csv
```

### Usage[​](#csv-usage "Direct link to Usage")

lingui.config.{js,ts}

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

import { formatter } from "@lingui/format-csv";



export default defineConfig({

  // [...]

  format: formatter(),

});
```

This formatter has no configurable options.

### Examples[​](#csv-examples "Direct link to Examples")

```
messageId,Message

msg.common,String for translation
```

## See Also[​](#see-also "Direct link to See Also")

* [Custom Formatter](https://lingui.dev/guides/custom-formatter.md)


---

# Lingui CLI

The `@lingui/cli` tool provides the `lingui` command which allows you to extract messages from source files into message catalogs, check them, and compile these catalogs for production use.

## Installation[​](#installation "Direct link to Installation")

1. Install `@lingui/cli` as a development dependency:

   * npm
   * Yarn
   * pnpm

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

   ```
   yarn add --dev @lingui/cli
   ```

   ```
   pnpm add --save-dev @lingui/cli
   ```

2. Add the following scripts to your `package.json`:

   package.json

   ```
   {

     "scripts": {

       "extract": "lingui extract",

       "compile": "lingui compile"

     }

   }
   ```

tip

If you use TypeScript, you can add the `--typescript` flag to the `compile` script to produce compiled message catalogs with TypeScript types:

package.json

```
{

  "scripts": {

    "compile": "lingui compile --typescript"

  }

}
```

## Global Options[​](#global-options "Direct link to Global Options")

### `--config <config>`[​](#--config-config "Direct link to --config-config")

Path to the configuration file. If not set, the default file is loaded as described in the [Configuration](https://lingui.dev/ref/conf.md) reference.

## Commands[​](#commands "Direct link to Commands")

### `extract`[​](#extract "Direct link to extract")

```
lingui extract [files...]

        [--clean]

        [--overwrite]

        [--format <format>]

        [--locale <locale, [...]>]

        [--convert-from <format>]

        [--verbose]

        [--watch [--debounce <delay>]]

        [--workers <n>]
```

The `extract` command scans source files to locate and extract messages, generating separate message catalogs for each language.

This process involves:

1. Extracting messages from files based on the `include` and `exclude` settings in the [`catalogs`](https://lingui.dev/ref/conf.md#catalogs) section of the configuration file.
2. Merging the newly extracted messages with any existing message catalogs.
3. Updating and saving the message catalogs.
4. Printing extraction statistics for each language, including the total number of messages and any missing translations.

tip

Refer to the [Message Extraction](https://lingui.dev/guides/message-extraction.md) guide to learn more about this process and the options available.

#### `files`[​](#extract-files "Direct link to extract-files")

Filter source paths to extract messages only from specific files. For example:

```
lingui extract src/components
```

This command extracts messages from files within the `src/components/**/*` path. You can also pass multiple paths for extraction.

This feature is useful when you want to extract messages from files that are staged for commit. For example, you can use husky to automatically extract messages from staged files before committing:

package.json

```
{

  "husky": {

    "hooks": {

      "pre-commit": "lingui extract $(git diff --name-only --staged)"

    }

  }

}
```

#### `--clean`[​](#extract-clean "Direct link to extract-clean")

By default, the extract command merges messages extracted from source files with existing message catalogs, ensuring that translated messages are preserved and not accidentally lost.

However, over time, some messages may be removed from the source code. You can use the following option to clean up your message catalogs and remove obsolete messages.

#### `--overwrite`[​](#extract-overwrite "Direct link to extract-overwrite")

Update translations for [`sourceLocale`](https://lingui.dev/ref/conf.md#sourcelocale) from source.

#### `--format <format>`[​](#extract-format "Direct link to extract-format")

Extract message catalogs to the specified file format (see the [`format`](https://lingui.dev/ref/conf.md#format) option for more details).

#### `--locale <locale, [...]>`[​](#extract-locale "Direct link to extract-locale")

Extract data for the specified locales only.

#### `--convert-from <format>`[​](#extract-convert-from "Direct link to extract-convert-from")

Convert message catalogs from the previous format (see the [`format`](https://lingui.dev/ref/conf.md#format) option for more details).

#### `--verbose`[​](#extract-verbose "Direct link to extract-verbose")

Print additional information.

#### `--watch`[​](#extract-watch "Direct link to extract-watch")

Enable watch mode to monitor changes in files located in the paths specified in the configuration file or in the command itself. Note that this feature is intended for development use only, as it does not remove obsolete translations.

#### `--debounce <delay>`[​](#extract-debounce "Direct link to extract-debounce")

Delay the extraction by `<delay>` milliseconds, bundling multiple file changes together.

#### `--workers`[​](#extract-workers "Direct link to extract-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

Worker threads can significantly improve performance on large projects. However, on small projects they may provide little benefit or even be slightly slower due to thread startup overhead.

A larger worker pool also increases memory usage. Adjust this value for your project to achieve the best performance.

### `extract-template`[​](#extract-template "Direct link to extract-template")

```
lingui extract-template [--verbose]
```

This command extracts messages from your source files and generates a `.pot` template file. Any artifacts created by this command can be safely ignored in version control.

If your message catalogs are not synchronized with the source and some messages are missing, the application will fallback to the template file. Running this command before building the application is recommended to ensure all messages are accounted for.

#### `--verbose`[​](#extract-template-verbose "Direct link to extract-template-verbose")

Print additional information.

### `compile`[​](#compile "Direct link to compile")

```
lingui compile

    [--strict]

    [--format <format>]

    [--verbose]

    [--typescript]

    [--namespace <namespace>]

    [--watch [--debounce <delay>]]

    [--workers <n>]

    [--output-prefix <prefix>]
```

Once you have all the catalogs ready and translated, you can use this command to compile all the catalogs into minified JS/TS files. It compiles message catalogs located in the [`path`](https://lingui.dev/ref/conf.md#catalogs) directory and generates minified JavaScript files. The resulting file is a string that is parsed into a plain JS object using `JSON.parse`.

The output looks like this:

```
export const messages = JSON.parse(`{

// object with keys (translation ids) and values (translations)

}`);
```

Messages added to the compiled file are collected in a specific order:

1. Translated messages from the specified locale.
2. Translated messages from the fallback locale for the specified locale.
3. Translated message from default fallback locale.
4. Message key.

It is also possible to merge the translated catalogs into a single file per locale by specifying [`catalogsMergePath`](https://lingui.dev/ref/conf.md#catalogsmergepath) in the configuration.

tip

The compiled files can be safely ignored by your version control system, since these files must be created each time you deploy to production. We recommend you to create the compiled catalogs in CI as part of your deployment process. Always remember to **use compiled catalogs** in deployments.

.gitignore

```
your_locale_folder/**/*.js
```

#### `--overwrite`[​](#compile-overwrite "Direct link to compile-overwrite")

Overwrite source locale translations from source.

#### `--strict`[​](#compile-strict "Direct link to compile-strict")

Fail if the compiled catalog still has missing translations after `fallbackLocales` are applied, or if message compilation produces errors.

This preserves the default validation behavior used by Lingui 6. The compiled output uses the normal fallback resolution behavior regardless of strict mode, although catalogs for locales that fail strict validation may not be emitted.

#### `--format <format>`[​](#compile-format "Direct link to compile-format")

Format of message catalogs (see the [`format`](https://lingui.dev/ref/conf.md#format) option for more details).

#### `--verbose`[​](#compile-verbose "Direct link to compile-verbose")

Print additional information.

#### `--namespace`[​](#compile-namespace "Direct link to compile-namespace")

Specify the namespace for compiled message catalogs (see also [`compileNamespace`](https://lingui.dev/ref/conf.md#compilenamespace) for global configuration).

#### `--typescript`[​](#compile-typescript "Direct link to compile-typescript")

Is the same as using [`compileNamespace`](https://lingui.dev/ref/conf.md#compilenamespace) with the value "ts". Generates a `{compiledFile}.ts` file and the exported object is typed using TS.

#### `--watch`[​](#compile-watch "Direct link to compile-watch")

Watch mode. Watches only for changes in locale files in your defined locale catalogs. For example, `locales\en\messages.po`.

#### `--debounce <delay>`[​](#compile-debounce "Direct link to compile-debounce")

Delays compilation by `<delay>` milliseconds to avoid multiple compilations for subsequent file changes.

#### `--workers`[​](#compile-workers "Direct link to compile-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

Worker threads can significantly improve performance on large projects. However, on small projects they may provide little benefit or even be slightly slower due to thread startup overhead.

A larger worker pool also increases memory usage. Adjust this value for your project to achieve the best performance.

#### `--output-prefix <prefix>`[​](#compile-output-prefix "Direct link to compile-output-prefix")

Adds a custom string to the beginning of compiled message catalogs (a header/prefix). By default, Lingui adds `/*eslint-disable*/` to prevent linters from reporting issues in generated files.

Use this option for other tools that rely on header directives (e.g., different linters, coverage tools, or formatters). Provide the full prefix exactly as it should appear in the output.

**Default value:** `/*eslint-disable*/`

**Examples:**

```
# For Oxlint

lingui compile --output-prefix "/*oxlint-disable*/"



# For Biome

lingui compile --output-prefix "/*biome-ignore lint: auto-generated*/"



# For no prefix at all

lingui compile --output-prefix ""
```

The generated file header will look like:

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

### `check`[​](#check "Direct link to check")

```
lingui check <command>
```

The `check` command is a namespace for validation subcommands. Running `lingui check` without a subcommand prints help and exits without running any validation.

These subcommands are useful in CI when you want to fail fast on stale catalogs or missing translations but do not need compilation artifacts yet.

#### `sync`[​](#sync "Direct link to sync")

```
lingui check sync

    [--locale <locale, [...]>]

    [--clean]

    [--overwrite]

    [--verbose]

    [--workers <n>]
```

Checks whether locale catalogs are synchronized with the current source code. It fails if the expected catalog differs from the existing catalog.

This validation checks locale catalogs only. It does not validate `.pot` / template freshness.

#### `missing`[​](#missing "Direct link to missing")

```
lingui check missing

    [--locale <locale, [...]>]

    [--mode <resolved|catalog>]

    [--verbose]

    [--workers <n>]
```

Checks whether locale catalogs have missing translations. By default, this validation uses `resolved` mode, which matches `lingui compile --strict`: translations are considered missing only if they are still missing after `fallbackLocales` are applied.

Use `--mode catalog` to fail when the target locale catalog itself has missing translations before `fallbackLocales` are applied. This command performs validation without compiling catalogs.

#### `sync --locale <locale, [...]>`[​](#check-sync-locale "Direct link to check-sync-locale")

Only check the specified locales when running `lingui check sync`.

#### `sync --clean`[​](#check-sync-clean "Direct link to check-sync-clean")

Before comparing catalogs, remove obsolete messages from the expected catalog. Existing obsolete messages are still reported as out of sync.

#### `sync --overwrite`[​](#check-sync-overwrite "Direct link to check-sync-overwrite")

When running the `sync` validation, mirror `lingui extract --overwrite`. Source locale translations are expected to be overwritten from source messages.

#### `sync --verbose`[​](#check-sync-verbose "Direct link to check-sync-verbose")

Print detailed findings for each failing `sync` validation.

#### `sync --workers`[​](#check-sync-workers "Direct link to check-sync-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

#### `missing --locale <locale, [...]>`[​](#check-missing-locale "Direct link to check-missing-locale")

Only check the specified locales when running `lingui check missing`.

#### `missing --mode <resolved|catalog>`[​](#check-missing-mode "Direct link to check-missing-mode")

Controls how missing translations are detected when running `lingui check missing`.

* `resolved` (default): fail only if a translation is still missing after `fallbackLocales` are applied.
* `catalog`: fail if the target locale catalog itself has missing translations before `fallbackLocales` are applied.

#### `missing --verbose`[​](#check-missing-verbose "Direct link to check-missing-verbose")

Print detailed findings for each failing `missing` validation.

#### `missing --workers`[​](#check-missing-workers "Direct link to check-missing-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

## Configuring the Source Locale[​](#configuring-the-source-locale "Direct link to Configuring the Source Locale")

One limitation of checking for missing translations is that the English message catalog typically does not require translations since our source code is in English. This issue can be resolved by configuring the [`sourceLocale`](https://lingui.dev/ref/conf.md#sourcelocale) in the configuration file.

## Compiling Catalogs in CI[​](#compiling-catalogs-in-ci "Direct link to Compiling Catalogs in CI")

If you're using CI, it's a good idea to add the `compile` command to your build process. Alternatively, you can also use a [Webpack loader](https://lingui.dev/ref/loader.md), [Vite plugin](https://lingui.dev/ref/vite-plugin.md) or [Metro transformer](https://lingui.dev/ref/metro-transformer.md).

Depending on your localization setup, you might also want to run the `extract` command in CI and upload the extracted messages to a [translation service](https://lingui.dev/tools/introduction.md).

## See Also[​](#see-also "Direct link to See Also")

* [Lingui Configuration](https://lingui.dev/ref/conf.md)
* [Message Extraction](https://lingui.dev/guides/message-extraction.md)
* [Catalog Formats](https://lingui.dev/ref/catalog-formats.md)
* [Custom Extractor](https://lingui.dev/guides/custom-extractor.md)


---

# Configuration

The following reference covers all supported configuration options in Lingui. To learn more about configuring Lingui, read the [Installation and Setup](https://lingui.dev/installation.md) guide.

By default, Lingui looks for the configuration in the following locations:

* `lingui.config.js` or `lingui.config.ts` file exporting a configuration object (recommended).

You can also define the environment variable `LINGUI_CONFIG` with the path to your config file.

In the case of TypeScript-based config you can use ESM format and *export default*.

## catalogs[​](#catalogs "Direct link to catalogs")

Default value:

```
[

  {

    path: "<rootDir>/locale/{locale}/messages",

    include: ["<rootDir>"],

    exclude: ["**/node_modules/**"],

  },

];
```

The `catalogs` configuration defines the location of message catalogs and specifies which files are included when the [`extract`](https://lingui.dev/ref/cli.md#extract) command scans for messages.

* `path`: the directory where the message catalogs are located. It should not end with a slash and must not include a file extension, which depends on the [`format`](#format) configuration. The `{locale}` token will be replaced by the catalog's locale.
* `include` and `exclude`: these patterns specify which files to include or exclude during the extraction process. They are passed to [minimatch](https://github.com/isaacs/minimatch) for pattern matching.
* [`<rootDir>`](#rootdir): represents the root directory of the project. It is replaced with the actual root directory when the configuration is loaded. By default, [`<rootDir>`](#rootdir) represents the configuration file's location.

The `path`, `include`, and `exclude` patterns are interpreted relative to the current process CWD (current working directory).

The `{name}` token in the `path` will be replaced with the catalog name. Be sure to include the `{name}` pattern in the source path as well, as it acts like a `*` glob pattern:

```
{

  "catalogs": [

    {

      "path": "<rootDir>/components/{name}/locale/{locale}",

      "include": ["<rootDir>/components/{name}/"]

    }

  ]

}
```

#### Examples[​](#examples "Direct link to Examples")

Let's assume we use `locales: ["en", "cs"]` and `format: "po"` in all examples.

#### All catalogs in one directory[​](#all-catalogs-in-one-directory "Direct link to All catalogs in one directory")

```
{

  "catalogs": [

    {

      "path": "locales/{locale}"

    }

  ]

}
```

```
locales/

├── en.po

└── cs.po
```

#### Catalogs in separate directories[​](#catalogs-in-separate-directories "Direct link to Catalogs in separate directories")

```
{

  catalogs: [

    {

      path: "locales/{locale}/messages",

    },

  ];

}
```

```
locales

├── en/

│   └── messages.po

└── cs/

    └── messages.po
```

#### Separate catalogs per component, placed inside component directory[​](#separate-catalogs-per-component-placed-inside-component-directory "Direct link to Separate catalogs per component, placed inside component directory")

```
{

  "catalogs": [

    {

      "path": "components/{name}/locale/{locale}",

      "include": ["components/{name}/"]

    }

  ]

}
```

```
components/

├── RegistrationForm/

│   ├── locale/

│   │  ├── en.po

│   │  └── cs.po

│   ├── RegistrationForm.test.js

│   └── RegistrationForm.js

└── LoginForm/

    ├── locale/

    │  ├── en.po

    │  └── cs.po

    ├── LoginForm.test.js

    └── LoginForm.js
```

#### Separate catalogs per component, placed inside shared directory[​](#separate-catalogs-per-component-placed-inside-shared-directory "Direct link to Separate catalogs per component, placed inside shared directory")

```
{

  "catalogs": [

    {

      "path": "locale/{locale}/{name}",

      "include": ["components/{name}/"]

    }

  ]

}
```

```
.

├── locale/

│   ├── en/

│   │   ├── RegistrationForm.po

│   │   └── LoginForm.po

│   └── cs/

│       ├── RegistrationForm.po

│       └── LoginForm.po

└── components/

    ├── RegistrationForm/

    │   ├── RegistrationForm.test.js

    │   └── RegistrationForm.js

    └── LoginForm/

        ├── LoginForm.test.js

        └── LoginForm.js
```

## locales[​](#locales "Direct link to locales")

Default value: `[]`

The locale tags used in the project. The [`extract`](https://lingui.dev/ref/cli.md#extract) and [`compile`](https://lingui.dev/ref/cli.md#compile) commands write a catalog for each locale specified. Each locale should be a valid [BCP-47 code](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html):

```
{

  "locales": ["en", "cs"]

}
```

## fallbackLocales[​](#fallbacklocales "Direct link to fallbackLocales")

Default value: `{}`

Translations from `fallbackLocales` are used if the translation for the given locale is missing. It uses [CLDR Parent Locales](https://github.com/unicode-cldr/cldr-core/blob/master/supplemental/parentLocales.json) by default, unless you override it with a `false` to use the default message or message ID instead:

```
{

  "fallbackLocales": false

}
```

The `fallbackLocales` object allows to configure fallback locales for each locale instance:

```
{

  "fallbackLocales": {

    "en-US": ["en-GB", "en"],

    "es-MX": "es"

  }

}
```

In this example, if any translation isn't found on `en-US`, then it will search on `en-GB`, after that if not found we'll search in `en`.

it's also possible to configure a `default` fallback locale for all locales:

```
{

  "fallbackLocales": {

    "en-US": ["en-GB", "en"],

    "es-MX": "es",

    "default": "en"

  }

}
```

## sourceLocale[​](#sourcelocale "Direct link to sourceLocale")

Default value: `""`

`sourceLocale` specifies the default language of message IDs in your source files. The catalog for `sourceLocale` doesn't need actual translations since message IDs are used as-is by default. However, you can still override any message ID by providing a custom translation.

The main difference between `sourceLocale` and [`fallbackLocales`](#fallbacklocales) is their purpose: `sourceLocale` defines the language used for message IDs, while `fallbackLocales` provides alternative translations when specific messages are missing for a particular locale.

## pseudoLocale[​](#pseudolocale "Direct link to pseudoLocale")

Default value: `""`

Locale used for pseudolocalization. For example, when you set `pseudoLocale: "en"`, all messages in the `en` catalog will be pseudo-localized. The locale must be included in the `locales` config.

It can be provided as a string (deprecated), an object to additionally configure the underlying [`pseudolocale`](https://github.com/MartinCerny-awin/pseudolocale) library, or an array of objects to define multiple pseudolocales with different parameters. The token delimiter is managed internally by Lingui (to keep HTML tags, ICU macros and variables intact) and therefore cannot be configured.

caution

The string form (`pseudoLocale: "pseudo"`) is deprecated and will be removed in a future major release. Use the object form (`pseudoLocale: { locale: "pseudo" }`) or an array of objects instead.

| Option            | Type      | Default     | Description                                                                                         |
| ----------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `locale`          | `string`  | —           | Locale used for pseudolocalization (required in the object form)                                    |
| `prepend`         | `string`  | `""`        | String prepended to the beginning of every pseudo-localized message                                 |
| `append`          | `string`  | `""`        | String appended to the end of every pseudo-localized message                                        |
| `extend`          | `number`  | `0`         | Extends the width of the string by the given percentage (e.g. `0.3` adds 30%)                       |
| `extendCharacter` | `string`  | `" "`       | Character used to pad messages when `extend` is set                                                 |
| `override`        | `string`  | `undefined` | Replaces every (non-token) character with the given one. Handy to quickly spot untranslated strings |
| `rightToLeft`     | `boolean` | `false`     | Emulates right-to-left languages by inserting Unicode RTL override marks                            |

lingui.config.{js,ts}

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



// Simple form

export default defineConfig({

  locales: ["en", "pseudo"],

  sourceLocale: "en",

  pseudoLocale: "pseudo",

  catalogs: [],

});



// Extended form

export default defineConfig({

  locales: ["en", "pseudo"],

  sourceLocale: "en",

  pseudoLocale: {

    locale: "pseudo",

    prepend: "⟦ ",

    append: " ⟧",

    extend: 0.4,

    extendCharacter: ".",

  },

  catalogs: [],

});



// Multiple pseudolocales

export default defineConfig({

  locales: ["en", "pseudo-en", "pseudo-ar"],

  sourceLocale: "en",

  pseudoLocale: [

    { locale: "pseudo-en", prepend: "⟦ ", append: " ⟧", extend: 0.4 },

    { locale: "pseudo-ar", rightToLeft: true },

  ],

  catalogs: [],

});
```

Read more about [Pseudolocalization](https://lingui.dev/guides/pseudolocalization.md).

## catalogsMergePath[​](#catalogsmergepath "Direct link to catalogsMergePath")

Default value: `""`

Define the path where translated catalogs are merged into a single file per locale during the [`compile`](https://lingui.dev/ref/cli.md#compile) process.

#### Example[​](#example "Direct link to Example")

Let's assume we have [separate catalogs per component, placed inside shared directory](#separate-catalogs-per-component-placed-inside-shared-directory).

Using the `catalogsMergePath`, separate catalogs can be merged into a single file:

```
{

  "catalogs": [

    {

      "path": "/locale/{locale}/{name}",

      "include": ["components/{name}/"]

    }

  ],

+ "catalogsMergePath": "locales/{locale}"

}
```

```
.

  ├── 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
```

## compileNamespace[​](#compilenamespace "Direct link to compileNamespace")

Default value: `cjs`

Specify namespace for exporting compiled messages. See [`compile`](https://lingui.dev/ref/cli.md#compile) command.

#### cjs[​](#cjs "Direct link to cjs")

Use CommonJS exports:

```
/* eslint-disable */module.exports={messages: {"..."}}
```

#### es[​](#es "Direct link to es")

Use ES6 named export:

```
/* eslint-disable */export const messages = {"..."}
```

#### ts[​](#ts "Direct link to ts")

Use ES6 named export + `.ts` file with an additional `{compiledFile}.d.ts` file:

```
/* eslint-disable */export const messages = {"..."}
```

```
import { Messages } from "@lingui/core";

declare const messages: Messages;

export { messages };
```

#### json[​](#json "Direct link to json")

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

#### (window|global).(.\*)[​](#windowglobal "Direct link to (window|global).(.*)")

Assign compiled messages to `window` or `global` object. Specify an identifier after `window` or `global` to which the catalog is assigned, e.g. `window.i18n`.

For example, setting [`compileNamespace`](#compilenamespace) to `window.i18n` creates file similar to this:

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

## extractorParserOptions[​](#extractorparseroptions "Direct link to extractorParserOptions")

note

This option is deprecated. If you want to change parser options, pass it directly to extractor implementation

```
import { createBabelExtractor } from "@lingui/cli/api/extractors/babel";



export default {

  // [...]

  extractors: [createBabelExtractor({ parserOptions: { tsExperimentalDecorators: true } })],

};
```

Specify additional options used to parse source files when extracting messages.

```
{

  "extractorParserOptions": {

    "tsExperimentalDecorators": false,

    "flow": false

  }

}
```

#### tsExperimentalDecorators[​](#tsexperimentaldecorators "Direct link to tsExperimentalDecorators")

Default value: `false`

By default, standard decorators (Stage3) are applied to TS files. Enable this if you want to use TypeScript's experimental decorators.

#### flow[​](#flow "Direct link to flow")

Default value: `false`

Lingui does not ship with [Flow](https://flow.org/) typing. However, you can use Lingui in projects written in Flow. Enable this option to tell the extractor that your sources use Flow syntax.

## compilerBabelOptions[​](#compilerbabeloptions "Direct link to compilerBabelOptions")

Default value:

```
{

  "minified": true,

  "jsescOption": {

    "minimal": true

  }

}
```

Specify extra babel options used to generate files when messages are being compiled. We use internally `@babel/generator` that accepts some configuration for generating code with/out ASCII characters. These are all the options available: [jsesc](https://github.com/mathiasbynens/jsesc).

```
{

  "compilerBabelOptions": {

    "jsescOption": {

      "minimal": false

    }

  }

}
```

This example configuration will compile with escaped ASCII characters ([jsesc#minimal](https://github.com/mathiasbynens/jsesc#minimal)).

## format[​](#format "Direct link to format")

Default value: `po`

Message catalog format. The `po` formatter is used by default. Other formatters are available as separate packages.

lingui.config.{js,ts}

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

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



export default defineConfig({

  // [...]

  format: formatter({ lineNumbers: false }),

});
```

Read more about available formatters in [Catalog Formats](https://lingui.dev/ref/catalog-formats.md) or create your own [Custom Formatter](https://lingui.dev/guides/custom-formatter.md).

## orderBy[​](#orderby "Direct link to orderBy")

Default value: `message`

Order of messages in catalog:

#### message[​](#message "Direct link to message")

Sort by source message.

#### messageId[​](#messageid "Direct link to messageId")

Sort by the message ID, `js-lingui-id` will be used if no custom id provided.

#### origin[​](#origin "Direct link to origin")

Sort by message origin (e.g. `App.js:3`)

#### Custom Function[​](#custom-function "Direct link to Custom Function")

You can provide custom sort function:

```
export default defineConfig({

  // [...]

  orderBy: (a, b) => {

    /* `a` and `b` has a shape

     * {

     *   messageId: string

     *   entry: ExtractedMessageType

     * }

     */

    const aIsGlobal = a.messageId.startsWith("global.");

    const bIsGlobal = b.messageId.startsWith("global.");



    // Put `global.*` entries first

    if (aIsGlobal && !bIsGlobal) return -1;

    if (!aIsGlobal && bIsGlobal) return 1;



    // Otherwise, sort alphabetically

    return a.messageId.localeCompare(b.messageId);

  },

});
```

## rootDir[​](#rootdir "Direct link to rootDir")

Default: The root of the directory containing your Lingui configuration file or the `package.json`.

This is the directory where the Lingui CLI scans for messages in your source files during the extraction process.

Note that using `<rootDir>` as a string token in any other path-based config settings will refer back to this value.

## runtimeConfigModule[​](#runtimeconfigmodule "Direct link to runtimeConfigModule")

Default value: `["@lingui/core", "i18n"]`

This setting specifies the module path for the exported `i18n` object. The first value in the array is the module path, and the second is the name of the import. This configuration is essential for [macros](https://lingui.dev/ref/macro.md) that need to reference the global `i18n` object.

You only need to set this value if you use custom object created using [`setupI18n`](https://lingui.dev/ref/core.md#setupi18n):

For example, if you have a custom module that exports the `i18n` object:

```
import { i18n } from "./custom-i18n-config";
```

```
{

  "runtimeConfigModule": ["./custom-i18n-config", "i18n"]

}
```

You may use a different named export:

```
import { myI18n } from "./custom-i18n-config";
```

```
{

  "runtimeConfigModule": ["./custom-i18n-config", "myI18n"]

}
```

In more advanced scenarios, you may need to change the module from which the [`Trans`](https://lingui.dev/ref/macro.md#trans) or [`useLingui`](https://lingui.dev/ref/macro.md#uselingui) macros are imported:

```
import { Trans, useLingui } from "./custom-config";
```

```
{

  "runtimeConfigModule": {

    "Trans": ["./custom-config", "Trans"],

    "useLingui": ["./custom-config", "useLingui"]

  }

}
```

## extractors[​](#extractors "Direct link to extractors")

Default value: `[babel]`

Extractors it's the way to customize which extractor you want for your codebase.

```
{

   "extractors": [

      myCustomExtractor,

   ]

}
```

See the [Custom Extractor](https://lingui.dev/guides/custom-extractor.md) guide for instructions on creating your own extractor, or use the [native extractor](https://lingui.dev/guides/custom-extractor.md#native-extractor) to extract without Babel.

## macro.corePackage[​](#macrocorepackage "Direct link to macro.corePackage")

Default value: `["@lingui/macro", "@lingui/core/macro"]`

Allows customizing the Core Macro package name that the Lingui macro detects.

```
// lingui.config

{

  macro: {

    corePackage: ["@lingui/myMacro"],

  }

}



// app.tsx

import { msg } from "@lingui/myMacro";



msg`Hello`; // <-- would be correctly picked up by macro
```

This setting mostly useful for external framework integrations.

## macro.jsxPackage[​](#macrojsxpackage "Direct link to macro.jsxPackage")

Default value: `["@lingui/macro", "@lingui/react/macro"]`

Allows customizing the JSX Macro package name that the Lingui macro detects.

```
// lingui.config

{

  macro: {

    jsxPackage: ["@lingui/myMacro"],

  }

}



// app.tsx

import { Trans } from "@lingui/myMacro";



<Trans>Hello</Trans>; // <-- would be correctly picked up by macro
```

This setting mostly useful for external framework integrations.

## macro.jsxPlaceholderAttribute[​](#macrojsxplaceholderattribute "Direct link to macro.jsxPlaceholderAttribute")

Default value: `undefined`

The JSX attribute name used to assign explicit placeholder names to JSX elements inside `<Trans>`. When set, the macro reads this attribute from JSX elements to use as the placeholder name in the message string, and strips the attribute from the output.

```
// lingui.config

{

  macro: {

    jsxPlaceholderAttribute: "_t",

  }

}



// source

<Trans>

  Click <a _t="link" href="/">here</a>

</Trans>;



// extracted message: "Click <link>here</link>"
```

Without this option, JSX elements are assigned auto-generated numeric placeholders (e.g. `<0>here</0>`), which are less readable for translators and may cause issues if the element order changes.

TypeScript Usage

In React/TypeScript projects, you need to declare the custom attribute so that TypeScript doesn't report an error. Add the following to a `.d.ts` file included in your project:

```
import "react";



declare module "react" {

  interface Attributes {

    _t?: string; // replace with your `jsxPlaceholderAttribute` value

  }

}
```

## macro.jsxPlaceholderDefaults[​](#macrojsxplaceholderdefaults "Direct link to macro.jsxPlaceholderDefaults")

Default value: `undefined`

A mapping of JSX element tag names to default placeholder names. When a JSX element inside `<Trans>` matches a key in this map and does not have an explicit placeholder attribute (see [`macro.jsxPlaceholderAttribute`](#macrojsxplaceholderattribute)), the corresponding value is used as the placeholder name.

```
// lingui.config

{

  macro: {

    jsxPlaceholderAttribute: "_t",

    jsxPlaceholderDefaults: {

      a: "link",

      em: "emphasis",

      strong: "bold",

    },

  }

}



// source

<Trans>

  Click <a href="/">here</a> and <em>this</em>

</Trans>;



// extracted message: "Click <link>here</link> and <emphasis>this</emphasis>"
```

Explicit attributes (via `jsxPlaceholderAttribute`) take priority over defaults.

One Name per Distinct Element

A placeholder name can be used only once per message. If two elements in the same `<Trans>` resolve to the same name but differ in tag or props, for example two `<a>` elements with different `href` values both mapped to `link`, the macro throws an error instead of numbering them (`<link1>`, `<link2>`). Give at least one of them an explicit name via `jsxPlaceholderAttribute`:

```
<Trans>

  Read the{" "}

  <a _t="docs" href="/docs">

    docs

  </a>{" "}

  or the{" "}

  <a _t="faq" href="/faq">

    FAQ

  </a>

  .

</Trans>



// extracted message: "Read the <docs>docs</docs> or the <faq>FAQ</faq>."
```

Identical elements, such as two `<br />` with no props, share a single placeholder without error.

See [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md#name-your-tags) for when and why to name tags.

Enforce Named Placeholders with ESLint

You can enforce that all JSX tags in `<Trans>` have named placeholders across your codebase using the Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) rule [`no-unnamed-tag-placeholders`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-unnamed-tag-placeholders.md).

## macro.idPrefixLeader[​](#macroidprefixleader "Direct link to macro.idPrefixLeader")

Default value: `undefined`

If defined, the `/* lingui-set idPrefix="..." */`) directive will only prepend `idPrefix` to explicit IDs that start with this leader string. This allows you to selectively apply prefixes to specific IDs while leaving others untouched. The leader string is **kept** in the final ID.

```
// lingui.config

export default {

  macro: {

    idPrefixLeader: ".",

  },

};
```

```
// 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"
```

## macro.jsxRuntime[​](#macrojsxruntime "Direct link to macro.jsxRuntime")

Default value: `undefined`

Controls which JSX runtime semantics the Lingui JSX macro emit.

```
// lingui.config

{

  macro: {

    jsxRuntime: "solid";

  }

}
```

## experimental.runtimeMacro[​](#experimentalruntimemacro "Direct link to experimental.runtimeMacro")

Default value: `false`

Experimental

This option is experimental and may change in a minor release.

Extracts messages defined with the [runtime macro](https://lingui.dev/ref/core.md#runtime-macro) (imports from `@lingui/core/runtime-macro`) to your catalogs.

```
// lingui.config

{

  experimental: {

    runtimeMacro: true,

  }

}
```


---

# Core API Reference

The `@lingui/core` package provides the main i18n object which manages message catalogs, active locale as well as translation and formatting of messages.

## Installation[​](#installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add @lingui/core
```

```
pnpm add @lingui/core
```

## Overview[​](#overview "Direct link to Overview")

The `@lingui/core` package provides a global instance of the `i18n` object, which you can import and use directly:

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



/**

 * Load messages for the requested locale and activate it.

 * This function isn't part of the Lingui because there are

 * many ways how to load messages — from REST API, from file, from cache, etc.

 */

async function activate(locale: string) {

  const { messages } = await import(`${locale}/messages.js`);

  i18n.loadAndActivate({ locale, messages });

}



activate("cs");



// returns the Czech translation of "Hello World"

const translation = i18n.t("Hello World");
```

Advanced

If you prefer not to use the global `i18n` instance and want to set up your own, you can utilize the [`setupI18n`](#setupi18n) method. Additionally, you'll need to configure the [`runtimeConfigModule`](https://lingui.dev/ref/conf.md#runtimeconfigmodule) to ensure that macros work properly.

## Class `i18n()`[​](#i18n "Direct link to i18n")

### `i18n.loadAndActivate(options)`[​](#i18n.loadAndActivate "Direct link to i18n.loadAndActivate")

The `options` parameter is an object with the following properties:

* `locale`: The initial active locale.
* `locales`: A list of alternative locales ([BCP-47](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html) language tags) used for number and date formatting.
* `messages`: The **compiled** message catalog.

It allows to set (overwrite) the catalog for a given locale and activate the locale:

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



const { messages } = await import(`${locale}/messages.js`);

i18n.loadAndActivate({ locale, messages });
```

### `i18n.load(allMessages: AllMessages)`[​](#i18n.load\(allMessages\) "Direct link to i18n.load(allMessages)")

### `i18n.load(locale: string, messages: Messages)`[​](#i18n.load "Direct link to i18n.load")

Load messages for given locale or load multiple message catalogs at once.

When some messages for the provided locale are already loaded, calling `i18n.load` will merge the new messages with the existing ones using `Object.assign`.

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



/**

 * This is just an example of what the catalog looks like internally.

 * Formatting of string messages only works in development. See note below.

 */

const messagesEn = {

  Hello: "Hello",

  "Good bye": "Good bye",

  "My name is {name}": "My name is {name}",

};



const messagesCs = {

  Hello: "Ahoj",

  "Good bye": "Nashledanou",

  "My name is {name}": "Jmenuji se {name}",

};



i18n.load({

  en: messagesEn,

  cs: messagesCs,

});



// This is the same as loading message catalogs separately per language:

// i18n.load('en', messagesEn)

// i18n.load('cs', messagesCs)
```

tip

Don't write catalogs manually. The code above is an example of message catalogs. In real applications, messages are loaded from external message catalogs generated by the [`compile`](https://lingui.dev/ref/cli.md#compile) command or by using tools such as [Vite Plugin](https://lingui.dev/ref/vite-plugin.md), [Webpack Loader](https://lingui.dev/ref/loader.md), or [Metro Transformer](https://lingui.dev/ref/metro-transformer.md).

Formatting of messages as strings (e.g: `"My name is {name}"`) works in development only, when messages are parsed on the fly. In production, however, messages must be compiled using the [`compile`](https://lingui.dev/ref/cli.md#compile) command.

Here's how the same example would look in a real application:

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



// File generated by `lingui compile`

import { messages as messagesEn } from "./locale/en/messages.js";



i18n.load("en", messagesEn);
```

### `i18n.setMessagesCompiler(compiler)`[​](#i18n.setMessagesCompiler "Direct link to i18n.setMessagesCompiler")

Registers a `MessageCompiler` to enable the use of uncompiled catalogs at runtime.

In production builds, the `MessageCompiler` is typically excluded to reduce bundle size.

By default, message catalogs should be precompiled during the build process. However, if you need to compile catalogs at runtime, you can use this method to set a message compiler.

Example usage:

```
import { compileMessage } from "@lingui/message-utils/compileMessage";



i18n.setMessagesCompiler(compileMessage);
```

### `i18n.activate(locale[, locales])`[​](#i18n.activate "Direct link to i18n.activate")

Activate the specified locale and any alternate locales. After calling this method, calling `i18n.t` will return messages in the activated locale.

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



i18n.activate("en");

i18n.t("Hello"); // Return "Hello" in English



i18n.activate("cs");

i18n.t("Hello"); // Return "Hello" in Czech
```

### `i18n.t(messageId[, values[, options]])`[​](#i18n.t "Direct link to i18n.t")

The core method for translating and formatting messages.

* `messageId`: a unique message ID which identifies message in catalog.
* `values`: an object containing variables used in translated message.
* `options.message`: the default translation (optional). This is mostly used when application doesn't use message IDs in natural language (e.g.: `msg.id` or `Component.title`).
* `options.formats`: custom format definitions for dates and times (optional). An object where keys are format names and values are either `Intl.DateTimeFormatOptions` or `Intl.NumberFormatOptions`.

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



// Simple message

i18n.t("Hello");



// Message with variables

i18n.t("My name is {name}", { name: "Tom" });



// Message with custom messageId

i18n.t("msg.id", { name: "Tom" }, { message: "My name is {name}" });



const date = new Date("2014-12-06");

const time = new Date("2014-12-06T17:40:00Z");



// Short date format

i18n.t("It starts on {someDate, date, short}", { someDate: date });



// Short time format

i18n.t("It starts on {someTime, time, short}", { someTime: time });



// Date skeleton format

i18n.t("It starts on {someDate, date, ::GrMMMdd}", { someDate: date });



// Custom date format

i18n.t("It starts on {someDate, date, myStyle}", { someDate: date }, { formats: { myStyle: { day: "numeric" } } });
```

### `i18n.t(messageDescriptor)`[​](#i18ntmessagedescriptor "Direct link to i18ntmessagedescriptor")

`messageDescriptor` is an object with a message ID, default message and other parameters. It's useful when you need to use the declared message later in the code.

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



// Simple message

i18n.t({ id: "Hello" });



// Simple message using custom ID

i18n.t({ id: "msg.hello", message: "Hello" });



// Message with variable

i18n.t({ id: "My name is {name}", values: { name: "Tom" } });



// Message with comment, custom ID and variable

i18n.t({

  id: "msg.name",

  message: "My name is {name}",

  comment: "Message showing the passed in name",

  values: { name: "Tom" },

});
```

Read more about [Message Descriptor](https://lingui.dev/ref/macro.md#core-macros).

### `i18n._(...)`[​](#i18n._ "Direct link to i18n._")

Canonical translation method. [`i18n.t`](#i18n.t) is an alias for this method.

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



i18n._({ id: "Hello" });
```

### `i18n.setVariables(variables)`[​](#i18n.setvariables "Direct link to i18n.setvariables")

Set default values for message variables when they are not passed to [`i18n.t`](#i18n.t). Accepts an object of static values or lazy functions, or an updater `(prev) => next`.

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



i18n.setVariables({

  appName: "ExampleApp",

  version: "1.2.3",

});



i18n.t("Powered by {appName} v{version}");

// Returns "Powered by ExampleApp v1.2.3"
```

Advanced

Default variables also work for placeholders that only exist in translations, like `{gender, select, ...}`. Since the placeholder isn't in the source string, the `select` must be added by your translation pipeline or translators who know the variable exists.

### `i18n.setVariable(name, value)`[​](#i18n.setvariable "Direct link to i18n.setvariable")

Set or update a single default variable, or pass `undefined` to remove it.

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



i18n.setVariable("appName", "ExampleApp");

i18n.setVariable("currentYear", () => new Date().getFullYear());

i18n.setVariable("appName", undefined);
```

### `i18n.date(value: string | Date | number[, format: Intl.DateTimeFormatOptions])`[​](#i18n.date "Direct link to i18n.date")

Format a date using the conventional format for the active language.

* `value`: the date to be formatted, as accepted by [`Intl.DateTimeFormat.prototype.format`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/format#parameters). When `value` is a string, a `Date` object is created using `new Date(date)`.
* `format`: an optional object that is passed to the `options` argument of the [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor. This allows for customization of the date formatting.

Deprecated

`i18n.date` will be removed. Prefer using `Intl.DateTimeFormat` directly:

```
new Intl.DateTimeFormat(i18n.locale, format).format(d);
```

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



const d = new Date("2021-07-23T16:23:00");



i18n.activate("en");

i18n.date(d);

// Returns "7/23/2021"



i18n.date(d, { timeStyle: "medium" });

// Returns "4:23:00 PM"



i18n.date(d, { dateStyle: "medium", timeStyle: "medium" });

// Returns "Jul 23, 2021, 4:23:00 PM"



i18n.activate("cs");

i18n.date(d);

// Returns "23. 7. 2021"
```

### `i18n.number(value: number | bigint | Intl.StringNumericLiteral[, format: Intl.NumberFormatOptions])`[​](#i18n.number "Direct link to i18n.number")

Format a number using the conventional format for the active language.

* `value`: the number to be formatted, as accepted by [`Intl.NumberFormat.prototype.format`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/format#parameters).
* `format`: an optional object that is passed to the `options` argument of the [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) constructor. This allows for customization of the date formatting.

Deprecated

`i18n.number` will be removed. Prefer using `Intl.NumberFormat` directly:

```
new Intl.NumberFormat(i18n.locale, format).format(value);
```

```
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č"
```

## `setupI18n([options])`[​](#setupi18n "Direct link to setupi18n")

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

info

You typically don't need to set up your own `i18n` instance. In most cases, you can use the global `i18n` object exported from `@lingui/core` directly.

However, if you need to do this, make sure to also configure the [`runtimeConfigModule`](https://lingui.dev/ref/conf.md#runtimeconfigmodule) to ensure macros work properly.

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



const i18n = setupI18n();
```

The factory function accepts an optional `options` parameter, which can be used to configure the initial state of the `i18n` instance.

### `options.locale`[​](#optionslocale "Direct link to optionslocale")

Initial active locale.

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



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



// This is a shortcut for:

// const i18n = setupI18n()

// i18n.activate("en")
```

### `options.locales`[​](#optionslocales "Direct link to optionslocales")

List of alternative locales ([BCP-47](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html) language tags) which are used for number and date formatting (some countries use more than one number/date format). If not set, the active locale is used instead.

```
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`[​](#optionsmessages "Direct link to optionsmessages")

Initial [`Messages`](#messages).

```
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`[​](#optionsmissing "Direct link to optionsmissing")

A custom message to be returned when a translation is missing. This feature is useful for debugging:

```
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:

```
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`[​](#optionsvariables "Direct link to optionsvariables")

Initial default message variables (see [`i18n.setVariables`](#i18n.setvariables)).

```
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" })
```

## Runtime macro (experimental)[​](#runtime-macro "Direct link to Runtime macro (experimental)")

Experimental

The runtime macro is experimental. Its API and import path may change in a minor release.

`@lingui/core/runtime-macro` exports `msg` (and its alias `defineMessage`), `plural`, `select` and `selectOrdinal` as plain functions. They work without a Babel or SWC plugin, so you can use them where there is no build step: Node.js scripts, serverless functions, CLI tools or test runners.

They return the same [Message Descriptor](https://lingui.dev/ref/macro.md#core-macros), with the same generated ID, as the [core macros](https://lingui.dev/ref/macro.md#core-macros). The extractor picks them up when [`experimental.runtimeMacro`](https://lingui.dev/ref/conf.md#experimentalruntimemacro) is enabled in your config.

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

import { msg, plural } from "@lingui/core/runtime-macro";



const greeting = msg`Hello ${{ name }}`;

i18n._(greeting);



const inbox = msg`You have ${plural({ count }, { one: "# message", other: "# messages" })}`;

i18n._(inbox);



const welcome = msg({ message: "Welcome back", context: "homepage" });

i18n._(welcome);
```

The runtime macro supports a subset of the core macros, with a few differences:

* **Placeholders must be named.** Variable names can't be read at runtime, so write `${{ name }}` instead of `${name}`. A plain value throws an error.
* **Option values can't be template literals.** Use a nested `msg` instead: ``select({ gender }, { female: msg`She is ${{ name }}`, other: msg`They are ${{ name }}` })``.
* **No `t` and no JSX.** Define a message with `msg` and translate it with [`i18n._`](#i18n._).
* **Use `plural`, `select` and `selectOrdinal` inside `msg`.** On their own, they return a Message Descriptor at runtime, but a build step that compiles them (see below) turns them into a translated string, like the core macros. Inside `msg`, both give the same result.
* **Without a compile step, the source message stays in your bundle.** The compile-time macros can strip it in production.

With [`experimental.runtimeMacro`](https://lingui.dev/ref/conf.md#experimentalruntimemacro) enabled, the Babel macro plugin and the [Vite native transform](https://lingui.dev/ref/vite-plugin.md) also compile these imports at build time, like the core macros. The [SWC plugin](https://lingui.dev/ref/swc-plugin.md) doesn't read the Lingui config: add `@lingui/core/runtime-macro` to its `corePackage` option if you want the same there. Without compilation, the code still works as it is.

## AllMessages[​](#allmessages "Direct link to AllMessages")

The `AllMessages` parameter in the [`I18n.load`](#i18n.load) method is of the following type:

```
type AllMessages = { [locale: string]: CompiledMessage };



// Example

const messages: AllMessages = {

  en: {

    messages: {

      Hello: "Hello",

      "Good bye": "Good bye",

    },

  },

  cs: {

    messages: {

      Hello: "Ahoj",

      "Good bye": "Nashledanou",

    },

  },

};
```

## Messages[​](#messages "Direct link to Messages")

Type of messages in [`AllMessages`](#allmessages). It's a mapping of a message ID to a translation in given language. This may be a function if messages are compiled.

```
type Messages = { [messageId: string]: string | Function };



// Example

const messagesEn: Messages = {

  Hello: "Hello",

  "Good bye": "Good bye",

};
```

## Events[​](#events "Direct link to Events")

### `change`[​](#change "Direct link to change")

The `change` event is triggered **after** changing the locale, loading a new message catalog, or updating default variables. No arguments are passed to this event.

### `missing`[​](#missing "Direct link to missing")

The `missing` event is triggered when a translation is requested using [`i18n.t`](https://lingui.dev/ref/core.md#i18n.t) that does not exist in the messages of the active locale. The event provides information about the locale and the missing message ID.

```
i18n.on("missing", (event) => {

  alert(`Translation in ${event.locale} for ${event.id} is missing!`);

});
```


---

# ESLint Plugin

Lingui provides an ESLint plugin to help you find common Lingui usage errors in your code.

[![npm-version](https://img.shields.io/npm/v/eslint-plugin-lingui?logo=npm\&cacheSeconds=1800)](https://www.npmjs.com/package/eslint-plugin-lingui) [![npm-downloads](https://img.shields.io/npm/dt/eslint-plugin-lingui?cacheSeconds=500)](https://www.npmjs.com/package/eslint-plugin-lingui)

## Installation[​](#installation "Direct link to Installation")

Install [ESLint](http://eslint.org):

* npm
* Yarn
* pnpm

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

```
yarn add --dev eslint
```

```
pnpm add --save-dev eslint
```

Next, install `eslint-plugin-lingui`:

* npm
* Yarn
* pnpm

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

```
yarn add --dev eslint-plugin-lingui
```

```
pnpm add --save-dev eslint-plugin-lingui
```

info

If you have installed ESLint globally (using the `-g` flag), you must also install `eslint-plugin-lingui` globally.

## Usage[​](#usage "Direct link to Usage")

### Flat Config (`eslint.config.js`)[​](#flat-config "Direct link to flat-config")

Version 8 of ESLint introduced a new configuration format called [Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files). Flat config files represent plugins and parsers as JavaScript objects.

#### Recommended Setup[​](#recommended-setup "Direct link to Recommended Setup")

To enable all the recommended rules for the plugin, add the following config:

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



export default [

  pluginLingui.configs["flat/recommended"],

  // Any other config...

];
```

#### Custom Setup[​](#custom-setup "Direct link to Custom Setup")

Alternatively, you can load the plugin and configure only the rules you want to use:

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



export default [

  {

    plugins: {

      lingui: pluginLingui,

    },

    rules: {

      "lingui/t-call-in-function": "error",

    },

  },

  // Any other config...

];
```

### Legacy Config (`.eslintrc`)[​](#legacy-eslintrc "Direct link to legacy-eslintrc")

The legacy configuration format has been deprecated by ESLint, but it's still supported. If you're using the legacy format, you can use the following configuration.

#### Recommended Setup[​](#recommended-setup-1 "Direct link to Recommended Setup")

To enable all the recommended rules for the plugin, add `plugin:lingui/recommended` to the `extends` section:

```
{

  "extends": ["plugin:lingui/recommended"]

}
```

#### Custom Setup[​](#custom-setup-1 "Direct link to Custom Setup")

Alternatively, add `lingui` to the `plugins` section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:

```
{

  "plugins": ["lingui"]

}
```

In the rules section, configure the rules you want to use. For example:

```
{

  "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

  }

}
```

### Oxlint[​](#oxlint "Direct link to Oxlint")

The plugin also works as an [Oxlint JS plugin](https://oxc.rs/docs/guide/usage/linter/js-plugins) without any changes. Add it to `jsPlugins` in your `.oxlintrc.json` and enable the rules you need.

Oxlint doesn't read the plugin's `configs`, so the recommended rules have to be listed explicitly:

```
{

  "jsPlugins": ["eslint-plugin-lingui"],

  "rules": {

    "lingui/t-call-in-function": "error",

    "lingui/no-single-tag-to-translate": "warn",

    "lingui/no-single-variables-to-translate": "warn",

    "lingui/no-trans-inside-trans": "warn",

    "lingui/no-expression-in-message": "warn"

  }

}
```

Compatibility with Oxlint is verified in CI on every change. The only known limitation is the `useTsTypes` option of the [`no-unlocalized-strings`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-unlocalized-strings.md) rule: it needs type information from `@typescript-eslint/parser`, which Oxlint doesn't provide.

tip

See the [official repository](https://github.com/lingui/eslint-plugin) for more information about the rules.


---

# Vue.js Extractor

The `@lingui/extractor-vue` package provides a custom extractor that handles Vue.js files.

## Installation[​](#installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/extractor-vue
```

```
pnpm add --save-dev @lingui/extractor-vue
```

## Usage[​](#usage "Direct link to Usage")

It is required that you use JavaScript or TypeScript for your Lingui configuration.

lingui.config.{js,ts}

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

import { createVueExtractor } from "@lingui/extractor-vue";

import babel from "@lingui/cli/api/extractors/babel";



export default defineConfig({

  locales: ["en", "nb"],

  sourceLocale: "en",

  catalogs: [

    {

      path: "<rootDir>/src/{locale}",

      include: ["<rootDir>/src"],

    },

  ],

  extractors: [babel, createVueExtractor()],

});
```

## Options[​](#options "Direct link to Options")

### Vue Reactivity Transform[​](#vue-reactivity-transform "Direct link to Vue Reactivity Transform")

If your project uses Vue's [Reactive Props Destructure](https://github.com/vuejs/rfcs/discussions/502), enable `vueReactivityTransform` to ensure message IDs match between extraction and runtime:

lingui.config.{js,ts}

```
import { createVueExtractor } from "@lingui/extractor-vue";



export default defineConfig({

  // ... other config

  extractors: [babel, createVueExtractor({ reactivityTransform: true })],

});
```

## See Also[​](#see-also "Direct link to See Also")

* [Message Extraction](https://lingui.dev/guides/message-extraction.md)
* [Custom Extractor](https://lingui.dev/guides/custom-extractor.md)


---

# Webpack-compatible loader

The `@lingui/loader` is a Webpack-compatible loader for Lingui message catalogs. It can be used with Webpack, Rspack, and Rsbuild. It offers an alternative to the [`lingui compile`](https://lingui.dev/ref/cli.md#compile) and compiles catalogs on the fly.

It enables you to `import` `.po` files directly, instead of running `lingui compile` and `import`ing the resulting JavaScript (or TypeScript) files.

## Installation[​](#installation "Direct link to Installation")

Install `@lingui/loader` as a development dependency:

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/loader
```

```
pnpm add --save-dev @lingui/loader
```

## Usage[​](#usage "Direct link to Usage")

The recommended setup is to configure the loader in your bundler config and import catalogs without the inline loader syntax.

```
module: {

  rules: [

    {

      test: /\.po$/,

      use: [

        {

          loader: "@lingui/loader",

          options: {

            failOnCompileError: true,

          },

        },

      ],

    },

    ...otherRules

  ],

}
```

Here's an example of dynamic import:

```
export async function dynamicActivate(locale: string) {

  const { messages } = await import(`../locales/${locale}/messages.po`);

  i18n.loadAndActivate({

    locale,

    messages,

  });

}
```

You can also prepend `@lingui/loader!` in front of the catalog path if you prefer inline loader syntax:

```
export async function dynamicActivate(locale: string) {

  const { messages } = await import(`@lingui/loader!./locales/${locale}/messages.po`);

  i18n.loadAndActivate({

    locale,

    messages,

  });

}
```

Remember that the file extension is mandatory.

## Options[​](#options "Direct link to Options")

### `failOnMissing`[​](#failonmissing "Direct link to failonmissing")

Fail the build when missing translations are detected.

* `true` or `"resolved"`: fail only if a translation is still missing after `fallbackLocales` are applied.
* `"catalog"`: fail if the target locale catalog itself has missing translations before `fallbackLocales` are applied.
* `false` or omitted: do not fail the build on missing translations.

### `failOnCompileError`[​](#failoncompileerror "Direct link to failoncompileerror")

Fail the build when message compilation produces errors.

note

Catalogs with the `.json` extension are treated differently by Webpack-compatible bundlers. They load as ES module with default export, so your import should look like this:

```
const { messages } = (await import(`@lingui/loader!./locales/${locale}/messages.json`)).default;
```

## See Also[​](#see-also "Direct link to See Also")

* [Dynamic Loading of Message Catalogs](https://lingui.dev/guides/dynamic-loading-catalogs.md)
* [Catalog Formats](https://lingui.dev/ref/catalog-formats.md)


---

# Locale Detection

The `@lingui/detect-locale` is a lightweight package *(only \~1 kB Gzip)* providing several methods and helpers to determine the user's locale using different detection strategies.

Most of the detectors accept custom document, location or window objects as parameters, which is especially useful for testing purposes or when implementing server-side detection strategies.

## Installation[​](#installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add @lingui/detect-locale
```

```
pnpm add @lingui/detect-locale
```

## Reference[​](#reference "Direct link to Reference")

### `detect`[​](#detect "Direct link to detect")

The `detect` method accepts multiple detectors as arguments and returns the first valid locale detected.

### `multipleDetect`[​](#multipledetect "Direct link to multipledetect")

The `multipleDetect` method also accepts multiple detectors as arguments and returns an array with all locales detected by each detector.

### `fromCookie(key: string)`[​](#fromCookie "Direct link to fromCookie")

Accepts a key as a parameter and retrieves the locale value from the browser's cookies based on that key.

### `fromHtmlTag(tag: string)`[​](#fromHtmlTag "Direct link to fromHtmlTag")

Looks for the specified attribute in the HTML document (commonly `lang` or `xml:lang`) to detect the locale.

### `fromNavigator()`[​](#fromNavigator "Direct link to fromNavigator")

Retrieves the user's language setting from the browser, compatible with older browsers such as IE11.

### `fromPath(localePathIndex: number)`[​](#fromPath "Direct link to fromPath")

Splits `location.pathname` into an array, requiring you to specify the index where the locale is located.

### `fromStorage(key: string, { useSessionStorage: boolean })`[​](#fromStorage "Direct link to fromStorage")

Searches for the item with the specified key in `localStorage` by default. If the `useSessionStorage` parameter is passed, it will search in `sessionStorage`.

### `fromSubdomain(localeSubdomainIndex: number)`[​](#fromSubdomain "Direct link to fromSubdomain")

Splits `location.href` by subdomain segments, requiring the index where the locale is specified.

### `fromUrl(parameter: string)`[​](#fromUrl "Direct link to fromUrl")

Uses a query string parser to find the locale by the specified parameter in the URL.

## Usage Examples[​](#usage-examples "Direct link to Usage Examples")

### Usage with `detect`[​](#usage-with-detect "Direct link to usage-with-detect")

```
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"
```

### Usage with `multipleDetect`[​](#usage-with-multipledetect "Direct link to usage-with-multipledetect")

```
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"]
```


---

# Macros

Lingui Macro provides powerful macros to transform JavaScript objects and JSX elements into [ICU MessageFormat](https://lingui.dev/guides/message-format.md) messages at compile time. It provides a more efficient and developer-friendly way to handle internationalization in your project.

The benefits of using macros:

* You don't have to learn ICU MessageFormat syntax. You always use familiar JS and JSX code.
* Components and functions are type checked.
* Short IDs are generated for your messages.
* Additional validation of plural rules is performed during transformation.
* Non-essential data is removed from the production build (e.g. comments and default messages) to save a few bytes.

There are two types of macros: [Core Macros](#core-macros) (JS) and [React Macros](#react-macros) (JSX).

No build step?

Macros need a compiler plugin. If your code runs without a build step, for example in Node.js scripts, serverless functions or test runners, see the experimental [runtime macro](https://lingui.dev/ref/core.md#runtime-macro).

## Core Macros[​](#core-macros "Direct link to Core Macros")

Core (JS) Macros can be used in any JavaScript context (e.g. outside JSX). All JS macros are transformed into a *Message Descriptor* wrapped inside of [`i18n._`](https://lingui.dev/ref/core.md#i18n._) call:

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

t`Attachment ${name} saved`;



// ↓ ↓ ↓ ↓ ↓ ↓



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

i18n._(

  /** i18n */ {

    id: "nwR43V",

    message: "Attachment {name} saved",

    values: { name },

  }

);
```

`/** i18n */` comment

In the example above you may notice the `/** i18n */` comment in the macro output. This comment tells the extract plugin that the following object should be collected into the message catalog.

*Message Descriptor* is an object with a message ID, default message and other parameters:

```
type MessageDescriptor = {

  id: string;

  message?: string;

  values?: Record<string, any>;

  comment?: string;

};
```

The `id` is the message ID and is the only parameter required. The `id` and `message` are extracted into the message catalog. Only `id` and `values` are used at runtime, all other attributes are removed from the production code for size optimization.

You don't need to specify the ID manually. By default, Macro will automatically create a short ID from your message. However, you can explicitly specify a custom ID. Read more about [Explicit vs Generated IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md).

### `t`[​](#t "Direct link to t")

The most common macro for messages. It transforms tagged template literal into message in ICU MessageFormat:

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

const message = t`Hello World`;



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "mY42CM",

    message: "Hello World",

  }

);
```

Message variables are supported:

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

const message = t`My name is ${name}`;



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "mVmaLu",

    message: "My name is {name}",

    values: { name },

  }

);
```

In fact, any expression can be used inside template literal. However, only simple variables are referenced by name in a transformed message. All other expressions are referenced by their numeric index:

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

const message = t`Today is ${new Date()}`;



// ↓ ↓ ↓ ↓ ↓ ↓



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



const message = i18n._(

  /** i18n */ {

    id: "2aJT27",

    message: "Today is {0}",

    values: { 0: new Date() },

  }

);
```

info

By default the `i18n` object is imported from [`@lingui/core`](https://lingui.dev/ref/core.md). If you are using a custom instance of the `i18n` object, you need to set [`runtimeConfigModule`](https://lingui.dev/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](https://lingui.dev/ref/macro.md#t).

It's also possible to pass custom `id` and `comment` for translators by calling `t` macro with a message descriptor:

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

const message = t({

  id: "msg.hello",

  comment: "Greetings at the homepage",

  message: `Hello ${name}`,

});



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "msg.hello",

    comment: "Greetings at the homepage",

    message: "Hello {name}",

    values: { name },

  }

);
```

In this case, `message` is used as the default message, and it's transformed as if it were wrapped in a `t` macro. `message` also accepts any other macros:

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

const message = t({

  id: "msg.plural",

  message: plural(value, { one: "...", other: "..." }),

});



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "msg.plural",

    message: "{value, plural, one {...} other {...}}",

    values: { value },

  }

);
```

### `plural`[​](#plural "Direct link to plural")

Pluralization is a common problem in i18n. Different languages have different rules for plural form (e.g. English has only `one` and `other`, while Czech has `one`, `few`, `many` and `other`). The `plural` macro is used to handle this.

```
plural(value: string | number, options: Object)
```

The `value` specifies the plural form or cardinal number. The second argument, `options`, is an object with available plural forms:

```
import { plural } from "@lingui/core/macro";

const message = plural(count, {

  one: "# Book",

  other: "# Books",

});



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "V/M0Vc",

    message: "{count, plural, one {# Book} other {# Books}}",

    values: { count },

  }

);
```

tip

Choose the plural forms used in your source code based on the pluralization rules of your source locale.

If you need to add variables in plural form, you can use template string literals. This time you don't need the [`t`](https://lingui.dev/ref/macro.md#t) macro, because template strings are transformed automatically:

```
import { plural } from "@lingui/core/macro";

const message = plural(count, {

  one: `${name} has # friend`,

  other: `${name} has # friends`,

});



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "CvuUwE",

    message: "{count, plural, one {{name} has # friend} other {{name} has # friends}}",

    values: { count, name },

  }

);
```

Plurals can also be nested to form complex messages. Here's an example using two counters:

```
import { plural } from "@lingui/core/macro";

const message = plural(numBooks, {

  one: plural(numArticles, {

    one: `1 book and 1 article`,

    other: `1 book and ${numArticles} articles`,

  }),

  other: plural(numArticles, {

    one: `${numBooks} books and 1 article`,

    other: `${numBooks} books and ${numArticles} articles`,

  }),

});



// ↓ ↓ ↓ ↓ ↓ ↓

// Generated message was wrapped for better readability



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

const message = i18n._(

  /** i18n */ {

    id: "XnUh4j",

    message: `{numBooks, plural,

         one {{numArticles, plural,

            one {1 book and 1 article}

            other {1 book and {numArticles} articles}

         }}

         other {{numArticles, plural,

            one {{numBooks} books and 1 article}

            other {{numBooks} books and {numArticles} articles}

         }}

      }`,

    values: { numBooks, numArticles },

  }

);
```

This is just one example of how macros can be combined to create a complex message. However, simple is better, because in the end it's the translator who has to translate these long and complex strings.

tip

Use `plural` inside [`t`](#t) or [`defineMessage`](#definemessage) macro if you want to add custom `id`, `context` or `comment` for translators.

```
const message = t({

  id: "my.custom.id",

  comment: "My Comment",

  message: plural(count, {

    one: "# Book",

    other: "# Books",

  }),

});
```

### `selectOrdinal`[​](#selectordinal "Direct link to selectordinal")

SelectOrdinal is a variation of the [`plural`](#plural) macro. It's used to handle ordinal numbers (e.g. 1st, 2nd, 3rd, 4th, etc.).

```
selectOrdinal(value: string | number, options: Object)
```

The `value` specifies the ordinal number. The second argument, `options`, is an object with available ordinal forms:

```
import { selectOrdinal } from "@lingui/core/macro";

const message = selectOrdinal(count, {

  one: "#st",

  two: "#nd",

  few: "#rd",

  other: "#th",

});



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "V8xI3w",

    message: "{count, selectOrdinal, one {#st} two {#nd} few {#rd} other {#th}}",

    values: { count },

  }

);
```

tip

Use `selectOrdinal` inside [`t`](#t) or [`defineMessage`](#definemessage) macro if you want to add custom `id`, `context` or `comment` for translators.

```
const message = t({

  id: "my.custom.id",

  comment: "My Comment",

  message: selectOrdinal(count, {

    one: "#st",

    two: "#nd",

    few: "#rd",

    other: "#th",

  }),

});
```

### `select`[​](#select "Direct link to select")

The `select` macro is used to handle different forms of a message based on a value.

```
select(value: string | number, options: Object)
```

It works like a switch statement - it selects one of the forms provided in the `options` object based on the `value`:

```
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 },

  }

);
```

tip

Use `select` inside [`t`](#t) or [`defineMessage`](#definemessage) macro if you want to add custom `id`, `context` or `comment` for translators.

```
const message = t({

  id: "my.custom.id",

  comment: "My Comment",

  message: select(gender, {

    male: "he",

    female: "she",

    other: "they",

  }),

});
```

### `defineMessage` / `msg`[​](#definemessage "Direct link to definemessage")

The `defineMessage` (alias: `msg`) macro allows to define a message for later use. It has the same signature as `t` and returns a `MessageDescriptor` that you can pass to `i18n.t` to get a translated string at any time later. This is useful for [Lazy Translations](https://lingui.dev/guides/lazy-translations.md).

In other words, `t` returns a translated string at the time when it's called, while `msg` returns a `MessageDescriptor` that can produce translated strings later:

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

import { defineMessage } from "@lingui/core/macro";



// define message

const message = defineMessage`Hello World`;



// use it later

i18n.t(message);



// ↓ ↓ ↓ ↓ ↓ ↓



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



const message = /** i18n */ {

  id: "mY42CM",

  message: "Hello World",

};



// use it later

i18n.t(message);
```

You can also use a shorter alias of the `defineMessage` macro:

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

const message = msg`Hello World`;



// ↓ ↓ ↓ ↓ ↓ ↓



const message = /** i18n */ {

  id: "mY42CM",

  message: "Hello World",

};
```

The `defineMessage` macro also supports a `MacroMessageDescriptor` object as input. This can be used to provide additional information for the message such as comment or context:

```
type MacroMessageDescriptor = {

  id?: string;

  message?: string;

  comment?: string;

  context?: string;

};
```

Either the `id` or `message` property is required. `id` is a custom message ID. If it isn't set, the `message` (and `context` if present) will be used to generate an ID. Read more about [Explicit vs Generated IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md).

```
import { defineMessage } from "@lingui/core/macro";

const message = defineMessage({

  id: "Navigation / About",

  message: "About us",

});



// ↓ ↓ ↓ ↓ ↓ ↓



const message = /** i18n */ {

  id: "Navigation / About",

  message: "About us",

};
```

The `message` is a default message. Any JS macro can be used here. Template string literals don't need to be tagged with [`t`](#t).

```
import { defineMessage } from "@lingui/core/macro";

const name = "Joe";

const message = defineMessage({

  message: `Welcome, ${name}!`,

});



// ↓ ↓ ↓ ↓ ↓ ↓



const message = /** i18n */ {

  id: "dgJjNB",

  message: "Welcome, {name}",

  values: {

    name,

  },

};
```

The `comment` is a comment for translators. It's extracted into the message catalog, and it gives translators additional information about the message. It's removed from the production code:

```
import { defineMessage } from "@lingui/core/macro";

const message = defineMessage({

  comment: "Link in navigation pointing to About page",

  message: "About us",

});



// ↓ ↓ ↓ ↓ ↓ ↓



const message = /** i18n */ {

  id: "+mNwru",

  comment: "Link in navigation pointing to About page",

  message: "About us",

};
```

Note

In the production build, the macro is stripped of `message`, `comment` and `context` properties:

```
import { defineMessage } from "@lingui/core/macro";

const message = defineMessage({

  id: "msg.navigation.about",

  comment: "Link in navigation pointing to About page",

  message: "About us",

  context: "Context about the link",

});



// process.env.NODE_ENV === "production"

// ↓ ↓ ↓ ↓ ↓ ↓



const message = /** i18n */ {

  id: "msg.navigation.about",

};
```

`message` and `comment` are used in message catalogs only. `context` is used only for generating ID and is stripped from the output.

### `ph`[​](#ph "Direct link to ph")

The `ph` macro is used to provide explicit labels for placeholders. By default, only simple variables are referenced by name in transformed messages. Complex expressions (like function calls) are referenced by numeric index (`{0}`, `{1}`), which provides little context for translators.

The `ph` macro solves this by letting you assign meaningful names to any expression. See [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md#name-your-placeholders) for guidance on when to use it:

```
import { t, ph } from "@lingui/core/macro";



// Without ph(): "Hello {0}"

t`Hello ${getUserName()}`;



// With ph(): "Hello {name}"

t`Hello ${ph({ name: getUserName() })}`;
```

It works by taking an object with a single property, where the key becomes the placeholder name and the value is the expression:

```
import { t, ph } from "@lingui/core/macro";

const message = t`Hello ${ph({ name: getUserName() })}`;



// ↓ ↓ ↓ ↓ ↓ ↓



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

const message = i18n._(

  /** i18n */ {

    id: "OUzSsf",

    message: "Hello {name}",

    values: { name: getUserName() },

  }

);
```

The `ph` macro can be used with any other macro that accepts expressions, including [`plural`](#plural), [`select`](#select), and JSX macros like [`Trans`](#trans):

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

import { ph } from "@lingui/core/macro";



<Trans>Welcome back, {ph({ username: getUser().name })}!</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id={"Z5GF+g"} message="Welcome back, {username}!" values={{ username: getUser().name }} />;
```

### `lingui-set` / `lingui-reset` Comment Directives[​](#lingui-directive "Direct link to lingui-directive")

Instead of passing `context` and/or `comment` to every macro call, you can use the `lingui-set` and `lingui-reset` comment directives to set these values for all subsequent macros in the same file (or until the next directive resets/overrides them). See [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md#set-context-once-per-file) for typical use cases.

* **`lingui-set`**: Sets the specified parameters for all subsequent macros. Requires at least one parameter.
* **`lingui-reset`**: Clears all previously set parameters. Also accepts new parameters to set like `lingui-set`.

The directive is placed in a comment directly above (or anywhere before) the macro calls it should affect:

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



// lingui-set context="homepage"

const msg1 = t`Welcome`;

const msg2 = t`Sign up`;
```

Both `msg1` and `msg2` will have `context` set to `"homepage"`.

tip

A directive that is never reset applies to every macro that follows it in the file, including messages added later. You can enforce that each `lingui-set` is closed with a `lingui-reset` using the Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) rule [`require-directive-reset`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/require-directive-reset.md).

#### Supported Params[​](#supported-params "Direct link to Supported Params")

| Param      | Example                     | Description                                                                                                                                                                 |
| ---------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`  | `context="homepage"`        | Sets the [context](https://lingui.dev/guides/explicit-vs-generated-ids.md#context) for ID generation                                                                        |
| `comment`  | `comment="translator note"` | Sets the [comment](#comment) for translators                                                                                                                                |
| `idPrefix` | `idPrefix="module."`        | Prefixes explicit `id` values (does not affect generated IDs). If `macro.idPrefixLeader` is specified in the lingui config, only IDs starting with the leader are prefixed. |

#### Syntax[​](#syntax "Direct link to Syntax")

Both line comments and block comments are supported:

```
// lingui-set context="homepage"

/* lingui-set context="homepage" comment="note" */

// lingui-reset

/* lingui-reset context="new context" */
```

Params use the `key="value"` syntax. Values must be wrapped in double quotes.

#### Merging and Scoping[​](#merging-and-scoping "Direct link to Merging and Scoping")

Directives are **file-scoped**. Each directive merges its values with values from previous directives. This allows you to set a base context at the top of a file and add or override specific values later:

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



// lingui-set context="settings" comment="Settings page"

const msg1 = t`Save`;



// lingui-set comment="Updated note"

const msg2 = t`Cancel`; // context="settings", comment="Updated note"
```

#### Unsetting a Value[​](#unsetting-a-value "Direct link to Unsetting a Value")

Setting a param to an empty string unsets that specific value, without affecting other inherited values:

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



// lingui-set context="settings" comment="note"

const msg1 = t`Save`; // context="settings", comment="note"



// lingui-set context=""

const msg2 = t`Cancel`; // comment="note" (context is removed)
```

#### Resetting Prior Values[​](#resetting-prior-values "Direct link to Resetting Prior Values")

The `lingui-reset` directive clears **all** inherited values. You can combine it with new values to immediately set a new context:

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



// lingui-set context="settings" comment="note"

const msg1 = t`Save`;



// lingui-reset

const msg2 = t`Cancel`; // no context & no comment



// lingui-reset context="new section"

const msg3 = t`Delete`; // context="new section"
```

#### Explicit Values Override Directives[​](#explicit-values-override-directives "Direct link to Explicit Values Override Directives")

Values passed directly to a macro always take precedence over directive values:

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



// lingui-set context="directive ctx"

const msg = t({ message: "Hello", context: "explicit ctx" });

// → context will be "explicit ctx"
```

#### Usage with React (JSX) Macros[​](#usage-with-react-jsx-macros "Direct link to Usage with React (JSX) Macros")

The directive works with React macros too:

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



{/* lingui-set idPrefix="homepage." context="homepage" */}

<Trans>Welcome</Trans>

<Trans id="copyright">Copyright</Trans>
```

## React Macros[​](#react-macros "Direct link to React Macros")

React (JSX) Macros are used in JSX elements and are transformed into the [`Trans`](https://lingui.dev/ref/react.md#trans) component imported from the [`@lingui/react`](https://lingui.dev/ref/react.md) package.

### `Trans`[​](#trans "Direct link to trans")

The `Trans` macro is used to translate static messages, messages with variables and messages with inline markup:

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

<Trans>Refresh inbox</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id="EsCV2T" message="Refresh inbox" />;
```

Available Props:

| Prop Name | Type   | Description                                            |
| --------- | ------ | ------------------------------------------------------ |
| `id`      | string | Custom message ID                                      |
| `comment` | string | Comment for translators                                |
| `context` | string | Allows to extract the same messages with different IDs |
| `render`  | func   | Custom render callback to render translation           |

#### `id`[​](#id "Direct link to id")

Each message in the catalog is identified by a message ID. While macro uses message (and `context` property if provided) to generate the ID, it's possible to provide custom ID. Read more about [Explicit vs Generated IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md).

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

<Trans id="message.attachment_saved">Attachment {name} saved.</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id="message.attachment_saved" message="Attachment {name} saved." />;
```

#### `comment`[​](#comment "Direct link to comment")

Comment for translators to give them additional information about the message. It will be visible in the [TMS](https://lingui.dev/tools/introduction.md) if it is supported, and in the [catalog format](https://lingui.dev/ref/catalog-formats.md). It will be removed from production code. See [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md#explain-what-the-message-means) for what makes a useful comment.

tip

You can require every message to describe itself to translators with the Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) rule [`require-comment`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/require-comment.md). It accepts a [`lingui-set comment="..."`](#lingui-directive) directive as well, which is the only option for tagged template literals such as `` t`Save` ``.

#### `context`[​](#context "Direct link to context")

Allows to extract the same messages with different IDs. It is useful when the same message has different meanings in different contexts. See [Context](https://lingui.dev/guides/explicit-vs-generated-ids.md#context) for more details.

Similarly to [`comment`](#comment), it will be added to the message catalog, visible in TMS and will be removed from the production code:

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

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

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



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id={"d1wX4r"} message="right" />;

<Trans id={"16eaSK"} message="right" />;
```

This macro is particularly useful if the message contains inline markup:

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



<Trans>

  Read the <a href="/docs">docs</a>.

</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id={"mk8bSG"} message="Read the <0>docs</0>." components={{ 0: <a href="/docs" /> }} />;
```

Components and HTML tags are replaced by dummy indexed tags (`<0></0>`) which has several advantages:

* Both custom React components and built-in HTML tags are supported.
* Changing component props doesn't break translation.
* The message is extracted as a whole sentence (this seems to be obvious, but most i18n libs simply split the message into pieces by tags and translate them separately).

Named Tag Placeholders

By default, tags are indexed numerically (`<0></0>`). To provide descriptive placeholder names for translators (e.g. `<link>docs</link>`), configure [`macro.jsxPlaceholderAttribute`](https://lingui.dev/ref/conf.md#macrojsxplaceholderattribute) or [`macro.jsxPlaceholderDefaults`](https://lingui.dev/ref/conf.md#macrojsxplaceholderdefaults). You can enforce named placeholders with the Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) rule [`no-unnamed-tag-placeholders`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-unnamed-tag-placeholders.md).

#### `render`[​](#render "Direct link to render")

Custom render callback to render translation. This prop is passed directly to the [`Trans`](https://lingui.dev/ref/react.md#trans) component from the [`@lingui/react`](https://lingui.dev/ref/react.md) package.

### `Plural`[​](#plural-1 "Direct link to plural-1")

The `Plural` JSX macro is used to handle plural forms. It's similar to the [`plural`](#plural) core macro, but is used in JSX elements.

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

<Plural value={numBooks} one="Book" other="Books" />;



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id={"is7n96"} message="{numBooks, plural, one {Book} other {Books}}" values={{ numBooks }} />;
```

Available Props:

| Prop name   | Type   | Description                                            |
| ----------- | ------ | ------------------------------------------------------ |
| `other`     | string | *(required)* general *plural* form                     |
| `value`     | number | *(required)* Value is mapped to plural form below      |
| `offset`    | number | Offset of value when calculating plural forms          |
| `zero`      | string | Form for empty `value`                                 |
| `one`       | string | *Singular* form                                        |
| `two`       | string | *Dual* form                                            |
| `few`       | string | *Paucal* form                                          |
| `many`      | string | *Plural* form                                          |
| `_<number>` | string | Exact match form, corresponds to `=N` rule             |
| `id`        | string | Custom message ID                                      |
| `comment`   | string | Comment for translators                                |
| `context`   | string | Allows to extract the same messages with different IDs |
| `render`    | func   | Custom render callback to render translation           |

`#` in a form is replaced with `value` (minus `offset`), formatted for the active locale with [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat): `1234.5` reads `1,234.5` in `en` and `1.234,5` in `de`.

Exact matches in MessageFormat syntax are expressed as `=int` (e.g. `=0`), but in React this isn't a valid prop name. Therefore, exact matches are expressed as `_int` prop (e.g. `_0`). This is commonly used in combination with `offset` prop. `offset` affects only plural forms, not exact matches.

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



<Plural

  value={count}

  offset={1}

  // when value == 0

  _0="Nobody arrived"

  // when value == 1

  _1="Only you arrived"

  // when value == 2

  // value - offset = 1 -> `one` plural form

  one="You and # other guest arrived"

  // when value >= 3

  other="You and # other guests arrived"

/>;



/*

  This is transformed to Trans component with ID:

  {count, plural, offset:1 _0    {Nobody arrived}

                           _1    {Only you arrived}

                           one   {You and # other guest arrived}

                           other {You and # other guests arrived}}

*/
```

### `SelectOrdinal`[​](#selectordinal-1 "Direct link to selectordinal-1")

The `SelectOrdinal` JSX macro is used to handle ordinal numbers. It's similar to the [`selectOrdinal`](#selectordinal) core macro, but is used in JSX elements.

```
import { SelectOrdinal } from "@lingui/react/macro";



// count == 1 -> 1st

// count == 2 -> 2nd

// count == 3 -> 3rd

// count == 4 -> 4th

<SelectOrdinal value={count} one="#st" two="#nd" few="#rd" other="#th" />;
```

Available Props:

| Prop name   | Type   | Description                                                  |
| ----------- | ------ | ------------------------------------------------------------ |
| `value`     | number | *(required)* Value is mapped to plural form below            |
| `other`     | string | *(required)* general *plural* form                           |
| `offset`    | number | Offset of value for plural forms                             |
| `zero`      | string | Form for empty `value`                                       |
| `one`       | string | *Singular* form                                              |
| `two`       | string | *Dual* form                                                  |
| `few`       | string | *Paucal* form                                                |
| `many`      | string | *Plural* form                                                |
| `_<number>` | string | Exact match form, correspond to `=N` rule. (e.g: `_0`, `_1`) |

### `Select`[​](#select-1 "Direct link to select-1")

The `Select` JSX macro is used to handle different forms of a message based on a value. It's similar to the [`select`](#select) core macro, but is used in JSX elements.

```
import { Select } from "@lingui/react/macro";



// gender == "female"      -> Her book

// gender == "male"        -> His book

// gender == "non-binary"  -> Their book

<Select value={gender} _male="His book" _female="Her book" other="Their book" />;
```

Available Props:

| Prop name | Type   | Description                                            |
| --------- | ------ | ------------------------------------------------------ |
| `value`   | number | *(required)* Value determines which form is output     |
| `other`   | number | *(required)* Default, catch-all form                   |
| `_<case>` | string | Form for specific case                                 |
| `id`      | string | Custom message ID                                      |
| `comment` | string | Comment for translators                                |
| `context` | string | Allows to extract the same messages with different IDs |
| `render`  | func   | Custom render callback to render translation           |

The select cases except `other` should be prefixed with underscore: `_male` or `_female`.

### `useLingui`[​](#uselingui "Direct link to uselingui")

The `useLingui` React macro gives access to a [`t`](https://lingui.dev/ref/macro.md#t) macro that is bound to the local `i18n` object passed from the React context.

It returns an object with the following content:

| Key                | Type                  | Description                                                       |
| ------------------ | --------------------- | ----------------------------------------------------------------- |
| `i18n`             | `I18n`                | The `I18n` object instance passed to `I18nProvider`               |
| `t`                | `t`                   | Reference to the `t` macro described above                        |
| `defaultComponent` | `React.ComponentType` | the same `defaultComponent` passed to `I18nProvider`, if provided |

Example usage:

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



function MyComponent() {

  const { t } = useLingui();

  const a = t`Text`;

}



// ↓ ↓ ↓ ↓ ↓ ↓



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



function MyComponent() {

  const { _ } = useLingui();

  const a = _(

    /** i18n */

    {

      id: "xeiujy",

      message: "Text",

    }

  );

}
```

caution

The `useLingui` React macro is available from **Lingui v5**.

## Important Notes[​](#important-notes "Direct link to Important Notes")

### Using Macros[​](#using-macros "Direct link to Using Macros")

All Core Macros cannot be used at the module level:

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



// ❌ Bad! This won't work because the `t` macro is used at the module level.

// The `t` macro returns a string, and once this string is assigned, it won't react to locale changes.

const colors = [t`Red`, t`Orange`, t`Yellow`, t`Green`];



// ✅ Good! Every time the function is executed, the `t` macro will be re-executed as well,

// and the correctly translated color labels will be returned.

function getColors() {

  return [t`Red`, t`Orange`, t`Yellow`, t`Green`];

}
```

tip

There is an [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) rule designed to check for this misuse: [`t-call-in-function`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/t-call-in-function.md).

A better option would be to use the [Lazy Translations](https://lingui.dev/guides/lazy-translations.md) pattern.

### Global `i18n` Instance[​](#global-i18n-instance "Direct link to global-i18n-instance")

When you use the [`t`](#t) macro (or [`plural`](#plural), [`select`](#select), [`selectOrdinal`](#selectordinal)), it uses a global [`i18n`](https://lingui.dev/ref/core.md#i18n) instance. While this generally works, there are situations, such as server-side rendering (SSR) applications, where it may not be the best solution.

For better control and flexibility, it's a good idea to avoid the global `i18n` instance and instead use a specific instance tailored to your needs:

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

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



export function showAlert(i18n) {

  alert(i18n.t(msg`...`));

}



function MyComponent() {

  // Get i18n instance from React Context

  const { i18n } = useLingui();



  // Pass the instance from outside

  showAlert(i18n);

}
```

## More Examples[​](#more-examples "Direct link to More Examples")

### Examples of JS macros[​](#examples-of-js-macros "Direct link to Examples of JS macros")

```
t`Refresh inbox`;



// ↓ ↓ ↓ ↓ ↓ ↓



i18n._(

  /** i18n */ {

    id: "EsCV2T",

    message: "Refresh inbox",

  }

);
```

```
customI18n._(msg(`Refresh inbox`));



// ↓ ↓ ↓ ↓ ↓ ↓



customI18n._(

  /** i18n */ {

    id: "EsCV2T",

    message: "Refresh inbox",

  }

);
```

```
t(customI18n)`Attachment ${name} saved`;



// ↓ ↓ ↓ ↓ ↓ ↓



customI18n._(

  /** i18n */ {

    id: "nwR43V",

    message: "Attachment {name} saved",

    values: { name },

  }

);
```

```
plural(count, {

  one: "# Message",

  other: "# Messages",

});



// ↓ ↓ ↓ ↓ ↓ ↓



i18n._(

  /** i18n */ {

    id: "4w2nim",

    message: "{count, plural, one {# Message} other {# Messages}}",

    values: { count },

  }

);
```

```
t({

  id: "msg.refresh",

  message: "Refresh inbox",

});



// ↓ ↓ ↓ ↓ ↓ ↓



i18n._(

  /** i18n */ {

    id: "msg.refresh",

    message: "Refresh inbox",

  }

);
```

```
const msg = defineMessage`Refresh inbox`;



// ↓ ↓ ↓ ↓ ↓ ↓



const msg = /** i18n */ {

  id: "EsCV2T",

  message: "Refresh inbox",

};
```

```
const msg = defineMessage({

  id: "msg.refresh",

  message: "Refresh inbox",

});



// ↓ ↓ ↓ ↓ ↓ ↓



const msg = /** i18n */ {

  id: "msg.refresh",

  message: "Refresh inbox",

};
```

```
const msg = defineMessage({

  id: "msg.plural",

  message: plural(count, {

    one: "# Message",

    other: "# Messages",

  }),

});



// ↓ ↓ ↓ ↓ ↓ ↓



const msg = /** i18n */ {

  id: "msg.plural",

  message: "{count, plural, one {# Message} other {# Messages}}",

  values: { count },

};
```

### Examples of JSX macros[​](#examples-of-jsx-macros "Direct link to Examples of JSX macros")

```
<Trans>Attachment {name} saved</Trans>



// ↓ ↓ ↓ ↓ ↓ ↓



<Trans

   id={"nwR43V"}

   message="Attachment {name} saved"

   values={{ name }}

/>
```

```
<Plural

   value={count}

   one="# Message"

   other="# Messages"

/>



// ↓ ↓ ↓ ↓ ↓ ↓



<Trans

   id={"4w2nim"}

   message="{count, plural, one {# Message} other {# Messages}}"

   values={{ count }}

/>
```

```
<Trans id="msg.refresh">

   Refresh inbox

</Trans>



// ↓ ↓ ↓ ↓ ↓ ↓



<Trans

   id="msg.refresh"

   message="Refresh inbox"

/>
```


---

# Metro Transformer

[Metro bundler](https://metrobundler.dev/) is a JavaScript bundler used in React Native apps. The `@lingui/metro-transformer` offers an alternative to the [`lingui compile`](https://lingui.dev/ref/cli.md#compile) command: a transformer that enables Metro to compile `.po` files on the fly.

The transformer enables you to `import` `.po` files directly, instead of running `lingui compile` and `import`ing the resulting JavaScript (or TypeScript) files.

## Installation[​](#installation "Direct link to Installation")

> Only Expo SDK 50 and React Native v0.73.0 or newer are supported.

Install `@lingui/metro-transformer` as a development dependency:

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/metro-transformer
```

```
pnpm add --save-dev @lingui/metro-transformer
```

Set up the transformer in your `metro.config.js` by specifying [`babelTransformerPath`](https://metrobundler.dev/docs/configuration/#babeltransformerpath) and updating `sourceExts`.

If you need to combine multiple transformers, use [this approach](https://stackoverflow.com/a/57660231/2070942):

<!-- -->

* Expo
* Plain React Native

metro.config.js

```
// Learn more https://docs.expo.io/guides/customizing-metro

const { getDefaultConfig } = require("expo/metro-config");



const config = getDefaultConfig(__dirname);

const { transformer, resolver } = config;



config.transformer = {

  ...transformer,

  babelTransformerPath: require.resolve("@lingui/metro-transformer/expo"),

};

config.resolver = {

  ...resolver,

  sourceExts: [...resolver.sourceExts, "po", "pot"],

};



module.exports = config;
```

metro.config.js

```
const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");



const defaultConfig = getDefaultConfig(__dirname);

const { assetExts, sourceExts } = defaultConfig.resolver;



/**

 * Metro configuration

 * https://reactnative.dev/docs/metro

 *

 * @type {import('metro-config').MetroConfig}

 */

const config = {

  transformer: {

    babelTransformerPath: require.resolve("@lingui/metro-transformer/react-native"),

  },

  resolver: {

    sourceExts: [...sourceExts, "po", "pot"],

  },

};



module.exports = mergeConfig(defaultConfig, config);
```

## Usage[​](#usage "Direct link to Usage")

tip

Take a look at the [example app](https://github.com/lingui/js-lingui/tree/main/examples/react-native) that uses the transformer. The transformer only supports catalogs based on `po` and `pot` files.

The library is currently in beta. If you encounter any issues, please [report them](https://github.com/lingui/js-lingui/issues).

1. Import `.po` files directly in your code:

   ```
   -import { messages } from "./src/locales/en/messages.ts";

   +import { messages } from "./src/locales/en/messages.po";
   ```

2. If you are using TypeScript, you need to add `.po` file declaration so that TypeScript understands the file extension:

   src/po-types.d.ts

   ```
   declare module "*.po" {

     import type { Messages } from "@lingui/core";

     export const messages: Messages;

   }
   ```

3. Restart Metro bundler with `expo start -c` or `yarn start --reset-cache` to clear the transformer cache.

4. Profit! 🎉

danger

Whenever you make a change to the Lingui config file (this should not happen often), restart Metro bundler.

## See Also[​](#see-also "Direct link to See Also")

* [React Native i18n Tutorial](https://lingui.dev/tutorials/react-native.md)
* [Lingui React Native Example App](https://github.com/lingui/js-lingui/tree/main/examples/react-native)


---

# React API Reference

The Lingui React API, provided by the `@lingui/react` package, integrates Lingui's core JavaScript functionality directly into React, extending React components with the ability to dynamically manage localization.

This API provides React-specific components that automatically update the user interface when the active language or interpolated variables change, simplifying translation management and reactivity in the application.

## Installation[​](#installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add @lingui/react
```

```
pnpm add @lingui/react
```

## Rendering of Translations[​](#rendering-translations "Direct link to Rendering of Translations")

All i18n components render translations as plain text by default, without a wrapping tag. You can customize this behavior in two ways:

* Globally: Set the `defaultComponent` prop on the [`I18nProvider`](#i18nprovider) component.
* Locally: Use the `render` or `component` props on individual i18n components.

### Global Configuration[​](#global-configuration "Direct link to Global Configuration")

You can set a default rendering component using the `defaultComponent` prop in [`I18nProvider`](#i18nprovider). This is especially useful in cases like React Native, where you may want translations to be rendered inside a `<Text>` component by default.

### Local Configuration[​](#local-configuration "Direct link to Local Configuration")

You can customize how translations are rendered locally within individual i18n components using the following props:

| Prop name   | Type                                 | Description                                                   |
| ----------- | ------------------------------------ | ------------------------------------------------------------- |
| `className` | string                               | Class name to be added to `<span>` element                    |
| `render`    | Function(props) -> Element \| `null` | Custom render callback to render translation                  |
| `component` | Component \| `null`                  | React component to wrap the translation                       |
| `comment`   | string                               | Comment picked up by extractor to provide translation context |

The `className` prop is applicable only to built-in components when the `render` prop is specified as a string.

When using the `render` callback, it accepts an object of type `TransRenderProps` as an argument:

```
type TransRenderProps = {

  id: string;

  translation: React.ReactNode;

  children: React.ReactNode;

  message?: string | null;

};
```

* `id` - The message ID.
* `translation` - The translated message.
* `children` - The same as `translation`, provided for compatibility with components that expect a `children` prop.
* `message` - The compiled message (generally not needed).

If you choose to use the `component` prop, the same object will be passed as a prop to your custom component. This allows you to access the necessary information for rendering translations directly within your component.

#### Important Notes[​](#important-notes "Direct link to Important Notes")

* You cannot use both `render` and `component` props simultaneously.
* Both `render` and `component` can be set to `null` to override the global `defaultComponent` and render a string without a wrapping component.
* The `component` supports nested elements with the `asChild` pattern.

#### Examples[​](#examples "Direct link to Examples")

Using a custom component:

```
import { Text } from "react-native";



<Trans component={Text}>Link to docs</Trans>;

// renders as <Text>Link to docs</Text>
```

Using render prop for custom rendering logic:

```
<Trans render={({ translation }) => <Icon label={translation} />}>Sign in</Trans>

// renders as <Icon label="Sign in" />
```

## Lingui Context[​](#lingui-context "Direct link to Lingui Context")

Message catalogs and the active locale are provided through the context in the [`I18nProvider`](#i18nprovider). You can access this context using the [`useLingui`](#uselingui) hook.

The `LinguiContext` object is exported from the `@lingui/react` package. While most users will not need to interact with it directly, it can be useful for advanced scenarios where the default behavior of `I18nProvider` doesn't meet your specific needs.

### `I18nProvider`[​](#i18nprovider "Direct link to i18nprovider")

The `I18nProvider` provides Lingui context to all components in the subtree. It should be rendered as top-level component of your application.

It ensures that its children are only rendered after a locale has been activated, guaranteeing that any components relying on `i18n` have access to the translations. Additionally, the `I18nProvider` subscribes to change events emitted by the `i18n` object, automatically re-rendering all components that consume the Lingui context whenever messages are updated or a new locale is activated.

| Prop name          | Type                  | Description                                                                    |
| ------------------ | --------------------- | ------------------------------------------------------------------------------ |
| `i18n`             | `I18n`                | The `I18n` object instance (usually the one imported from `@lingui/core`)      |
| `children`         | `React.ReactNode`     | React Children node                                                            |
| `defaultComponent` | `React.ComponentType` | A React component within which translation strings will be rendered (optional) |

The `defaultComponent` serves the same purpose as the `component` prop in other i18n components. For a detailed explanation of how translations are rendered, see the [Rendering of Translations](#rendering-translations) section at the beginning of this document.

#### Examples[​](#examples-1 "Direct link to Examples")

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

  );

};
```

### `useLingui`[​](#uselingui "Direct link to uselingui")

The `useLingui` hook provides access to the Lingui context. It returns an object with the following properties:

| Key                | Type                  | Description                                                                                  |
| ------------------ | --------------------- | -------------------------------------------------------------------------------------------- |
| `i18n`             | `I18n`                | The `I18n` object instance that you passed to `I18nProvider`                                 |
| `_`                | `I18n[_]`             | Reference to the [`i18n._`](https://lingui.dev/ref/core.md#i18n._) function, explained below |
| `defaultComponent` | `React.ComponentType` | The same `defaultComponent` you passed to `I18nProvider`, if provided                        |

Components that use `useLingui` hook will re-render when locale and / or catalogs change. However, the reference to the `i18n` object is stable and doesn't change between re-renders. This can lead to unexpected behavior with memoization (see [memoization pitfall](https://lingui.dev/guides/lazy-translations.md#memoization-pitfall)).

To alleviate the issue, `useLingui` provides the `_` function, which is the same as [`i18n._`](https://lingui.dev/ref/core.md#i18n._) but *its reference changes* with each update of the Lingui context. Thanks to that, you can safely use this `_` function as a hook dependency:

```
import React from "react";

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

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



const CurrentLocale = () => {

  const { _, i18n } = useLingui();



  return (

    <span>

      {_(msg`Current locale`)}: {i18n.locale}

    </span>

  );

};
```

tip

There is a [macro version](https://lingui.dev/ref/macro.md#uselingui) of the `useLingui` hook which supports all features of the [`t` macro](https://lingui.dev/ref/macro.md#t) and uses the runtime `useLingui` hook (from `@lingui/react`) under the hood:

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



const CurrentLocale = () => {

  const { t } = useLingui();



  const userName = "Tim";

  return <span>{t`Hello ${userName}`}</span>;

};
```

You also can safely use the returned `t` function in a dependency array of React hooks.

## Components[​](#components "Direct link to Components")

The `@lingui/react` package provides the `Trans` component for rendering translations in your application. It is a low-level component that allows you to render translations with dynamic values and components.

caution

While this component is available, you will likely find [Macros](https://lingui.dev/ref/macro.md) to be more convenient and developer-friendly. Macros simplify the translation process and reduce boilerplate code.

This section serves as a reference for those who prefer to use the components directly.

### `Trans`[​](#trans "Direct link to trans")

| Prop name | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `id`      | `string` | Key, the message ID                       |
| `message` | `string` | Default message                           |
| `values`  | `object` | Variables to interpolate into the message |

The `values` and `components` props allow to pass dynamic values and components used for formatting the translation. In addition, the `comment` prop provides context to translators, helping them to understand the intent behind the message.

tip

Import the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro instead if you use macros. It will be transformed into the runtime `Trans` component automatically:

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

<Trans>Refresh inbox</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id="EsCV2T" message="Refresh inbox" />;
```

It's also possible to use the `Trans` component directly without macros. In this case `id` identifies the message to be translated.

#### Examples[​](#examples-2 "Direct link to Examples")

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

  );

};
```

#### Plurals[​](#plurals "Direct link to Plurals")

If for some reason you cannot use [Macros](https://lingui.dev/ref/macro.md), you can render plurals using the simple `Trans` component by passing the [ICU MessageFormat](https://lingui.dev/guides/message-format.md) string as the `message` prop:

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

    />

  );

};
```


---

# Solid API Reference

The Lingui Solid API, provided by the `@lingui/solid` package, integrates Lingui's core JavaScript functionality directly into Solid, extending Solid components with the ability to dynamically manage localization.

This API provides Solid-specific components that automatically update the user interface when the active language or interpolated variables change, simplifying translation management and reactivity in the application.

## Installation[​](#installation "Direct link to Installation")

* npm
* Yarn
* pnpm

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

```
yarn add @lingui/core @lingui/solid
```

```
pnpm add @lingui/core @lingui/solid
```

## `defineConfig`[​](#defineconfig "Direct link to defineconfig")

We recommend using `defineConfig` from `@lingui/solid/config` to configure Lingui for Solid projects. It applies the Solid-specific settings, so you don't need to configure them manually.

lingui.config.ts

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



export default defineConfig({

  locales: ["en", "cs"],

  sourceLocale: "en",

  catalogs: [

    {

      path: "src/locales/{locale}",

      include: ["src"],

    },

  ],

});
```

It is equivalent to configuring the Solid-specific options manually:

lingui.config.ts

```
export default {

  locales: ["en", "cs"],

  sourceLocale: "en",

  catalogs: [

    {

      path: "src/locales/{locale}",

      include: ["src"],

    },

  ],

  macro: {

    jsxPackage: ["@lingui/solid/macro"],

    jsxRuntime: "solid",

  },

  runtimeConfigModule: {

    Trans: ["@lingui/solid", "Trans"],

    useLingui: ["@lingui/solid", "useLingui"],

  },

};
```

## Rendering of Translations[​](#rendering-translations "Direct link to Rendering of Translations")

All i18n components render translations as plain text by default, without a wrapping tag. You can customize this behavior in two ways:

* Globally: Set the `defaultComponent` prop on the [`I18nProvider`](#i18nprovider) component.
* Locally: Use the `render` or `component` props on individual i18n components.

### Global Configuration[​](#global-configuration "Direct link to Global Configuration")

You can set a default rendering component using the `defaultComponent` prop in [`I18nProvider`](#i18nprovider). This is especially useful in cases where you may want translations to be rendered inside a specific component by default.

### Local Configuration[​](#local-configuration "Direct link to Local Configuration")

You can customize how translations are rendered locally within individual i18n components using the following props:

| Prop name   | Type                                      | Description                                                   |
| ----------- | ----------------------------------------- | ------------------------------------------------------------- |
| `render`    | Function(props) -> `JSXElement` \| `null` | Custom render callback to render translation                  |
| `component` | `Component` \| `null`                     | Solid component to wrap the translation                       |
| `comment`   | `string`                                  | Comment picked up by extractor to provide translation context |

When using the `render` callback, it accepts an object of type `TransRenderProps` as an argument:

```
type TransRenderProps = {

  id: string;

  translation: JSXElement;

  children: JSXElement;

  message?: string | null;

};
```

* `id` - The message ID.
* `translation` - The translated message.
* `children` - The same as `translation`, provided for compatibility with components that expect a `children` prop.
* `message` - The compiled message (generally not needed).

If you choose to use the `component` prop, the same object will be passed as props to your custom component. This allows you to access the necessary information for rendering translations directly within your component.

#### Important Notes[​](#important-notes "Direct link to Important Notes")

* You cannot use both `render` and `component` props simultaneously.
* Both `render` and `component` can be set to `null` to override the global `defaultComponent` and render a string without a wrapping component.

#### Examples[​](#examples "Direct link to Examples")

Using a custom component:

```
const Label = (props) => <span class="label">{props.children}</span>;



<Trans component={Label}>Link to docs</Trans>;

// renders as <span class="label">Link to docs</span>
```

Using render prop for custom rendering logic:

```
<Trans render={({ translation }) => <Icon label={translation} />}>Sign in</Trans>

// renders as <Icon label="Sign in" />
```

## Lingui Context[​](#lingui-context "Direct link to Lingui Context")

Message catalogs and the active locale are provided through the context in the [`I18nProvider`](#i18nprovider). You can access this context using the [`useLingui`](#uselingui) hook.

The `LinguiContext` object is exported from the `@lingui/solid` package. While most users will not need to interact with it directly, it can be useful for advanced scenarios where the default behavior of `I18nProvider` doesn't meet your specific needs.

### `I18nProvider`[​](#i18nprovider "Direct link to i18nprovider")

The `I18nProvider` provides Lingui context to all components in the subtree. It should be rendered as top-level component of your application.

It ensures that its children are only rendered after a locale has been activated, guaranteeing that any components relying on `i18n` have access to the translations. Additionally, the `I18nProvider` subscribes to change events emitted by the `i18n` object, automatically updating computations that consume the Lingui context whenever messages are updated or a new locale is activated.

| Prop name          | Type                          | Description                                                                    |
| ------------------ | ----------------------------- | ------------------------------------------------------------------------------ |
| `i18n`             | `I18n`                        | The `I18n` object instance (usually the one imported from `@lingui/core`)      |
| `children`         | `JSXElement`                  | Solid children                                                                 |
| `defaultComponent` | `Component<TransRenderProps>` | A Solid component within which translation strings will be rendered (optional) |

The `defaultComponent` serves the same purpose as the `component` prop in other i18n components. For a detailed explanation of how translations are rendered, see the [Rendering of Translations](#rendering-translations) section at the beginning of this document.

#### Examples[​](#examples-1 "Direct link to Examples")

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

  );

};
```

### `useLingui`[​](#uselingui "Direct link to uselingui")

The `useLingui` hook provides access to the Lingui context. It returns an object with the following properties:

| Key                | Type                                    | Description                                                                                  |
| ------------------ | --------------------------------------- | -------------------------------------------------------------------------------------------- |
| `i18n`             | `Accessor<I18n>`                        | Accessor for the `I18n` object instance that you passed to `I18nProvider`                    |
| `_`                | `I18n["_"]`                             | Reference to the [`i18n._`](https://lingui.dev/ref/core.md#i18n._) function, explained below |
| `defaultComponent` | `Accessor<Component<TransRenderProps>>` | The same `defaultComponent` you passed to `I18nProvider`, if provided                        |

The `i18n` value returned from `useLingui` is a Solid signal. Call `i18n()` inside the JSX or computation that should react to locale and / or catalog updates.

To keep translations reactive, `useLingui` provides the `_` function, which is the same as [`i18n._`](https://lingui.dev/ref/core.md#i18n._) but bound to the current Lingui context. You can safely call this `_` function inside Solid computations:

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

import { useLingui } from "@lingui/solid";



const CurrentLocale = () => {

  const { _, i18n } = useLingui();



  return (

    <span>

      {_(msg`Current locale`)}: {i18n().locale}

    </span>

  );

};
```

tip

There is a [macro version](https://lingui.dev/ref/macro.md#uselingui) of the `useLingui` hook which supports all features of the [`t` macro](https://lingui.dev/ref/macro.md#t) and uses the runtime `useLingui` hook (from `@lingui/solid`) under the hood:

```
import { useLingui } from "@lingui/solid/macro";



const CurrentLocale = () => {

  const { t } = useLingui();



  const userName = "Tim";

  return <span>{t`Hello ${userName}`}</span>;

};
```

## Components[​](#components "Direct link to Components")

The `@lingui/solid` package provides the `Trans` component for rendering translations in your application. It is a low-level component that allows you to render translations with dynamic values and components.

caution

While this component is available, you will likely find [Macros](https://lingui.dev/ref/macro.md) to be more convenient and developer-friendly. Macros simplify the translation process and reduce boilerplate code.

This section serves as a reference for those who prefer to use the components directly.

### `Trans`[​](#trans "Direct link to trans")

| Prop name | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `id`      | `string` | Key, the message ID                       |
| `message` | `string` | Default message                           |
| `values`  | `object` | Variables to interpolate into the message |

The `values` and `components` props allow to pass dynamic values and components used for formatting the translation. In addition, the `comment` prop provides context to translators, helping them to understand the intent behind the message.

tip

Import the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro instead if you use macros. It will be transformed into the runtime `Trans` component automatically:

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

<Trans>Refresh inbox</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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

<Trans id="EsCV2T" message="Refresh inbox" />;
```

It's also possible to use the `Trans` component directly without macros. In this case `id` identifies the message to be translated.

#### Examples[​](#examples-2 "Direct link to Examples")

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

  );

};
```

#### Plurals[​](#plurals "Direct link to Plurals")

If for some reason you cannot use [Macros](https://lingui.dev/ref/macro.md), you can render plurals using the simple `Trans` component by passing the [ICU MessageFormat](https://lingui.dev/guides/message-format.md) string as the `message` prop:

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



const CarCount = (props) => {

  return (

    <Trans

      id="application.pages.carsList"

      message="{count, plural, =1 {# car} other {# cars}}"

      values={{ count: props.cars.length }}

    />

  );

};
```


---

# SWC Plugin

[SWC](https://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools.

If you're using SWC in your project, you can opt for the `@lingui/swc-plugin`. This plugin, designed for SWC, is a Rust version of [Lingui Macros](https://lingui.dev/ref/macro.md).

[![npm-version](https://img.shields.io/npm/v/@lingui/swc-plugin?logo=npm\&cacheSeconds=1800)](https://www.npmjs.com/package/@lingui/swc-plugin) [![npm-downloads](https://img.shields.io/npm/dt/@lingui/swc-plugin?cacheSeconds=500)](https://www.npmjs.com/package/@lingui/swc-plugin)

## SWC Compatibility[​](#swc-compatibility "Direct link to SWC Compatibility")

SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions [is not guaranteed](https://github.com/swc-project/swc/issues/5060). You need to choose an appropriate version of the `@lingui/swc-plugin` to match the compatible `@swc/core` version.

tip

It is recommended to check the [plugins.swc.rs](https://plugins.swc.rs/) site to find the compatible version.

## Installation[​](#installation "Direct link to Installation")

Install `@lingui/swc-plugin` as a development dependency:

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/swc-plugin
```

```
pnpm add --save-dev @lingui/swc-plugin
```

To ensure that the resolved version of `@swc/core` is one of the supported versions, you can use the `resolutions` field in the `package.json` file, which is supported by Yarn:

package.json

```
"resolutions": {

  "@swc/core": "1.3.56"

}
```

or `overrides` for >npm\@8.3

package.json

```
"overrides": {

  "@swc/core": "1.3.56"

}
```

## Usage[​](#usage "Direct link to Usage")

Add the following configuration to your [`.swcrc`](https://swc.rs/docs/configuration/swcrc) file:

.swcrc

```
{

  "$schema": "https://json.schemastore.org/swcrc",

  "jsc": {

    "experimental": {

      "plugins": [

        [

          "@lingui/swc-plugin",

          {

            // Additional Configuration

          }

        ]

      ]

    }

  }

}
```

If you use Next.js, add the following to your `next.config.js`:

next.config.js

```
/** @type {import('next').NextConfig} */

const nextConfig = {

  reactStrictMode: true,

  experimental: {

    swcPlugins: [

      [

        "@lingui/swc-plugin",

        {

          // Additional Configuration

        },

      ],

    ],

  },

};



module.exports = nextConfig;
```

## Additional Configuration[​](#additional-configuration "Direct link to Additional Configuration")

### Runtime Modules Configuration[​](#runtime-modules-configuration "Direct link to Runtime Modules Configuration")

You can configure the plugin by passing the `runtimeModules` option. This option is an object that maps runtime module names to their corresponding module paths and export names. It is essential for macros, which rely on referencing the global `i18n` object.

```
[

  "@lingui/swc-plugin",

  {

    "runtimeModules": {

      "i18n": ["@lingui/core", "i18n"],

      "trans": ["@lingui/react", "Trans"]

    }

  }

]
```

For more details, refer to the [Runtime Configuration](https://lingui.dev/ref/conf.md#runtimeconfigmodule) section of the documentation.

### JSX Placeholder Naming in `<Trans>`[​](#jsx-placeholder-naming-in-trans "Direct link to jsx-placeholder-naming-in-trans")

You can configure semantic JSX placeholder names for elements inside `<Trans>` with:

* `jsxPlaceholderAttribute` - custom attribute used to set an explicit placeholder name in JSX (for example, `_t="link"`).
* `jsxPlaceholderDefaults` - default placeholder names per JSX tag.

```
[

  "@lingui/swc-plugin",

  {

    "jsxPlaceholderAttribute": "_t",

    "jsxPlaceholderDefaults": {

      "a": "link",

      "strong": "bold"

    }

  }

]
```

For behavior details and examples, see [`macro.jsxPlaceholderAttribute`](https://lingui.dev/ref/conf.md#macrojsxplaceholderattribute) and [`macro.jsxPlaceholderDefaults`](https://lingui.dev/ref/conf.md#macrojsxplaceholderdefaults).

### Descriptor Fields[​](#descriptor-fields "Direct link to Descriptor Fields")

The `descriptorFields` option controls which message descriptor fields are preserved in the transformed code.

* `"auto"` (default): In production (`NODE_ENV === "production"`), keeps only the `id`. Otherwise, keeps all fields.
* `"all"`: Keeps `id`, `message`, `context`, and `comment`.
* `"id-only"`: Strips everything except `id`. Most optimized for production.
* `"message"`: Keeps `id`, `message`, and `context` (but not `comment`).

For example, to keep `message` and `context` in production builds:

```
[

  "@lingui/swc-plugin",

  {

    "descriptorFields": "message"

  }

]
```

## Examples[​](#examples "Direct link to Examples")

* [React with Vite and SWC](https://github.com/lingui/js-lingui/tree/main/examples/vite-project-react-swc)
* [Next.js with SWC](https://github.com/lingui/js-lingui/tree/main/examples/nextjs-swc)

info

If you would like to suggest a new feature or report a bug, please [open an issue](https://github.com/lingui/swc-plugin/issues) on the GitHub repository.


---

# Vite Plugin

Vite is a blazing fast frontend build tool powering the next generation of web applications.

The `@lingui/vite-plugin` is a Vite plugin that compiles Lingui catalogs on the fly, can transform Lingui macros natively and provides the necessary configuration for seamless integration with Vite.

[![npm-version](https://img.shields.io/npm/v/@lingui/vite-plugin?logo=npm\&cacheSeconds=1800)](https://www.npmjs.com/package/@lingui/vite-plugin) [![npm-downloads](https://img.shields.io/npm/dt/@lingui/vite-plugin?cacheSeconds=500)](https://www.npmjs.com/package/@lingui/vite-plugin)

## Installation[​](#installation "Direct link to Installation")

Install `@lingui/vite-plugin` as a development dependency:

* npm
* Yarn
* pnpm

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

```
yarn add --dev @lingui/vite-plugin
```

```
pnpm add --save-dev @lingui/vite-plugin
```

For a complete installation guide, see [Installation and Setup](https://lingui.dev/installation.md#vite).

## Usage[​](#usage "Direct link to Usage")

To integrate Lingui with Vite, add the `@lingui/vite-plugin` inside your `vite.config.ts` as follows:

vite.config.ts

```
import { UserConfig } from "vite";

import { lingui } from "@lingui/vite-plugin";



const config: UserConfig = {

  plugins: [lingui({ macroTransform: true })],

};
```

With `macroTransform: true`, the plugin also transforms Lingui macros, so you don't need a separate Babel or SWC plugin for Lingui. This is the recommended setup. See [Native Macro Transform](#native-macro-transform) for details.

Then use [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports) in your code to load only necessary catalog:

```
export async function dynamicActivate(locale: string) {

  const { messages } = await import(`./locales/${locale}.po`);



  i18n.load(locale, messages);

  i18n.activate(locale);

}
```

Remember that the file extension is mandatory.

tip

If you are using a format that has a different extension than `*.po`, you need to specify the `?lingui` suffix:

```
const { messages } = await import(`./locales/${language}.json?lingui`);
```

## Native Macro Transform[​](#native-macro-transform "Direct link to Native Macro Transform")

The plugin can transform Lingui macros (`t`, `msg`, `<Trans>`, and others) natively using [`@lingui/native-tools`](https://www.npmjs.com/package/@lingui/native-tools), a Rust and SWC based toolchain. When enabled, `@rolldown/plugin-babel` with `linguiTransformerBabelPreset`, `@lingui/babel-plugin-lingui-macro` or `@lingui/swc-plugin` are no longer needed for Lingui macros.

The native transform is up to 2.5x faster than SWC with the Lingui plugin and up to 29x faster than Babel. It is disabled by default and will become the default in the next major release.

vite.config.ts

```
import { defineConfig } from "vite";

import react from "@vitejs/plugin-react";

import { lingui } from "@lingui/vite-plugin";



export default defineConfig({

  plugins: [react(), lingui({ macroTransform: true })],

});
```

This works with `@vitejs/plugin-react`, `@vitejs/plugin-react-swc` and Vite 8+ with Rolldown. The transform runs in the `pre` stage and only touches files that import Lingui macros.

caution

The native transform doesn't support [`macro.jsxRuntime: "solid"`](https://lingui.dev/ref/conf.md#macrojsxruntime) yet and fails with an error when it is set. Solid projects should keep transforming macros with `@lingui/babel-plugin-lingui-macro`, see the [Solid tutorial](https://lingui.dev/tutorials/solid.md#configure-vite).

Macro options such as `macro.corePackage`, `macro.jsxPackage`, `macro.jsxPlaceholderAttribute`, `macro.jsxPlaceholderDefaults`, `macro.idPrefixLeader` and `runtimeConfigModule` are read from your [Lingui configuration](https://lingui.dev/ref/conf.md), so in most cases `true` is all you need.

Production builds emit `id`-only message descriptors, while development builds keep the `message` as well. This matches the behavior of the Babel and SWC plugins. To change it, set `descriptorFields` in the `macro` overrides, for example `"message"` to keep messages in production builds.

info

`@lingui/native-tools` ships prebuilt binaries for macOS, Linux, Windows and Android. There is no WASM fallback, so make sure your build environment matches one of the supported platforms. The binary is loaded lazily, only when `macroTransform` is enabled.

note

`lingui extract` still uses Babel by default. Use the [native extractor](https://lingui.dev/guides/custom-extractor.md#native-extractor) to extract without Babel as well.

### Options Reference[​](#options-reference "Direct link to Options Reference")

`macroTransform` accepts `true` to enable the transform with default options, or an object to fine-tune it:

vite.config.ts

```
lingui({

  macroTransform: {

    macro: {

      jsxPlaceholderAttribute: "_t",

    },

    parser: {

      syntax: "typescript",

      decorators: true,

    },

  },

});
```

* `macro` - overrides for the macro options derived from your Lingui configuration. Accepts a partial [`LinguiMacroOptions`](https://www.npmjs.com/package/@lingui/native-tools) object from `@lingui/native-tools`, for example `corePackage`, `jsxPackage`, `jsxPlaceholderAttribute`, `jsxPlaceholderDefaults`, `runtimeModules`, `idPrefixLeader` or `descriptorFields`. Explicit values take precedence over the values from `lingui.config`.
* `parser` - SWC parser options, the same as [`jsc.parser`](https://swc.rs/docs/configuration/compilation#jscparser) in `.swcrc`. The actual syntax (ECMAScript or TypeScript) and JSX support are inferred from the file name, Decorators are enabled by default. A custom `parser` replaces the defaults, so set `decorators: true` yourself if you need them.

## Options[​](#options "Direct link to Options")

### `failOnMissing`[​](#failonmissing "Direct link to failonmissing")

Fail the build when missing translations are detected.

* `true` or `"resolved"`: fail only if a translation is still missing after `fallbackLocales` are applied.
* `"catalog"`: fail if the target locale catalog itself has missing translations before `fallbackLocales` are applied.
* `false` or omitted: do not fail the build on missing translations.

### `failOnCompileError`[​](#failoncompileerror "Direct link to failoncompileerror")

Fail the build when message compilation produces errors.

### `macroTransform`[​](#macrotransform "Direct link to macrotransform")

Enable the native macro transform. Accepts `true` or an object with `macro` and `parser` overrides. Default: `false`. See [Native Macro Transform](#native-macro-transform).

## `linguiTransformerBabelPreset`[​](#linguitransformerbabelpreset "Direct link to linguitransformerbabelpreset")

If you use `@rolldown/plugin-babel`, `@lingui/vite-plugin` exports `linguiTransformerBabelPreset` as a convenience helper for macro transformation:

vite.config.ts

```
import { defineConfig } from "vite";

import react from "@vitejs/plugin-react";

import babel from "@rolldown/plugin-babel";

import { lingui, linguiTransformerBabelPreset } from "@lingui/vite-plugin";



export default defineConfig({

  plugins: [

    react(),

    lingui(),

    babel({

      presets: [linguiTransformerBabelPreset()],

    }),

  ],

});
```

The preset prints a notice recommending the native macro transform. Set the `LINGUI_SUPPRESS_BABEL_WARNING=1` environment variable to hide it. The preset is not deprecated, but the native transform will become the default in the next major release.

### Migrating to the Native Macro Transform[​](#migrating-to-the-native-macro-transform "Direct link to Migrating to the Native Macro Transform")

1. Enable the native transform: `lingui({ macroTransform: true })`.
2. Remove `linguiTransformerBabelPreset` from the `@rolldown/plugin-babel` presets. If Babel was only used for Lingui, remove `@rolldown/plugin-babel` entirely, together with `@lingui/babel-plugin-lingui-macro` if nothing else uses it.
3. If you keep `@rolldown/plugin-babel` for other presets (for example React Compiler), place `lingui()` before `babel()` in the `plugins` array so macros are transformed first.

vite.config.ts

```
import { defineConfig } from "vite";

import react from "@vitejs/plugin-react";

import { lingui } from "@lingui/vite-plugin";



export default defineConfig({

  plugins: [react(), lingui({ macroTransform: true })],

});
```

## See Also[​](#see-also "Direct link to See Also")

* [Dynamic Loading](https://lingui.dev/guides/dynamic-loading-catalogs.md)
* [Dynamic Import in Vite](https://vitejs.dev/guide/features.html#dynamic-import)


---

# Crowdin

![Crowdin agile localization for developers](https://support.crowdin.com/assets/logos/crowdin-dark-symbol.png#gh-light-mode-only)![Crowdin agile localization for developers](https://support.crowdin.com/assets/logos/symbol/png/crowdin-symbol-cWhite.png#gh-dark-mode-only)

Crowdin is a localization management platform that helps translate your LinguiJS-based product. Automate localization, release several multilingual versions of your app simultaneously, and provide an enhanced experience for your global customers.

[Website](https://crowdin.com/?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev) | [GitHub](https://github.com/crowdin) | [Support](https://crowdin.com/contacts?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev)

## Features[​](#features "Direct link to Features")

### Keep all translations in one place while connecting your teams via Crowdin[​](#keep-all-translations-in-one-place-while-connecting-your-teams-via-crowdin "Direct link to Keep all translations in one place while connecting your teams via Crowdin")

Connect with your content, marketing, and translation teams in one collaborative space:

* Screenshots for additional context.
* Highlight HTML, placeholders, plurals, and more.
* Describe the context and set character limits to ensure the translation fits the UI.
* All translations are done online or can be uploaded to the platform.
* Jira integration to notify you about source string issues.
* Tips for translators to ensure there is no extra space or broken code.

### Ship faster with localization running in parallel[​](#ship-faster-with-localization-running-in-parallel "Direct link to Ship faster with localization running in parallel")

Keep developing new features and improvements while translators receive new texts in real-time. Release multilingual versions for customers around the globe simultaneously.

### Release your product in several languages at once[​](#release-your-product-in-several-languages-at-once "Direct link to Release your product in several languages at once")

Help users from different regions use the latest version of your product in their language:

* Get feature branches translated independently from the master branch.
* Translators work together in one place to boost productivity.
* Never deal with translations in spreadsheets or email attachments.
* Source texts are updated for translators automatically and in real-time.
* Automatically pull completed translations that are ready to be merged.

### Seamlessly integrate localization during any phase of your development cycle[​](#seamlessly-integrate-localization-during-any-phase-of-your-development-cycle "Direct link to Seamlessly integrate localization during any phase of your development cycle")

Automate the integration of source texts and translations between Crowdin and your source code with one-click integration or customizable solutions.

### Define your translation strategy[​](#define-your-translation-strategy "Direct link to Define your translation strategy")

Decide who will translate your content:

* Invite your team of translators (in-house translators, freelancers, or translation agencies you already work with).
* Order professional translations from a vendor (translation agency) from Crowdin Vendors Marketplace.
* Configure machine translation engines.
* Engage your community.

### VCS: GitHub, GitLab, Bitbucket[​](#vcs-github-gitlab-bitbucket "Direct link to VCS: GitHub, GitLab, Bitbucket")

Source strings are pulled automatically and are always up to date for your translators. Translated content is automatically pushed to your repository as a request.

![Automatically pull source strings to Crowdin and push translated content to your repository](/assets/images/Crowdin__js-lingui-vcs-a0145c95baafee2bd889e6d08d7ec993.png)

## CLI[​](#cli "Direct link to CLI")

Connect cross-platform [Crowdin CLI](https://crowdin.github.io/crowdin-cli/) directly to your code repository and never deal with localization files manually again.

With Crowdin CLI, you can:

* Automate the process of updating your source files in your Crowdin project.
* Download translations from Crowdin and automatically save them in the correct locations.
* Upload all your existing translations to Crowdin in minutes.

### Create the `crowdin.yml` configuration file[​](#create-the-crowdinyml-configuration-file "Direct link to create-the-crowdinyml-configuration-file")

crowdin.yml

```
project_id: "123456" # Your Crowdin project ID

api_token_env: CROWDIN_PERSONAL_TOKEN



preserve_hierarchy: true



files: # Paths to the source and translation files

  - source: /**/locales/en/*

    translation: /**/locales/%two_letters_code%/%original_file_name%
```

### Install the Crowdin CLI as an npm package[​](#install-the-crowdin-cli-as-an-npm-package "Direct link to Install the Crowdin CLI as an npm package")

* npm
* Yarn
* pnpm

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

```
yarn add --dev @crowdin/cli
```

```
pnpm add --save-dev @crowdin/cli
```

### Add the synchronization scripts[​](#add-the-synchronization-scripts "Direct link to Add the synchronization scripts")

Add the following scripts to your `package.json`:

package.json

```
{

  "scripts": {

    "crowdin": "crowdin",

    "sync": "crowdin push && crowdin pull",

    "sync:sources": "crowdin push",

    "sync:translations": "crowdin pull"

  }

}
```

### Configuration[​](#configuration "Direct link to Configuration")

Set the `CROWDIN_PERSONAL_TOKEN` env variable on your computer, to allow the CLI to authenticate with the Crowdin API.

#### Usage[​](#usage "Direct link to Usage")

Test that you can run the Crowdin CLI:

* npm
* Yarn
* pnpm

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

```
yarn crowdin --version
```

```
pnpm run crowdin --version
```

Upload all the source files to Crowdin:

* npm
* Yarn
* pnpm

```
npm run sync:sources
```

```
yarn sync:sources
```

```
pnpm run sync:sources
```

Download translation files from Crowdin:

* npm
* Yarn
* pnpm

```
npm run sync:translations
```

```
yarn sync:translations
```

```
pnpm run sync:translations
```

Upload sources to Crowdin and download translations from Crowdin:

* npm
* Yarn
* pnpm

```
npm run sync
```

```
yarn sync
```

```
pnpm run sync
```

To run other Crowdin CLI commands you can use the following command:

* npm
* Yarn
* pnpm

```
npm run crowdin <command> <options>
```

```
yarn crowdin <command> <options>
```

```
pnpm run crowdin <command> <options>
```

To see the full list of possible commands and options:

* npm
* Yarn
* pnpm

```
npm run crowdin -h
```

```
yarn crowdin -h
```

```
pnpm run crowdin -h
```

## Over-The-Air Content Delivery[​](#over-the-air-content-delivery "Direct link to Over-The-Air Content Delivery")

Over-the-Air Content Delivery is a feature that allows you to instantly update sources and translations in your mobile, server, desktop, or web apps with a single click without preparing a new release.

Visit the following pages to learn more about how to integrate Over-The-Air Content Delivery into your Lingui project:

* [Lingui tutorial - Crowdin OTA JS Client](https://crowdin.github.io/ota-client-js/tutorials/lingui/)
* [Lingui String Exporter - Crowdin Marketplace](https://store.crowdin.com/lingui-string-exporter?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev)

## API and Webhooks[​](#api-and-webhooks "Direct link to API and Webhooks")

Customize your experience. Automate and scale your localization workflow. Seamlessly add new content for translation to your Crowdin project, check translation status, merge new content, etc.

See the [API](https://support.crowdin.com/developer/api/?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev) and [Webhooks](https://support.crowdin.com/developer/webhooks/?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev) documentation for more information.

## Next Steps[​](#next-steps "Direct link to Next Steps")

To get started, register a [Crowdin.com](https://accounts.crowdin.com/register?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev) or [Crowdin Enterprise](https://accounts.crowdin.com/workspace/create?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev) account. Once you have signed up, [create your localization project](https://support.crowdin.com/creating-project/?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev).

Depending on how you'd like to work with Crowdin, you have the following options:

1. [Integrate Crowdin with GitHub](https://support.crowdin.com/github-integration/?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev).
2. Manage and synchronize your localization resources with [Crowdin CLI](https://developer.crowdin.com/cli-tool/?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev).
3. [Upload files for the test via UI](https://support.crowdin.com/uploading-files/?utm_source=lingui.dev\&utm_medium=referral\&utm_campaign=lingui.dev).


---

# Sync & Collaboration Tools

While Lingui provides a powerful API for managing your translations, it doesn't provide an integrated solution for managing synchronization and collaboration with your translators.

This guide covers tools that can help you manage your localization process. You may come across acronyms like TMS (Translation Management System) or CAT (Computer Aided Translation) that are sometimes used to describe these tools.

## Workflows[​](#workflows "Direct link to Workflows")

The easiest way to translate your application is to translate your message catalogs directly in a text editor, or with a tool like [Poedit](https://poedit.net).

This solution may be good enough when your application is small and doesn't evolve much, but it quickly becomes hard work as the number of sentences to translate and target languages to manage increases over time.

It becomes increasingly difficult and time-consuming to manage the back-and-forth with translators while keeping your application's message catalogs up to date with the current state of a codebase that does not stop evolving.

### Regular Workflow[​](#regular-workflow "Direct link to Regular Workflow")

![Translation workflow without sync and collaboration tool](/assets/images/without-collaboration-tool-c754b37fb89866426c7e758c06a9e8f7.svg)

This is the most basic workflow which involves sending the `.po` files to your translators (usually by email) and syncing them back manually into your application.

This workflow is manageable when your application is still quite small, doesn't contain a lot of text, and doesn't evolve much.

### Sync & Collaboration Tool Workflow[​](#sync--collaboration-tool-workflow "Direct link to Sync & Collaboration Tool Workflow")

![Translation workflow with sync and collaboration tool](/assets/images/with-collaboration-tool-0a2b67b7ad85e0a266ae26c5d3d2a8e6.svg)

When the amount of text to translate increases, and the number of target languages grows, it becomes more efficient to use a sync and collaboration tool to assist you with the management of your team of translators, and co-evolution between your code and the translated files.

Instead of manually sending and receiving many emails and fixing the inconsistencies with your code, a `sync` method is called and your `.po` and `.js` files are directly updated with the latest translations. Your translators will also be notified when there are new text to translate.

## Benefits[​](#benefits "Direct link to Benefits")

* **Synchronization**: unique `yarn sync` or `npm run sync` command to synchronize your project with all your translators and update your local `.po` and `.js` files with the latest translations.
* **Translation Interface**: provide a professional and flexible interface to translators.
* **Translation Memory**: assist translators by suggesting previously translated sentences that are similar.
* **Machine Translation**: auto-translate with Google Translate, DeepL, etc. and human-proofread later.
* **Smart Plural Management**: allows to translate `Message` and `Messages` instead of `{count, plural, one {Message} other {Messages}}`.
* **Consistency**: assist translators with `{variable}` interpolation and HTML formatting.

## Available Tools[​](#available-tools "Direct link to Available Tools")

* [Crowdin](https://lingui.dev/tools/crowdin.md)
* [Translation.io](https://lingui.dev/tools/translation-io.md)


---

# Translation.io

![Translation.io - Localization made simple for tech companies](https://translation.io/logo.png)

Translation.io is a professional synchronization and collaboration platform that will assist your team in the translation of your Lingui application.

[Website](https://translation.io/lingui) | [GitHub](https://github.com/translation/lingui) | <contact@translation.io>

## Features[​](#features "Direct link to Features")

### Smooth Team Management[​](#smooth-team-management "Direct link to Smooth Team Management")

Invite collaborators using their email or username, and assign them a role and a target language. They will be brought on board and kept informed about any new activity in their language.

![Smooth Team Management on Translation.io](https://translation.io/gifs/lingui/translation-collaborators.gif)

Learn more:

* [Fine-Grained Authorizations](https://translation.io/blog/fine-grained-authorization-and-role-management?default_stack=lingui)
* [Activity Digests](https://translation.io/blog/better-history-and-activity-email-digests?default_stack=lingui)

### Elegant Translation Process[​](#elegant-translation-process "Direct link to Elegant Translation Process")

Our interface was designed to be the most ergonomic way to translate. It provides translation suggestions (from [TM](https://en.wikipedia.org/wiki/Translation_memory), Google Translate or DeepL), context, discussion and history.

Keyboard shortcuts allow translators to stay focused on their work, visual hints indicate when something went wrong, for example when an interpolated variable or HTML tag is missing.

![Elegant Translation Process on Translation.io](https://translation.io/gifs/lingui/translation-interface.gif)

Learn more:

* [Keyboard Shortcuts](https://translation.io/blog/shortcuts-and-translation?default_stack=lingui)
* [History and Activity Digests](https://translation.io/blog/better-history-and-activity-email-digests?default_stack=lingui)

### Syntax Highlighting[​](#syntax-highlighting "Direct link to Syntax Highlighting")

Sometimes you have no choice but to confront your translators with HTML or interpolated variables. The problem is that translators do not necessarily know the meaning of these notations and may be tempted to translate them or may inadvertently alter them.

`Hello {name}` should never be translated as `Bonjour {nom}`, and several mechanisms are in place to ensure this, such as warnings and auto-completion:

![Syntax Highlighting warning on Translation.io](https://translation.io/_articles/translation/2019-10-11-highlighting-of-html-tags-and-interpolated-variables/highlight-interpolated-variable-lingui.png)

***

![Syntax Highlighting auto-completion on Translation.io](https://translation.io/gifs/lingui/translation-highlights.gif)

### Smart Plural Management[​](#smart-plural-management "Direct link to Smart Plural Management")

Lingui allows to write plurals using the [ICU MessageFormat](https://lingui.dev/guides/message-format.md) syntax that looks like this:

```
{count, plural, =0 {No messages}

                one {# message}

                other {# messages}}
```

But you can't ask a translator to understand this syntax, and he or she would be tempted to translate `one` or `other` keywords in other languages, breaking your code at the same time.

That's why plural syntaxes are deconstructed to make translation easier, and then reconstructed in the local `.po` files.

If the target language has more plural forms than the source language, examples are also provided to the translator, as it may be unclear which plural form the `few` or `other` keyword refers to in that specific target language (for instance, Czech has three plural forms).

![Smart Plural Management on Translation.io](/assets/images/translation-lingui-plural-forms-cfe7f08db002ef78fb4b12b5fb5a2f0f.png)

### Efficient Search[​](#efficient-search "Direct link to Efficient Search")

Our powerful search helps translators to maintain consistency of terms throughout their work. In addition, they are able to filter depending on a particular source file or context. To provide a more enjoyable experience, this lightning-fast search works without any page reloading.

![Efficient Search on Translation.io](https://translation.io/gifs/lingui/translation-search.gif)

Learn more:

* [Smart URLs](https://translation.io/blog/smart-urls-in-translation-interface?default_stack=lingui)

### Adaptive Workflows using Tags[​](#adaptive-workflows-using-tags "Direct link to Adaptive Workflows using Tags")

Our interface is flexible enough to adapt to your own translation workflows. Add custom tags to your segments and you'll be directly able to filter them. Moreover, these tags will appear in the statistics page so you can use them for reporting.

![Adaptive Workflows using Tags on Translation.io](https://translation.io/gifs/lingui/translation-tags.gif)

Learn more:

* [How to Use Tags](https://translation.io/blog/tags-work-better-as-a-team?default_stack=lingui)
* [Project Statistics](https://translation.io/blog/translation-project-statistics?default_stack=lingui)

## Installation[​](#installation "Direct link to Installation")

### Create your Lingui project[​](#create-your-lingui-project "Direct link to Create your Lingui project")

Create an account on [Translation.io](https://translation.io/lingui) and create a new Lingui project.

### Configure your application[​](#configure-your-application "Direct link to Configure your application")

Copy the `.linguirc` configuration file that was generated for you to the root of your application.

The configuration file looks like this:

.linguirc

```
{

  [...]

  "format": "po",

  "service": {

    "name": "TranslationIO",

    "apiKey": "abcdefghijklmnopqrstuvwxyz012345"

  }

}
```

The synchronization will then be part of the [`extract`](https://lingui.dev/ref/cli.md#extract) command.

### Add the following scripts[​](#add-the-following-scripts "Direct link to Add the following scripts")

Add these lines to your `package.json` to make your life easier.

package.json

```
{

  "scripts": {

    "sync": "lingui extract --overwrite && lingui compile",

    "sync_and_purge": "lingui extract --overwrite --clean && lingui compile"

  }

}
```

### Initialize your project[​](#initialize-your-project "Direct link to Initialize your project")

Initialize your project and upload your source text and potential existing translations with:

* npm
* Yarn
* pnpm

```
npm run sync
```

```
yarn sync
```

```
pnpm run sync
```

## Usage[​](#usage "Direct link to Usage")

### Sync[​](#sync "Direct link to Sync")

To send new translatable strings and get new translations from Translation.io, and at the same time generate the minified JavaScript catalog files, simply run:

* npm
* Yarn
* pnpm

```
npm run sync
```

```
yarn sync
```

```
pnpm run sync
```

### Sync and Purge[​](#sync-and-purge "Direct link to Sync and Purge")

If you need to remove unused strings from Translation.io, using the current branch as reference.

As the name says, this operation will also perform a sync at the same time.

**Warning**: all strings that are not present in the current local branch will be **permanently deleted from Translation.io**.

* npm
* Yarn
* pnpm

```
npm run sync_and_purge
```

```
yarn sync_and_purge
```

```
pnpm run sync_and_purge
```


---

# JavaScript Apps Internationalization

This tutorial will walk you through using Lingui's internationalization (i18n) features in a vanilla JavaScript application. We'll cover the essentials of the `@lingui/core` package, which handles all translation and message catalog management.

Example

If you're looking for a working solution, check out the [Vanilla JS example](https://github.com/lingui/js-lingui/tree/main/examples/js). This example application shows a complete setup using Lingui and vanilla JavaScript.

## Installing Lingui[​](#installing-lingui "Direct link to Installing Lingui")

1. Follow the [Installation and Setup](https://lingui.dev/installation.md) page for initial setup.
2. Install the [`@lingui/core`](https://lingui.dev/ref/core.md) package, which is responsible for translation and message catalog handling.

## Setting up i18n[​](#setting-up-i18n "Direct link to Setting up i18n")

First, we need to set up the i18n singleton, which is pretty simple:

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

import { messages } from "path-to-locale/en/messages.js";



i18n.load("en", messages);

i18n.activate("en");
```

The `messages.js` is generated by the Lingui CLI and contains compiled message catalogs.

tip

Alternatively, you can load catalogs dynamically using the [`@lingui/loader`](https://lingui.dev/ref/loader.md) or [`@lingui/vite-plugin`](https://lingui.dev/ref/vite-plugin.md) without the need to import compiled messages manually.

## Localizing Your App[​](#localizing-your-app "Direct link to Localizing Your App")

To localize your application, you need to wrap your localizable texts in [Macros](https://lingui.dev/ref/macro.md). Lingui provides a set of Core Macros that transform tagged template literals and can be used in any JavaScript context.

tip

Macros need a compiler plugin, such as Babel or SWC. For code that runs without a build step, see the experimental [runtime macro](https://lingui.dev/ref/core.md#runtime-macro).

Let's wrap our text in the [`t`](https://lingui.dev/ref/macro.md#t) macro:

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



t`Hello World!`;

// becomes "Salut le monde!"



const name = "Fred";

t`My name is ${name}`;

// becomes "Je m'appelle Fred"
```

Plurals and selections are possible using [`plural`](https://lingui.dev/ref/macro.md#plural) and [`select`](https://lingui.dev/ref/macro.md#select) macros:

```
import { plural } from "@lingui/core/macro";



const count = 42;



plural(count, {

  one: "# book",

  other: "# books",

});

// becomes "42 livres"
```

It's also possible to nest message formats. Each message format method in `i18n` has a standalone companion, which only returns message without performing the translation:

```
import { t, select, plural } from "@lingui/core/macro";



select(gender, {

  offset: 1,

  female: plural(numOfGuests, {

    offset: 1,

    0: t`${host} does not give a party.`,

    1: t`${host} invites ${guest} to her party.`,

    2: t`${host} invites ${guest} and one other person to her party.`,

    other: t`${host} invites ${guest} and # other people to her party.`

  }),

  male: plural(value, {...}),

  other: plural(value, {...}),

});
```

caution

All Core Macros cannot be used at the module level. They must be used within a component or function. See the [Macros](https://lingui.dev/ref/macro.md#using-macros) documentation for more information.

## See Also[​](#see-also "Direct link to See Also")

* [Message Extraction Guide](https://lingui.dev/guides/message-extraction.md)
* [Pluralization Guide](https://lingui.dev/guides/plurals.md)
* [Dynamic Loading of Message Catalogs](https://lingui.dev/guides/dynamic-loading-catalogs.md)
* [Lingui CLI Reference](https://lingui.dev/ref/cli.md)


---

# React Apps Internationalization

In this tutorial, we'll learn how to add internationalization (i18n) to an existing React JS application. We'll focus on the most common patterns and best practices for using Lingui in React.

Example

If you're looking for a working solution, check out the [Examples](https://lingui.dev/examples.md) page. It contains several sample projects with the complete setup using Lingui and React.

It includes examples for *React with Vite and Babel*, *React with Vite and SWC*, and more.

## Installing Lingui[​](#installing-lingui "Direct link to Installing Lingui")

1. Follow the [Installation and Setup](https://lingui.dev/installation.md) page for initial setup.
2. Install the [`@lingui/core`](https://lingui.dev/ref/core.md) and [`@lingui/react`](https://lingui.dev/ref/react.md) packages.

## Example Component[​](#example-component "Direct link to Example Component")

We're going to translate the following one-page mailbox application:

src/index.js

```
import React from "react";

import ReactDOM from "react-dom/client";

import Inbox from "./Inbox";



const App = () => <Inbox />;



const root = ReactDOM.createRoot(document.getElementById("root"));

root.render(

  <React.StrictMode>

    <App />

  </React.StrictMode>

);
```

src/Inbox.js

```
import React from "react";



export default function Inbox() {

  const messages = [{}, {}];

  const messagesCount = messages.length;

  const lastLogin = new Date();

  const markAsRead = () => {

    alert("Marked as read.");

  };



  return (

    <div>

      <h1>Message Inbox</h1>



      <p>

        See all <a href="/unread">unread messages</a>

        {" or "}

        <a onClick={markAsRead}>mark them</a> as read.

      </p>



      <p>

        {messagesCount === 1

          ? `There's ${messagesCount} message in your inbox.`

          : `There are ${messagesCount} messages in your inbox.`}

      </p>



      <footer>Last login on {lastLogin.toLocaleDateString()}.</footer>

    </div>

  );

}
```

This application is a simple mailbox with a header, a paragraph with a link and a button, another paragraph with a message count, and a footer with the last login date. We will use it as the basis for our tutorial.

## Setup[​](#setup "Direct link to Setup")

We will start translating the `Inbox` component right away, but we need to do one more step to set up our application.

Components need to read information about current language and message catalogs from the [`i18n`](https://lingui.dev/ref/core.md#i18n) instance. Lingui uses the [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider) to pass the `i18n` instance to your React components.

Let's add all required imports and wrap our app inside [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider):

src/index.js

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

);
```

info

You might be wondering: how are we going to change the active language? That's what the [`I18n.load`](https://lingui.dev/ref/core.md#i18n.load) and [`i18n.activate`](https://lingui.dev/ref/core.md#i18n.activate) calls are for! However, we cannot change the language unless we have the translated message catalog. And to get the catalog, we first need to extract all messages from the source code.

## Introducing Internationalization[​](#introducing-internationalization "Direct link to Introducing Internationalization")

Now we're finally going to *translate* our application. Actually, we're not going to *translate* from one language to another right now. Instead, we're going to *prepare* our app for translation. This process is called *internationalization*.

Let's start with the basics - static messages. These messages don't have any variables, HTML or components inside. Just some text:

```
<h1>Message Inbox</h1>
```

To make this heading translatable, simply wrap it in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro:

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



<h1>

  <Trans>Message Inbox</Trans>

</h1>;
```

Using JSX Macros is the easiest way to translate your React components. It handles translations of messages, including variables and other React components.

### Macros vs. Components[​](#macros-vs-components "Direct link to Macros vs. Components")

If you're wondering what [Macros](https://lingui.dev/ref/macro.md) are and the difference between macros and runtime components, here's a quick explanation.

In general, macros are executed at compile time and serve to transform the source code to make the message writing process easier. Under the hood, all JSX macros are transformed into the runtime component [`Trans`](https://lingui.dev/ref/react.md#trans) (imported from `@lingui/react`).

Below is a brief example demonstrating this transformation:

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



<Trans>Hello {name}</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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



<Trans id="OVaF9k" message="Hello {name}" values={{ name }} />;
```

As you can see, the [`Trans`](https://lingui.dev/ref/react.md#trans) runtime component gets `id` and `message` props with a message in [ICU MessageFormat](https://lingui.dev/guides/message-format.md) syntax. We could write it manually, but it's just easier and shorter to write JSX as we're used to and let macros generate the message for us.

Bundle Size Impact

Another advantage of using macros is that all non-essential properties are excluded from the production build. This results in a significant reduction in the size footprint for internationalization:

```
// NODE_ENV=production

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



<Trans id="OVaF9k" values={{ name }} />;
```

### Extracting Messages[​](#extracting-messages "Direct link to Extracting Messages")

Back to our project. It's nice to use JSX and let macros generate messages under the hood. Let's check that it actually works correctly.

All messages from the source code must be extracted into external message catalogs. Message catalogs are interchange files between developers and translators. We're going to have one file per language.

info

Refer to the [Message Extraction](https://lingui.dev/guides/message-extraction.md) guide for more information about various message extraction concepts and strategies.

Let's switch to the command line for a moment. Execute the [`extract`](https://lingui.dev/ref/cli.md#extract) CLI command. If everything is set up correctly, you should see the extracted message statistics in the output:

```
> lingui extract



Catalog statistics:

┌──────────┬─────────────┬─────────┐

│ Language │ Total count │ Missing │

├──────────┼─────────────┼─────────┤

│ cs       │      1      │    1    │

│ en       │      1      │    1    │

└──────────┴─────────────┴─────────┘
```

As a result, we have two new files in the `locales` directory: `en/messages.po` and `cs/messages.po`. These files contain extracted messages from the source code.

Let's take a look at the Czech message catalog:

src/locales/cs/messages.po

```
msgid ""

msgstr ""

"POT-Creation-Date: 2021-07-22 21:44+0900\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=utf-8\n"

"Content-Transfer-Encoding: 8bit\n"

"X-Generator: @lingui/cli\n"

"Language: cs\n"



#: src/Inbox.js:12

msgid "Message Inbox"

msgstr ""
```

It contains the message we wrapped in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro. Let's add the Czech translation:

src/locales/cs/messages.po

```
#: src/Inbox.js:12

msgid "Message Inbox"

msgstr "Příchozí zprávy"
```

If we run the [`extract`](https://lingui.dev/ref/cli.md#extract) command again, we'll see that all the Czech messages have been translated:

```
> lingui extract



Catalog statistics:

┌──────────┬─────────────┬─────────┐

│ Language │ Total count │ Missing │

├──────────┼─────────────┼─────────┤

│ cs       │      1      │    0    │

│ en       │      1      │    1    │

└──────────┴─────────────┴─────────┘
```

That's great! So how do we load it into your application? Lingui introduces the concept of compiled message catalogs. Before we load messages into our application, we need to compile them.

Use the [`compile`](https://lingui.dev/ref/cli.md#compile) command to do this:

```
> lingui compile



Compiling message catalogs…

Done!
```

If you look inside the `locales/<locale>` directory, you'll see that there is a new file for each locale: `messages.js`. This file contains the compiled message catalog.

tip

If you use TypeScript, you can add the `--typescript` flag to the `compile` command to produce compiled message catalogs with TypeScript types.

Let's load this file into our app and set active language to `cs`:

src/index.js

```
import React from "react";

import ReactDOM from "react-dom/client";



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

import { I18nProvider } from "@lingui/react";

import { messages as enMessages } from "./locales/en/messages";

import { messages as csMessages } from "./locales/cs/messages";

import Inbox from "./Inbox";



i18n.load({

  en: enMessages,

  cs: csMessages,

});

i18n.activate("cs");



const App = () => (

  <I18nProvider i18n={i18n}>

    <Inbox />

  </I18nProvider>

);



const root = ReactDOM.createRoot(document.getElementById("root"));

root.render(

  <React.StrictMode>

    <App />

  </React.StrictMode>

);
```

When we run the app, we see the inbox header is translated into Czech.

tip

Alternatively, you can load catalogs dynamically using the [`@lingui/loader`](https://lingui.dev/ref/loader.md) or [`@lingui/vite-plugin`](https://lingui.dev/ref/vite-plugin.md) without the need to import compiled messages manually.

### Summary of Basic Workflow[​](#summary-of-basic-workflow "Direct link to Summary of Basic Workflow")

Let's go through the workflow again:

1. Add an [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider), this component provides the active language and catalog(s) to other components.
2. Wrap messages in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro.
3. Run [`extract`](https://lingui.dev/ref/cli.md#extract) command to generate message catalogs.
4. Translate message catalogs (send them to translators usually).
5. Run [`compile`](https://lingui.dev/ref/cli.md#compile) to create runtime catalogs.
6. Load runtime catalog.
7. Profit! 🎉

It's not necessary to extract/translate messages one by one. This is usually done in batches. When you finish your work or PR, run [`extract`](https://lingui.dev/ref/cli.md#extract) to generate the latest message catalogs, and before building the application for production, run [`compile`](https://lingui.dev/ref/cli.md#compile).

## Formatting[​](#formatting "Direct link to Formatting")

Let's move on to another paragraph in our project. The following paragraph has some variables, some HTML and components inside:

```
<p>

  See all <a href="/unread">unread messages</a>

  {" or "}

  <a onClick={markAsRead}>mark them</a> as read.

</p>
```

Although it looks complex, there's really nothing special here. Just wrap the content of the paragraph in [`Trans`](https://lingui.dev/ref/macro.md#trans) and let the macro do the magic:

```
<p>

  <Trans>

    See all <a href="/unread">unread messages</a>

    {" or "}

    <a onClick={markAsRead}>mark them</a> as read.

  </Trans>

</p>
```

Let's see how this message actually looks in the message catalog. Run the [`extract`](https://lingui.dev/ref/cli.md#extract) command and take a look at the message:

```
#: src/Inbox.js:20

msgid "See all <0>unread messages</0> or <1>mark them</1> as read."

msgstr ""
```

You may notice that components and html tags are replaced with indexed tags (`<0>`, `<1>`). This is a little extension to the ICU MessageFormat which allows rich-text formatting inside translations. Components and their props remain in the source code and don't scare our translators. Also, in case we change a `className`, we don't need to update our message catalogs.

### JSX to MessageFormat Transformations[​](#jsx-to-messageformat-transformations "Direct link to JSX to MessageFormat Transformations")

At first glance, these transformations might seem somewhat unconventional; however, they are straightforward, intuitive, and align well with React principles. There is no need to focus on MessageFormat, as the library handles its creation for us. We can write our components as we typically would and simply wrap the text in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro.

Let's see some examples with MessageFormat equivalents:

```
<Trans>Hello {name}</Trans>

// Hello {name}
```

Any expressions are allowed, not just simple variables. The only difference is, only the variable name will be included in the extracted message:

* Any expression -> positional argument:

  ```
  <Trans>Hello {user.name}</Trans>

  // Hello {0}
  ```

* Object, arrays, function calls -> positional argument:

  ```
  <Trans>The random number is {Math.rand()}</Trans>

  // The random number is {0}
  ```

* Components might get tricky, but like we saw, it's really easy:

  ```
  <Trans>

    Read <a href="/more">more</a>.

  </Trans>

  // Read <0>more</0>.
  ```

  ```
  <Trans>

    Dear Watson,

    <br />

    it's not exactly what I had in my mind.

  </Trans>

  // Dear Watson,<0/>it's not exactly what I had in my mind.
  ```

caution

Try to keep your messages simple and avoid complex expressions. During extraction, these expressions will be replaced by positional placeholders such as `{0}`, resulting in a lack of context for translators. When you can't avoid an expression, give it a name with the [`ph`](https://lingui.dev/ref/macro.md#ph) macro: `` t`Hello ${ph({ name: user.name })}` `` is extracted as `Hello {name}`. There is also a special rule in Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) to catch these cases: [`no-expression-in-message`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-expression-in-message.md).

Similarly, to prevent numbered tag placeholders like `<0>` from depriving translators of context, use [named tag placeholders](https://lingui.dev/ref/conf.md#macrojsxplaceholderattribute) and enforce them with [`no-unnamed-tag-placeholders`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-unnamed-tag-placeholders.md).

See [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md) for the complete set of practices.

### Dates and Numbers[​](#dates-and-numbers "Direct link to Dates and Numbers")

Take a look at the message in the footer of our component. It is a bit special because it contains a date:

```
<footer>Last login on {lastLogin.toLocaleDateString()}.</footer>
```

Dates (as well as numbers) are formatted differently in different languages, but we don't have to do this manually. The heavy lifting is done by the [`Intl` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).

The `i18n` object can be accessed with the [`useLingui`](https://lingui.dev/ref/react.md#uselingui) hook:

src/Inbox.js

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

import { useMemo } from "react";



export default function Inbox() {

  const { i18n } = useLingui();

  const dateFormatter = useMemo(() => new Intl.DateTimeFormat(i18n.locale), [i18n.locale]);



  return (

    <div>

      <footer>

        <Trans>Last login on {dateFormatter.format(lastLogin)}.</Trans>

      </footer>

    </div>

  );

}
```

This will format the date using the conventional format for the active language. To format numbers, use `Intl.NumberFormat` in a similar way.

### Message ID[​](#message-id "Direct link to Message ID")

At this point, we'll explain what the message ID is and how to set it manually. Translators work with *message catalogs*. No matter what format we use, it's just a mapping of a message ID to the translation.

Here's an example of a simple message catalog in **Czech** language:

| Message ID | Translation |
| ---------- | ----------- |
| Monday     | Pondělí     |
| Tuesday    | Úterý       |
| Wednesday  | Středa      |

... and the same catalog in **French** language:

| Message ID | Translation |
| ---------- | ----------- |
| Monday     | Lundi       |
| Tuesday    | Mardi       |
| Wednesday  | Mercredi    |

The message ID is *what all catalogs have in common* – "Lundi" and "Pondělí" represent the same message in different languages.

There are two approaches for creating a message ID:

* Automatically generated from message (e.g. `Monday`) and context, if available.
* Explicit message ID set by the developer (e.g. `days.monday`).

info

Refer to the [Explicit vs Generated IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md) guide for more information about the pros and cons of each approach.

## Plurals[​](#plurals "Direct link to Plurals")

Let's take a closer look at the following code in our component:

```
<p>

  {messagesCount === 1

    ? `There's ${messagesCount} message in your inbox.`

    : `There are ${messagesCount} messages in your inbox.`}

</p>
```

This message is a bit special, because it depends on the value of the `messagesCount` variable. Most languages use different forms of words when describing quantities - this is called [pluralization](https://lingui.dev/guides/plurals.md).

What's tricky is that different languages use different number of plural forms. For example, English has only two forms - singular and plural - as we can see in the example above. However, Czech language has three plural forms. Some languages have up to 6 plural forms and some don't have plurals at all!

info

Lingui uses `Intl.PluralRules` which is supported in [every modern browser](https://caniuse.com/intl-pluralrules) and can be polyfilled for older. So you don't need to setup anything special.

### English Plural Rules[​](#english-plural-rules "Direct link to English Plural Rules")

How do we know which plural form we should use? It's very simple: we, as developers, only need to know plural forms of the language we use in our source. Our component is written in English, so looking at [English plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html#en) we'll need just two forms:

`one`

> Singular form

`other`

> Plural form

We don't need to select these forms manually. We'll use [`Plural`](https://lingui.dev/ref/macro.md#plural-1) component, which takes a `value` prop and based on the active language, selects the right plural form:

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



<p>

  <Plural value={messagesCount} one="There's # message in your inbox" other="There are # messages in your inbox" />

</p>;
```

This component will render `There's 1 message in your inbox` when `messageCount = 1` and `There are # messages in your inbox` for any other values of `messageCount`. `#` is a placeholder, which is replaced with `value`.

Let's run the [`extract`](https://lingui.dev/ref/cli.md#extract) command to see the extracted message:

```
{messagesCount, plural,

  one {There's # message in your inbox}

  other {There are # messages in your inbox}

}
```

In the catalog, you'll see the message in a single line. Here we have wrapped it to make it more readable.

### Beware of Zeroes\![​](#beware-of-zeroes "Direct link to Beware of Zeroes!")

Just a short detour, because it's a common misunderstanding. You may wonder why the following code doesn't work as expected:

```
<p>

  <Plural

    value={messagesCount}

    zero="There are no messages"

    one="There's # message in your inbox"

    other="There are # messages in your inbox"

  />

</p>
```

This component will render `There are 0 messages in your inbox` for `messagesCount = 0`. Why so? Because English doesn't have `zero` plural form. Looking at [English plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html#en), it's:

| N | Form                  |
| - | --------------------- |
| 0 | other                 |
| 1 | one                   |
| n | other (anything else) |

However, decimal numbers (even `1.0`) always use the `other` form:

```
There are 0.0 messages in your inbox.
```

### Exact Forms[​](#exact-forms "Direct link to Exact Forms")

Going back to our example, what if we specifically want to display `There are no messages` when `messagesCount = 0`? This is where exact forms come in handy:

```
<p>

  <Plural

    value={messagesCount}

    _0="There are no messages"

    one="There's # message in your inbox"

    other="There are # messages in your inbox"

  />

</p>
```

tip

MessageFormat allows exact forms, like `=0`. However, React props can't start with `=` and can't be numbers either, so we need to write `_N` instead of `=0`.

It works with any number, allowing for extensive customization as follows:

```
<p>

  <Plural

    value={messagesCount}

    _0="There are no messages"

    _1="There's one message in your inbox"

    _2="There are two messages in your inbox, that's not much!"

    other="There are # messages in your inbox"

  />

</p>
```

Exact matches always take precedence over plural forms.

### Variables and Components[​](#variables-and-components "Direct link to Variables and Components")

Let's go back to our original pluralized message:

```
<p>

  <Plural value={messagesCount} one="There's # message in your inbox" other="There are # messages in your inbox" />

</p>
```

To include variables or components within messages, simply wrap them in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro or use template literals (for example, with a variable `name`):

```
<p>

  <Plural

    value={messagesCount}

    one={`There's # message in your inbox, ${name}`}

    other={

      <Trans>

        There are <strong>#</strong> messages in your inbox, {name}

      </Trans>

    }

  />

</p>
```

Nested macros, components, variables, and expressions are all supported, providing the flexibility needed for any use case.

## Internationalization Outside of React[​](#internationalization-outside-of-react "Direct link to Internationalization Outside of React")

So far, we have learned how to translate strings within a JSX element. However, what if we need to translate content that is outside JSX or pass a translation as a prop to another component?

In our example, we have the following code:

```
const markAsRead = () => {

  alert("Marked as read.");

};
```

To translate it, we will use the [`useLingui`](https://lingui.dev/ref/macro.md#uselingui) macro hook:

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



const { t } = useLingui();



const markAsRead = () => {

  alert(t`Marked as read.`);

};
```

Now the `Marked as read.` message would be picked up by the extractor, and available for translation in the catalog.

You could also pass variables and use any other macro in the message:

```
const { t } = useLingui();



const markAsRead = () => {

  const userName = "User1234";

  alert(t`Hello ${userName}, your messages marked as read!`);

};
```

tip

You can also use this approach to translate element attributes, such as `alt` in an `img` tag:

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



export default function ImageWithCaption() {

  const { t } = useLingui();



  return <img src="..." alt={t`Image caption`} />;

}
```

caution

All Core Macros cannot be used at the module level. They must be used within a component or function. See the [Macros](https://lingui.dev/ref/macro.md#using-macros) documentation for more information.

## Review[​](#review "Direct link to Review")

After all modifications, the final i18n-ready component looks like this:

src/Inbox.js

```
import React, { useMemo } from "react";

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



export default function Inbox() {

  const { i18n, t } = useLingui();

  const messages = [{}, {}];

  const messagesCount = messages.length;

  const lastLogin = new Date();

  const markAsRead = () => {

    alert(t`Marked as read.`);

  };



  const dateFormatter = useMemo(() => new Intl.DateTimeFormat(i18n.locale), [i18n.locale]);



  return (

    <div>

      <h1>

        <Trans>Message Inbox</Trans>

      </h1>



      <p>

        <Trans>

          See all <a href="/unread">unread messages</a>

          {" or "}

          <a onClick={markAsRead}>mark them</a> as read.

        </Trans>

      </p>



      <p>

        <Plural

          value={messagesCount}

          one="There's # message in your inbox"

          other="There are # messages in your inbox"

        />

      </p>



      <footer>

        <Trans>Last login on {dateFormatter.format(lastLogin)}.</Trans>

      </footer>

    </div>

  );

}
```

That's it for this tutorial! For more details, see the reference documentation or check out additional tutorials. Happy Internationalizing!

## See Also[​](#see-also "Direct link to See Also")

* [Next.js App Router i18n Tutorial](https://lingui.dev/tutorials/react-rsc.md)
* [React Native i18n Tutorial](https://lingui.dev/tutorials/react-native.md)
* [`@lingui/react` Reference](https://lingui.dev/ref/react.md)


---

# React Native Apps Internationalization

In this tutorial, we'll learn how to add internationalization to an existing application in React Native.

The React Native tutorial is similar to the one for [React](https://lingui.dev/tutorials/react.md) and we highly recommend you read that one first because it goes into greater detail on many topics. Here, we will only cover parts that are relevant for React Native.

Example

If you're looking for a working solution, check out the [React Native example](https://github.com/lingui/js-lingui/tree/main/examples/react-native). This example application shows a complete setup using Lingui and React Native.

This tutorial assumes you use Lingui >= 5.0 and React Native >=0.76 or Expo >=52, with the Hermes JavaScript Engine.

`@lingui/core` depends on several APIs exposed by the [`Intl` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). Support of the `Intl` object can vary across React Native and OS versions. If some `Intl` feature is not supported by your runtime, you can [polyfill it](#polyfilling-intl-apis).

## Installing Lingui[​](#installing-lingui "Direct link to Installing Lingui")

1. Follow the [Installation and Setup](https://lingui.dev/installation.md?transpiler=babel) page for initial setup (for Babel).
2. Install the [`@lingui/core`](https://lingui.dev/ref/core.md) and [`@lingui/react`](https://lingui.dev/ref/react.md) packages.
3. *(optional)* Install and configure the [`@lingui/metro-transformer`](https://lingui.dev/ref/metro-transformer.md) package that enables Metro to compile `.po` files on the fly.

Warning

With the dependencies installed and set up, before running your app, please clear your Metro bundler cache with `npx expo start -c` or `npx react-native start --reset-cache` (if you do not use Expo).

## Polyfilling Intl APIs[​](#polyfilling-intl-apis "Direct link to Polyfilling Intl APIs")

React Native's JS engine may not support all `Intl` features out of the box. As of 08/2024, we need to polyfill [`Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) using [`@formatjs/intl-locale`](https://formatjs.github.io/docs/polyfills/intl-locale/) and [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) using [`@formatjs/intl-pluralrules`](https://formatjs.github.io/docs/polyfills/intl-pluralrules/). Please note that importing the `Intl` polyfills can significantly increase the amount of JS that needs to be `require`d by your app. At the same time, modern i18n libraries rely on its presence.

Follow the polyfill installation instructions before proceeding further. Import polyfills from `/polyfill-force` to avoid [slow initialization time on low-end devices](https://github.com/formatjs/formatjs/issues/4463).

## Example Component[​](#example-component "Direct link to Example Component")

We're going to translate the following contrived example:

```
import React from "react";

import { StyleSheet, Text, View, Alert, SafeAreaView, Button } from "react-native";



export const AppRoot = () => {

  const [messages, setMessages] = useState<string[]>([]);



  const markAllAsRead = () => {

    Alert.alert("", "Do you want to set all your messages as read?", [

      {

        text: "OK",

        onPress: () => {

          setMessages([]);

        },

      },

    ]);

  };



  return (

    <Inbox

      markAsRead={markAllAsRead}

      messages={messages}

      addMessage={() => {

        setMessages((msgs) => msgs.concat([`message # ${msgs.length + 1}`]));

      }}

    />

  );

};



const Inbox = ({ messages, markAsRead }) => {

  const messagesCount = messages.length;



  return (

    <SafeAreaView style={styles.container}>

      <View style={styles.container2}>

        <Text style={styles.heading}>Message Inbox</Text>



        <Button onPress={markAsRead} title="Mark all messages as read" />



        <Text>

          {messagesCount === 1

            ? `There's {messagesCount} message in your inbox.`

            : `There are ${messagesCount} messages in your inbox.`}

        </Text>

        {/* additional code for adding messages, etc.*/}

      </View>

    </SafeAreaView>

  );

};
```

As you can see, it's a simple mailbox application with only one screen.

## Internationalization in React (Native)[​](#internationalization-in-react-native "Direct link to Internationalization in React (Native)")

TL;DR

There are several ways to render translations: You may use the [`Trans`](https://lingui.dev/ref/react.md#trans) component or the [`useLingui`](https://lingui.dev/ref/react.md#uselingui) hook together with the [`t`](https://lingui.dev/ref/macro.md#t) or [`msg`](https://lingui.dev/ref/macro.md#definemessage) macros. When you change the active locale or load new messages, all components that consume the Lingui context provided by [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider) will re-render, making sure the UI shows the correct translations.

Not surprisingly, this part isn't too different from the [React tutorial](https://lingui.dev/tutorials/react.md).

First, we need to wrap our app with [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider) and then we can use the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro to translate the screen heading:

```
import { I18nProvider, TransRenderProps } from "@lingui/react";

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

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

import { Text } from "react-native";



i18n.loadAndActivate({ locale: "en", messages });



const DefaultComponent = (props: TransRenderProps) => {

  return <Text>{props.children}</Text>;

};



<I18nProvider i18n={i18n} defaultComponent={DefaultComponent}>

 <AppRoot />

</I18nProvider>



// later in the React element tree:

<Text style={styles.heading}><Trans>Message Inbox</Trans></Text>
```

Hint

We're importing the default `i18n` object from `@lingui/core`. Read more about the `i18n` object in the [reference](https://lingui.dev/ref/core.md).

Translating the heading is done. Now, let's translate the `title` prop in the `<Button title="mark messages as read" />` element. In this case, `Button` expects to receive a `string`, so we cannot use the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro here!

The solution is to use the `t` macro which we can obtain from the `useLingui` hook. We use it like this to get a translated string:

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



const { t } = useLingui();

...

<Button title={t`this will be translated and rerendered with locale changes`}/>
```

Under the hood, [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider) takes the instance of the `i18n` object and passes it to `Trans` components through React context. `I18nProvider` will update the context value (which then rerenders components that consume the provided context value) when locale or message catalogs are updated.

The `Trans` component uses the `i18n` instance to get the translations from it. If we cannot use `Trans`, we can use the `useLingui` hook to get hold of the `i18n` instance ourselves and get the translations from there.

The interplay of `I18nProvider` and `useLingui` is shown in the following simplified example:

```
import { I18nProvider } from "@lingui/react";

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

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



<I18nProvider i18n={i18n}>

  <AppRoot />

</I18nProvider>;

//...

const Inbox = ({ markAsRead }) => {

  const { t } = useLingui();

  return (

    <View>

      <Text style={styles.heading}>

        <Trans>Message Inbox</Trans>

      </Text>

      <Button onPress={markAsRead} title={t`Mark messages as read`} />

    </View>

  );

};
```

## Internationalization Outside of React[​](#internationalization-outside-of-react "Direct link to Internationalization Outside of React")

Until now, we have covered the [`Trans`](https://lingui.dev/ref/react.md#trans) macro and the [`useLingui`](https://lingui.dev/ref/react.md#uselingui) hook. Using them will make sure our components are always in sync with the currently active locale and message catalog.

However, you may want to show localized strings outside of React, for example when you want to show an Alert from some business logic code.

In that case you'll also need access to the `i18n` object, but you don't need to pass it around from some React component. By default, Lingui uses an `i18n` object instance that you can import as follows:

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

This instance is the source of truth for the active locale. For string constants that will be translated at runtime, use the [`msg`](https://lingui.dev/ref/macro.md#definemessage) macro as follows:

```
const deleteTitle = msg`Are you sure to delete this?`

...

const showDeleteConfirmation = () => {

  Alert.alert(i18n.t(deleteTitle))

}
```

## Changing the Active Locale[​](#changing-the-active-locale "Direct link to Changing the Active Locale")

The last remaining piece of the puzzle is changing the active locale. The `i18n` object exposes [`i18n.loadAndActivate()`](https://lingui.dev/ref/core.md#i18n.loadAndActivate) for that. Call the method and the [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider) will re-render the translations. It all becomes clear when you take a look at the [final code](https://github.com/lingui/js-lingui/tree/main/examples/react-native/src/MainScreen.tsx#L29).

However, we don't recommend that you change the locale like this in mobile apps, as it can cause conflicts in how your app ui is localized. This is further [explained here](https://www.youtube.com/live/uLicTDG5hSs?feature=share\&t=9088).

## Choosing the Default Locale[​](#choosing-the-default-locale "Direct link to Choosing the Default Locale")

Lingui does not ship with functionality that would allow you to determine the best locale you should activate by default.

Instead, please refer to [Expo localization](https://docs.expo.dev/versions/latest/sdk/localization/#localizationgetlocales) or [react-native-localize](https://github.com/zoontek/react-native-localize#getlocales). Both packages will provide you with information about the locales that the user prefers. Combining that information with the locales that your app supports will give you the locale you should use by default.

## Rendering and Styling of Translations[​](#rendering-and-styling-of-translations "Direct link to Rendering and Styling of Translations")

As described in the [reference](https://lingui.dev/ref/react.md#rendering-translations), by default, translation components render translation as text without a wrapping tag. In React Native though, all text must be wrapped in the `Text` component. This means we would need to use the [`Trans`](https://lingui.dev/ref/macro.md#trans) component like this:

```
<Text>

  <Trans>Message Inbox</Trans>

</Text>
```

You'll surely agree the `Text` component looks a little redundant. That's why the [`I18nProvider`](https://lingui.dev/ref/react.md#i18nprovider) component accepts a `defaultComponent` prop. Just supply the `Text` component as the `defaultComponent` prop and the previous example can be simplified to:

```
<Trans>Message Inbox</Trans>
```

Alternatively, you may override the default locally on the i18n components, using the `render` or `component` props, as documented in the [reference](https://lingui.dev/ref/react.md#rendering-translations). Use them to apply styling to the rendered string.

## Nesting Components[​](#nesting-components "Direct link to Nesting Components")

The [`Trans`](https://lingui.dev/ref/macro.md#trans) macro and `Text` component may be nested, for example to achieve the effect shown in the picture. This is thanks to how React Native [handles nested text](https://facebook.github.io/react-native/docs/text#nested-text).

![image](/assets/images/rn-component-nesting-333bb3aa1e3e03a1e3e29035c93fcb4f.png)

This can be achieved by the following code:

```
<Trans>

  <Text style={{ fontSize: 20 }}>

    <Text>Concert of </Text>

    <Text style={{ color: "green" }}>Green Day</Text>

    <Text style={{ fontWeight: "bold" }}> tonight!</Text>

  </Text>

</Trans>
```

The extracted string for translation will look like this:

`"<0><1>Concert of </1><2>Green Day</2><3> tonight!</3></0>"`

The important point here is that the sentence isn't broken into pieces but remains together - that will allow the translator to deliver a quality result.

## See Also[​](#see-also "Direct link to See Also")

* [React i18n Tutorial](https://lingui.dev/tutorials/react.md)
* [Message Extraction Guide](https://lingui.dev/guides/message-extraction.md)
* [`@lingui/react` Reference](https://lingui.dev/ref/react.md)
* [Lingui CLI Reference](https://lingui.dev/ref/cli.md)
* [Localizing React Native apps talk from React Native EU 2022](https://www.youtube.com/live/uLicTDG5hSs?feature=share\&t=7512)

***

This guide originally authored and contributed in full by [Vojtech Novak](https://twitter.com/vonovak).


---

# Next.js App Router i18n with React Server Components

Lingui provides support for React Server Components (RSC) as of v4.10.0. In this tutorial, we'll learn how to add internationalization to an application with the Next.js [App Router](https://nextjs.org/docs/app). However, the same principles are applicable to any RSC-based solution.

Example

There's a working example available [here](https://github.com/lingui/js-lingui/tree/main/examples/nextjs-swc). We will make references to the important parts of it throughout the tutorial. The example is more complete than this tutorial.

The example uses both Pages Router and App Router, so you can see how to use Lingui with both in [this commit](https://github.com/lingui/js-lingui/pull/1944/commits/100fc74abb49cff677f4b1cac1dfd5da60262b67).

Before going further, please follow the [Installation and Setup](https://lingui.dev/installation.md?transpiler=swc) instructions (for SWC or Babel depending on which you use - most likely it's SWC). You may also need to configure your `tsconfig.json` according to [this visual guide](https://twitter.com/mattpocockuk/status/1724462050288587123). This is so that TypeScript understands the values exported from `@lingui/react` package.

### Adding i18n Support to Next.js[​](#adding-i18n-support-to-nextjs "Direct link to Adding i18n Support to Next.js")

Firstly, your Next.js app needs to be ready for routing and rendering of content in multiple languages. This is done through the proxy, called middleware before Next.js 16 (see the [example app's proxy](https://github.com/lingui/js-lingui/blob/main/examples/nextjs-swc/src/proxy.ts)). Please read the [official Next.js docs](https://nextjs.org/docs/app/guides/internationalization) for more information.

After configuring the proxy, make sure your page and route files are moved from `app` to `app/[lang]` folder (example: `app/[lang]/layout.tsx`). This enables the Next.js router to dynamically handle different locales in the route. Because `[lang]` sits above the root layout, it's a root parameter: since Next.js 16.3, any Server Component can read it with [`next/root-params`](https://nextjs.org/docs/app/api-reference/functions/next-root-params), without passing `params` down from layouts and pages.

### Next.js Config[​](#nextjs-config "Direct link to Next.js Config")

Secondly, add the `swc-plugin` to the Next.js config, so that you can use [Lingui Macros](https://lingui.dev/ref/macro.md).

next.config.mjs

```
import { linguiMacroSwcPlugin } from "@lingui/swc-plugin/options";



/** @type {import('next').NextConfig} */

const nextConfig = {

  // to use Lingui macros

  experimental: {

    swcPlugins: [linguiMacroSwcPlugin()],

  },

};



export default nextConfig;
```

### Setup with Server Components[​](#setup-with-server-components "Direct link to Setup with Server Components")

With Lingui, the experience of localizing React is the same in client and server components: `Trans` and `useLingui` can be used identically in both worlds, even though internally there are two implementations.

Under the hood

Translation strings, one way or another, are obtained from an [I18n](https://lingui.dev/ref/core.md) object instance. In client components, this instance is passed around using React context. Because context is not available in Server components, instead [`cache`](https://react.dev/reference/react/cache) is used to maintain an I18n instance for each request.

To make Lingui work in both server and client components, we need to take the `lang` of the current request and create a corresponding instance of the I18n object. We then make it available to the components in our app. This is a 2-step process:

1. given `lang`, take an I18n instance and store it in the [`cache`](https://react.dev/reference/react/cache) so it can be used server-side
2. given `lang`, take an I18n instance and make it available to client components via `I18nProvider`

Step (1) fits in a small helper. It reads `lang` with `next/root-params`, so it doesn't need any arguments:

src/initLingui.ts

```
import { lang } from "next/root-params";

import { setI18n } from "@lingui/react/server";

import { getI18nInstance } from "./appRouterI18n";



export async function initLingui() {

  const i18n = getI18nInstance(await lang()); // get a ready-made i18n instance for the current locale

  setI18n(i18n); // make it available server-side for the current request

  return i18n;

}
```

The root layout calls it, and so does `generateMetadata`:

src/app/\[lang]/layout.tsx

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

import { initLingui } from "../../initLingui";

import { LinguiClientProvider } from "./LinguiClientProvider";



export async function generateMetadata() {

  const i18n = await initLingui();



  return {

    title: i18n._(msg`Translation Demo`),

  };

}



export default async function RootLayout({ children }: { children: React.ReactNode }) {

  const i18n = await initLingui();



  return (

    <html lang={i18n.locale}>

      <body>

        <LinguiClientProvider initialLocale={i18n.locale} initialMessages={i18n.messages}>

          {children}

        </LinguiClientProvider>

      </body>

    </html>

  );

}
```

Next.js older than 16.3

`next/root-params` isn't available before Next.js 16.3. Take `lang` from the `params` prop that Next.js passes to every layout and page, and pass it to the helper instead:

```
export function initLingui(lang: string) {

  const i18n = getI18nInstance(lang);

  setI18n(i18n);

  return i18n;

}



type Props = {

  params: Promise<{ lang: string }>;

  children: React.ReactNode;

};



export default async function RootLayout({ params, children }: Props) {

  const { lang } = await params;

  const i18n = initLingui(lang);

  // ...render the same tree as above

}
```

In Next.js 14 and older, `params` is a plain object rather than a promise.

caution

Root parameter getters such as `lang()` only work in Server Components and the server-side code they call. They aren't available in Client Components, Server Actions, or Route Handlers: pass the locale explicitly there, for example as an argument from the component that calls the Server Action.

Inside a [`"use cache"`](https://nextjs.org/docs/app/api-reference/directives/use-cache) function, Next.js adds the root parameters you read to the cache key, so `getI18nInstance(await lang())` gives you one cache entry per locale. Calling `lang()` inside `unstable_cache` throws an error.

Step (2) is implemented in `LinguiClientProvider`, which is a client component:

LinguiClientProvider.tsx

```
"use client";



import { I18nProvider } from "@lingui/react";

import { type Messages, setupI18n } from "@lingui/core";

import { useState } from "react";



export function LinguiClientProvider({

  children,

  initialLocale,

  initialMessages,

}: {

  children: React.ReactNode;

  initialLocale: string;

  initialMessages: Messages;

}) {

  const [i18n] = useState(() => {

    return setupI18n({

      locale: initialLocale,

      messages: { [initialLocale]: initialMessages },

    });

  });

  return <I18nProvider i18n={i18n}>{children}</I18nProvider>;

}
```

tip

Why are we not passing the I18n instance directly from `RootLayout` to the client via `LinguiClientProvider`? It's because the I18n object isn't serializable, and cannot be passed from server to client.

Lastly, there's the `appRouterI18n.ts` file, which is only executed on server and holds one instance of I18n object for each locale of our application. See [here](https://github.com/lingui/js-lingui/blob/main/examples/nextjs-swc/src/appRouterI18n.ts) how it's implemented in the example app.

### Rendering Translations in Server and Client Components[​](#rendering-translations-in-server-and-client-components "Direct link to Rendering Translations in Server and Client Components")

Below you can see an example of a React component. This component can be rendered **both with RSC and on client**. This is great if you're migrating a Lingui-based project from pages router to App Router because you can keep the same components working in both worlds.

In fact, if you swapped the html tags for their more universal alternatives, this component could also be used in React Native.

app/\[lang]/components/SomeComponent.tsx

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



export function SomeComponent() {

  const { t } = useLingui();

  return (

    <div>

      <p>

        <Trans>Some Item</Trans>

      </p>

      <p>{t`Other Item`}</p>

    </div>

  );

}
```

As you may recall, hooks are not supported in RSC, so you might be surprised that this works. Under RSC, `useLingui` is actually not a hook but a simple function call which reads from the React `cache` mentioned above.

The [RSC implementation](https://github.com/lingui/js-lingui/blob/ec49d0cc53dbc4f9e0f92f0edcdf59f3e5c1de1f/packages/react/src/index-rsc.ts#L12) of `useLingui` uses `getI18n`, which is another way to obtain the I18n instance on the server.

### Pages, Layouts and Lingui[​](#pages-layouts-and-lingui "Direct link to Pages, Layouts and Lingui")

There's one last caveat: in a real-world app, you will need to localize many pages, and layouts. Because of the way the App Router is designed, the `setI18n` call needs to happen not only in layouts, but also in pages. Read more in:

* [Why do nested layouts/pages render before their parent layouts?](https://github.com/vercel/next.js/discussions/53026)
* [On navigation, layouts preserve state and do not re-render](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#layouts)

`next/root-params` doesn't change this. Lingui's server-side `Trans` and `useLingui` read the I18n instance synchronously from the React `cache`, so it has to be set before they render, in every page and layout. What root params remove is the need to thread `params` through each of them: the call becomes a one-liner without arguments.

src/app/\[lang]/some-page/page.tsx

```
import { initLingui } from "../../../initLingui";

import { SomeComponent } from "../components/SomeComponent";



export default async function Page() {

  await initLingui();

  return <SomeComponent />;

}
```

See [`initLingui.tsx`](https://github.com/lingui/js-lingui/blob/main/examples/nextjs-swc/src/initLingui.tsx) in the example app.

### Changing the Active Language[​](#changing-the-active-language "Direct link to Changing the Active Language")

Most likely, your users will not need to change the language of the application because it will render in their preferred language (obtained from the `accept-language` header in the [proxy](https://github.com/lingui/js-lingui/blob/main/examples/nextjs-swc/src/proxy.ts)), or with a fallback.

To change language, redirect users to a page with the new locale in the url. We do not recommend [dynamic](https://lingui.dev/guides/dynamic-loading-catalogs.md) switching because server-rendered locale-dependent content would become stale.

### Static Rendering Pitfall[​](#static-rendering-pitfall "Direct link to Static Rendering Pitfall")

Next.js can use [static rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#static-rendering-default) where it renders your pages only once at build time and then serves them to all users.

To ensure static rendering takes into account the supported locales, implement [generateStaticParams](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) which will build the content for all locales.

It's important that you do not create any locale-dependent strings at a place in the app where locale may not be initialized correctly at build time. This could result in the content being generated only for one locale, and for this reason we do not recommend using the global i18n object in such scenarios. For example:

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

import { t } from "@lingui/core/macro";

// 😰 if this code runs at build time, it'll always be in the locale

// which the imported global i18n object had at that time

const immutableGreeting = t(i18n)`Hello World`;



// ✅ this component will be statically rendered for each locale

// (specified with `generateStaticParams`)

export default function SomePage() {

  return (

    <>

      <Trans>Hello world</Trans> {/* this is fine */}

    </>

  );

}
```

Read more about [Lazy Translation](https://lingui.dev/guides/lazy-translations.md) to see how to handle translation defined on the module level.

## See Also[​](#see-also "Direct link to See Also")

* [React i18n Tutorial](https://lingui.dev/tutorials/react.md)
* [`@lingui/react` Reference](https://lingui.dev/ref/react.md)


---

# Solid Apps Internationalization

In this tutorial, we'll learn how to add internationalization (i18n) to an existing SolidJS application. We'll focus on the most common patterns and best practices for using Lingui in Solid.

Example

If you're looking for a working solution, check out the [Examples](https://lingui.dev/examples.md) page. It contains sample projects with the complete setup using Lingui and Solid.

It includes an example for *Solid with Vite*.

## Installing Lingui[​](#installing-lingui "Direct link to Installing Lingui")

1. Follow the [Installation and Setup](https://lingui.dev/installation.md) page for initial setup.
2. Install the [`@lingui/core`](https://lingui.dev/ref/core.md) and [`@lingui/solid`](https://lingui.dev/ref/solid.md) packages.

## Example Component[​](#example-component "Direct link to Example Component")

We're going to translate the following one-page mailbox application:

src/index.js

```
import { render } from "solid-js/web";

import Inbox from "./Inbox";



const App = () => <Inbox />;



render(() => <App />, document.getElementById("root")!);
```

src/Inbox.js

```
export default function Inbox() {

  const messages = [{}, {}];

  const messagesCount = messages.length;

  const lastLogin = new Date();

  const markAsRead = () => {

    alert("Marked as read.");

  };



  return (

    <div>

      <h1>Message Inbox</h1>



      <p>

        See all <a href="/unread">unread messages</a>

        {" or "}

        <a onClick={markAsRead}>mark them</a> as read.

      </p>



      <p>

        {messagesCount === 1

          ? `There's ${messagesCount} message in your inbox.`

          : `There are ${messagesCount} messages in your inbox.`}

      </p>



      <footer>Last login on {lastLogin.toLocaleDateString()}.</footer>

    </div>

  );

}
```

This application is a simple mailbox with a header, a paragraph with a link and a button, another paragraph with a message count, and a footer with the last login date. We will use it as the basis for our tutorial.

## Configure Lingui for Solid[​](#configure-lingui-for-solid "Direct link to Configure Lingui for Solid")

We recommend using `defineConfig` from `@lingui/solid/config` to create the configuration. It provides all required options for you.

lingui.config.ts

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



export default defineConfig({

  locales: ["en", "cs"],

  sourceLocale: "en",

  catalogs: [

    {

      path: "src/locales/{locale}/messages",

      include: ["src"],

    },

  ],

});
```

This is equivalent to:

lingui.config.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"],

  },

};
```

## Configure Vite[​](#configure-vite "Direct link to Configure Vite")

Setup Lingui in `vite.config.ts`:

vite.config.ts

```
import { defineConfig } from "vite";

import solid from "vite-plugin-solid";

import { lingui } from "@lingui/vite-plugin";



export default defineConfig({

  plugins: [

    solid({

      babel: {

        plugins: ["@lingui/babel-plugin-lingui-macro"],

      },

    }),

    lingui(),

  ],

});
```

note

The [native macro transform](https://lingui.dev/ref/vite-plugin.md#native-macro-transform) of `@lingui/vite-plugin` doesn't support Solid yet, so keep the Babel plugin for macros and don't enable `macroTransform`.

## Setup[​](#setup "Direct link to Setup")

We will start translating the `Inbox` component right away, but we need to do one more step to set up our application.

Components need to read information about current language and message catalogs from the [`i18n`](https://lingui.dev/ref/core.md#i18n) instance. Lingui uses the [`I18nProvider`](https://lingui.dev/ref/solid.md#i18nprovider) to pass the `i18n` instance to your Solid components.

Let's add all required imports and wrap our app inside [`I18nProvider`](https://lingui.dev/ref/solid.md#i18nprovider):

src/index.js

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

import { I18nProvider } from "@lingui/solid";

import { render } from "solid-js/web";

import { messages } from "./locales/en/messages";

import Inbox from "./Inbox";



i18n.load("en", messages);

i18n.activate("en");



const App = () => (

  <I18nProvider i18n={i18n}>

    <Inbox />

  </I18nProvider>

);



render(() => <App />, document.getElementById("root")!);
```

info

You might be wondering: how are we going to change the active language? That's what the [`I18n.load`](https://lingui.dev/ref/core.md#i18n.load) and [`i18n.activate`](https://lingui.dev/ref/core.md#i18n.activate) calls are for! However, we cannot change the language unless we have the translated message catalog. And to get the catalog, we first need to extract all messages from the source code.

## Introducing Internationalization[​](#introducing-internationalization "Direct link to Introducing Internationalization")

Now we're finally going to *translate* our application. Actually, we're not going to *translate* from one language to another right now. Instead, we're going to *prepare* our app for translation. This process is called *internationalization*.

Let's start with the basics - static messages. These messages don't have any variables, HTML or components inside. Just some text:

```
<h1>Message Inbox</h1>
```

To make this heading translatable, simply wrap it in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro:

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



<h1>

  <Trans>Message Inbox</Trans>

</h1>;
```

Using JSX Macros is the easiest way to translate your Solid components. It handles translations of messages, including variables and other Solid components.

### Macros vs. Components[​](#macros-vs-components "Direct link to Macros vs. Components")

If you're wondering what [Macros](https://lingui.dev/ref/macro.md) are and the difference between macros and runtime components, here's a quick explanation.

In general, macros are executed at compile time and serve to transform the source code to make the message writing process easier. Under the hood, all JSX macros are transformed into the runtime component [`Trans`](https://lingui.dev/ref/solid.md#trans) (imported from `@lingui/solid`).

Below is a brief example demonstrating this transformation:

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



<Trans>Hello {name}</Trans>;



// ↓ ↓ ↓ ↓ ↓ ↓



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



<Trans id="OVaF9k" message="Hello {name}" values={{ name }} />;
```

As you can see, the [`Trans`](https://lingui.dev/ref/solid.md#trans) runtime component gets `id` and `message` props with a message in [ICU MessageFormat](https://lingui.dev/guides/message-format.md) syntax. We could write it manually, but it's just easier and shorter to write JSX as we're used to and let macros generate the message for us.

Bundle Size Impact

Another advantage of using macros is that all non-essential properties are excluded from the production build. This results in a significant reduction in the size footprint for internationalization:

```
// NODE_ENV=production

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



<Trans id="OVaF9k" values={{ name }} />;
```

### Extracting Messages[​](#extracting-messages "Direct link to Extracting Messages")

Back to our project. It's nice to use JSX and let macros generate messages under the hood. Let's check that it actually works correctly.

All messages from the source code must be extracted into external message catalogs. Message catalogs are interchange files between developers and translators. We're going to have one file per language.

info

Refer to the [Message Extraction](https://lingui.dev/guides/message-extraction.md) guide for more information about various message extraction concepts and strategies.

Let's switch to the command line for a moment. Execute the [`extract`](https://lingui.dev/ref/cli.md#extract) CLI command. If everything is set up correctly, you should see the extracted message statistics in the output:

```
> lingui extract



Catalog statistics:

┌──────────┬─────────────┬─────────┐

│ Language │ Total count │ Missing │

├──────────┼─────────────┼─────────┤

│ cs       │      1      │    1    │

│ en       │      1      │    1    │

└──────────┴─────────────┴─────────┘
```

As a result, we have two new files in the `locales` directory: `en/messages.po` and `cs/messages.po`. These files contain extracted messages from the source code.

Let's take a look at the Czech message catalog:

src/locales/cs/messages.po

```
msgid ""

msgstr ""

"POT-Creation-Date: 2021-07-22 21:44+0900\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=utf-8\n"

"Content-Transfer-Encoding: 8bit\n"

"X-Generator: @lingui/cli\n"

"Language: cs\n"



#: src/Inbox.js:12

msgid "Message Inbox"

msgstr ""
```

It contains the message we wrapped in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro. Let's add the Czech translation:

src/locales/cs/messages.po

```
#: src/Inbox.js:12

msgid "Message Inbox"

msgstr "Příchozí zprávy"
```

If we run the [`extract`](https://lingui.dev/ref/cli.md#extract) command again, we'll see that all the Czech messages have been translated:

```
> lingui extract



Catalog statistics:

┌──────────┬─────────────┬─────────┐

│ Language │ Total count │ Missing │

├──────────┼─────────────┼─────────┤

│ cs       │      1      │    0    │

│ en       │      1      │    1    │

└──────────┴─────────────┴─────────┘
```

That's great! So how do we load it into your application? Lingui introduces the concept of compiled message catalogs. Before we load messages into our application, we need to compile them.

Use the [`compile`](https://lingui.dev/ref/cli.md#compile) command to do this:

```
> lingui compile



Compiling message catalogs…

Done!
```

If you look inside the `locales/<locale>` directory, you'll see that there is a new file for each locale: `messages.js`. This file contains the compiled message catalog.

tip

If you use TypeScript, you can add the `--typescript` flag to the `compile` command to produce compiled message catalogs with TypeScript types.

Let's load this file into our app and set active language to `cs`:

src/index.js

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

import { I18nProvider } from "@lingui/solid";

import { render } from "solid-js/web";

import { messages as enMessages } from "./locales/en/messages";

import { messages as csMessages } from "./locales/cs/messages";

import Inbox from "./Inbox";



i18n.load({

  en: enMessages,

  cs: csMessages,

});

i18n.activate("cs");



const App = () => (

  <I18nProvider i18n={i18n}>

    <Inbox />

  </I18nProvider>

);



render(() => <App />, document.getElementById("root")!);
```

When we run the app, we see the inbox header is translated into Czech.

tip

Alternatively, you can load catalogs dynamically using the [`@lingui/loader`](https://lingui.dev/ref/loader.md) or [`@lingui/vite-plugin`](https://lingui.dev/ref/vite-plugin.md) without the need to import compiled messages manually.

### Summary of Basic Workflow[​](#summary-of-basic-workflow "Direct link to Summary of Basic Workflow")

Let's go through the workflow again:

1. Add an [`I18nProvider`](https://lingui.dev/ref/solid.md#i18nprovider), this component provides the active language and catalog(s) to other components.
2. Wrap messages in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro.
3. Run [`extract`](https://lingui.dev/ref/cli.md#extract) command to generate message catalogs.
4. Translate message catalogs (send them to translators usually).
5. Run [`compile`](https://lingui.dev/ref/cli.md#compile) to create runtime catalogs.
6. Load runtime catalog.
7. Profit! 🎉

It's not necessary to extract/translate messages one by one. This is usually done in batches. When you finish your work or PR, run [`extract`](https://lingui.dev/ref/cli.md#extract) to generate the latest message catalogs, and before building the application for production, run [`compile`](https://lingui.dev/ref/cli.md#compile).

## Formatting[​](#formatting "Direct link to Formatting")

Let's move on to another paragraph in our project. The following paragraph has some variables, some HTML and components inside:

```
<p>

  See all <a href="/unread">unread messages</a>

  {" or "}

  <a onClick={markAsRead}>mark them</a> as read.

</p>
```

Although it looks complex, there's really nothing special here. Just wrap the content of the paragraph in [`Trans`](https://lingui.dev/ref/macro.md#trans) and let the macro do the magic:

```
<p>

  <Trans>

    See all <a href="/unread">unread messages</a>

    {" or "}

    <a onClick={markAsRead}>mark them</a> as read.

  </Trans>

</p>
```

Let's see how this message actually looks in the message catalog. Run the [`extract`](https://lingui.dev/ref/cli.md#extract) command and take a look at the message:

```
#: src/Inbox.js:20

msgid "See all <0>unread messages</0> or <1>mark them</1> as read."

msgstr ""
```

You may notice that components and html tags are replaced with indexed tags (`<0>`, `<1>`). This is a little extension to the ICU MessageFormat which allows rich-text formatting inside translations. Components and their props remain in the source code and don't scare our translators. Also, in case we change a `class`, we don't need to update our message catalogs.

Solid JSX references

Solid JSX values are references. Don't store a JSX element in a variable and use it more than once in a message:

```
const docsLink = <a href="/docs">documentation</a>;



<Trans>

  Read {docsLink} or open {docsLink}.

</Trans>;
```

The second use will move the same DOM node instead of rendering another copy. Use inline JSX or a component so Solid creates a new instance at each position:

```
const DocsLink = () => <a href="/docs">documentation</a>;



<Trans>

  Read <DocsLink /> or open <DocsLink />.

</Trans>;
```

### JSX to MessageFormat Transformations[​](#jsx-to-messageformat-transformations "Direct link to JSX to MessageFormat Transformations")

At first glance, these transformations might seem somewhat unconventional; however, they are straightforward, intuitive, and align well with Solid principles. There is no need to focus on MessageFormat, as the library handles its creation for us. We can write our components as we typically would and simply wrap the text in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro.

Let's see some examples with MessageFormat equivalents:

```
<Trans>Hello {name}</Trans>

// Hello {name}
```

Any expressions are allowed, not just simple variables. The only difference is, only the variable name will be included in the extracted message:

* Any expression -> positional argument:

  ```
  <Trans>Hello {user.name}</Trans>

  // Hello {0}
  ```

* Object, arrays, function calls -> positional argument:

  ```
  <Trans>The random number is {Math.random()}</Trans>

  // The random number is {0}
  ```

* Components might get tricky, but like we saw, it's really easy:

  ```
  <Trans>

    Read <a href="/more">more</a>.

  </Trans>

  // Read <0>more</0>.
  ```

  ```
  <Trans>

    Dear Watson,

    <br />

    it's not exactly what I had in my mind.

  </Trans>

  // Dear Watson,<0/>it's not exactly what I had in my mind.
  ```

caution

Try to keep your messages simple and avoid complex expressions. During extraction, these expressions will be replaced by positional placeholders such as `{0}`, resulting in a lack of context for translators. When you can't avoid an expression, give it a name with the [`ph`](https://lingui.dev/ref/macro.md#ph) macro: `` t`Hello ${ph({ name: user.name })}` `` is extracted as `Hello {name}`. There is also a special rule in Lingui [ESLint Plugin](https://lingui.dev/ref/eslint-plugin.md) to catch these cases: [`no-expression-in-message`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-expression-in-message.md).

Similarly, to prevent numbered tag placeholders like `<0>` from depriving translators of context, use [named tag placeholders](https://lingui.dev/ref/conf.md#macrojsxplaceholderattribute) and enforce them with [`no-unnamed-tag-placeholders`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/no-unnamed-tag-placeholders.md).

See [Translator-friendly Messages](https://lingui.dev/guides/translator-friendly-messages.md) for the complete set of practices.

### Dates and Numbers[​](#dates-and-numbers "Direct link to Dates and Numbers")

Take a look at the message in the footer of our component. It is a bit special because it contains a date:

```
<footer>Last login on {lastLogin.toLocaleDateString()}.</footer>
```

Dates (as well as numbers) are formatted differently in different languages, but we don't have to do this manually. The heavy lifting is done by the [`Intl` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).

The `i18n` object can be accessed with the [`useLingui`](https://lingui.dev/ref/solid.md#uselingui) hook:

src/Inbox.js

```
import { createMemo } from "solid-js";

import { Trans, useLingui } from "@lingui/solid/macro";



export default function Inbox() {

  const { i18n } = useLingui();

  const dateFormatter = createMemo(() => new Intl.DateTimeFormat(i18n().locale));



  return (

    <div>

      <footer>

        <Trans>Last login on {dateFormatter().format(lastLogin)}.</Trans>

      </footer>

    </div>

  );

}
```

This will format the date using the conventional format for the active language. To format numbers, use `Intl.NumberFormat` in a similar way.

### Message ID[​](#message-id "Direct link to Message ID")

At this point, we'll explain what the message ID is and how to set it manually. Translators work with *message catalogs*. No matter what format we use, it's just a mapping of a message ID to the translation.

Here's an example of a simple message catalog in **Czech** language:

| Message ID | Translation |
| ---------- | ----------- |
| Monday     | Pondělí     |
| Tuesday    | Úterý       |
| Wednesday  | Středa      |

... and the same catalog in **French** language:

| Message ID | Translation |
| ---------- | ----------- |
| Monday     | Lundi       |
| Tuesday    | Mardi       |
| Wednesday  | Mercredi    |

The message ID is *what all catalogs have in common* – "Lundi" and "Pondělí" represent the same message in different languages.

There are two approaches for creating a message ID:

* Automatically generated from message (e.g. `Monday`) and context, if available.
* Explicit message ID set by the developer (e.g. `days.monday`).

info

Refer to the [Explicit vs Generated IDs](https://lingui.dev/guides/explicit-vs-generated-ids.md) guide for more information about the pros and cons of each approach.

## Plurals[​](#plurals "Direct link to Plurals")

Let's take a closer look at the following code in our component:

```
<p>

  {messagesCount === 1

    ? `There's ${messagesCount} message in your inbox.`

    : `There are ${messagesCount} messages in your inbox.`}

</p>
```

This message is a bit special, because it depends on the value of the `messagesCount` variable. Most languages use different forms of words when describing quantities - this is called [pluralization](https://lingui.dev/guides/plurals.md).

What's tricky is that different languages use different number of plural forms. For example, English has only two forms - singular and plural - as we can see in the example above. However, Czech language has three plural forms. Some languages have up to 6 plural forms and some don't have plurals at all!

info

Lingui uses `Intl.PluralRules` which is supported in [every modern browser](https://caniuse.com/intl-pluralrules) and can be polyfilled for older. So you don't need to setup anything special.

### English Plural Rules[​](#english-plural-rules "Direct link to English Plural Rules")

How do we know which plural form we should use? It's very simple: we, as developers, only need to know plural forms of the language we use in our source. Our component is written in English, so looking at [English plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html#en) we'll need just two forms:

`one`

> Singular form

`other`

> Plural form

We don't need to select these forms manually. We'll use [`Plural`](https://lingui.dev/ref/macro.md#plural-1) component, which takes a `value` prop and based on the active language, selects the right plural form:

```
import { Plural } from "@lingui/solid/macro";



<p>

  <Plural value={messagesCount} one="There's # message in your inbox" other="There are # messages in your inbox" />

</p>;
```

This component will render `There's 1 message in your inbox` when `messagesCount = 1` and `There are # messages in your inbox` for any other values of `messagesCount`. `#` is a placeholder, which is replaced with `value`.

Let's run the [`extract`](https://lingui.dev/ref/cli.md#extract) command to see the extracted message:

```
{messagesCount, plural,

  one {There's # message in your inbox}

  other {There are # messages in your inbox}

}
```

In the catalog, you'll see the message in a single line. Here we have wrapped it to make it more readable.

### Beware of Zeroes\![​](#beware-of-zeroes "Direct link to Beware of Zeroes!")

Just a short detour, because it's a common misunderstanding. You may wonder why the following code doesn't work as expected:

```
<p>

  <Plural

    value={messagesCount}

    zero="There are no messages"

    one="There's # message in your inbox"

    other="There are # messages in your inbox"

  />

</p>
```

This component will render `There are 0 messages in your inbox` for `messagesCount = 0`. Why so? Because English doesn't have `zero` plural form. Looking at [English plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html#en), it's:

| N | Form                  |
| - | --------------------- |
| 0 | other                 |
| 1 | one                   |
| n | other (anything else) |

However, decimal numbers (even `1.0`) always use the `other` form:

```
There are 0.0 messages in your inbox.
```

### Exact Forms[​](#exact-forms "Direct link to Exact Forms")

Going back to our example, what if we specifically want to display `There are no messages` when `messagesCount = 0`? This is where exact forms come in handy:

```
<p>

  <Plural

    value={messagesCount}

    _0="There are no messages"

    one="There's # message in your inbox"

    other="There are # messages in your inbox"

  />

</p>
```

tip

MessageFormat allows exact forms, like `=0`. However, JSX props can't start with `=` and can't be numbers either, so we need to write `_N` instead of `=0`.

It works with any number, allowing for extensive customization as follows:

```
<p>

  <Plural

    value={messagesCount}

    _0="There are no messages"

    _1="There's one message in your inbox"

    _2="There are two messages in your inbox, that's not much!"

    other="There are # messages in your inbox"

  />

</p>
```

Exact matches always take precedence over plural forms.

### Variables and Components[​](#variables-and-components "Direct link to Variables and Components")

Let's go back to our original pluralized message:

```
<p>

  <Plural value={messagesCount} one="There's # message in your inbox" other="There are # messages in your inbox" />

</p>
```

To include variables or components within messages, simply wrap them in the [`Trans`](https://lingui.dev/ref/macro.md#trans) macro or use template literals (for example, with a variable `name`):

```
<p>

  <Plural

    value={messagesCount}

    one={`There's # message in your inbox, ${name}`}

    other={

      <Trans>

        There are <strong>#</strong> messages in your inbox, {name}

      </Trans>

    }

  />

</p>
```

Nested macros, components, variables, and expressions are all supported, providing the flexibility needed for any use case.

## Internationalization Outside of Solid[​](#internationalization-outside-of-solid "Direct link to Internationalization Outside of Solid")

So far, we have learned how to translate strings within a JSX element. However, what if we need to translate content that is outside JSX or pass a translation as a prop to another component?

In our example, we have the following code:

```
const markAsRead = () => {

  alert("Marked as read.");

};
```

To translate it, we will use the [`useLingui`](https://lingui.dev/ref/macro.md#uselingui) macro hook:

```
import { useLingui } from "@lingui/solid/macro";



const { t } = useLingui();



const markAsRead = () => {

  alert(t`Marked as read.`);

};
```

Now the `Marked as read.` message would be picked up by the extractor, and available for translation in the catalog.

You could also pass variables and use any other macro in the message:

```
const { t } = useLingui();



const markAsRead = () => {

  const userName = "User1234";

  alert(t`Hello ${userName}, your messages marked as read!`);

};
```

tip

You can also use this approach to translate element attributes, such as `alt` in an `img` tag:

```
import { useLingui } from "@lingui/solid/macro";



export default function ImageWithCaption() {

  const { t } = useLingui();



  return <img src="..." alt={t`Image caption`} />;

}
```

caution

All Core Macros cannot be used at the module level. They must be used within a component or function. See the [Macros](https://lingui.dev/ref/macro.md#using-macros) documentation for more information.

## Review[​](#review "Direct link to Review")

After all modifications, the final i18n-ready component looks like this:

src/Inbox.js

```
import { createMemo } from "solid-js";

import { Trans, Plural, useLingui } from "@lingui/solid/macro";



export default function Inbox() {

  const { i18n, t } = useLingui();

  const messages = [{}, {}];

  const messagesCount = messages.length;

  const lastLogin = new Date();

  const markAsRead = () => {

    alert(t`Marked as read.`);

  };



  const dateFormatter = createMemo(() => new Intl.DateTimeFormat(i18n().locale));



  return (

    <div>

      <h1>

        <Trans>Message Inbox</Trans>

      </h1>



      <p>

        <Trans>

          See all <a href="/unread">unread messages</a>

          {" or "}

          <a onClick={markAsRead}>mark them</a> as read.

        </Trans>

      </p>



      <p>

        <Plural

          value={messagesCount}

          one="There's # message in your inbox"

          other="There are # messages in your inbox"

        />

      </p>



      <footer>

        <Trans>Last login on {dateFormatter().format(lastLogin)}.</Trans>

      </footer>

    </div>

  );

}
```

That's it for this tutorial! For more details, see the reference documentation or check out additional tutorials. Happy Internationalizing!

## See Also[​](#see-also "Direct link to See Also")

* [`@lingui/solid` Reference](https://lingui.dev/ref/solid.md)
* [Examples](https://lingui.dev/examples.md)


---