Skip to main content

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​

npm install --save @lingui/react

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 component.
  • Locally: Use the render or component props on individual i18n components.

Global Configuration​

You can set a default rendering component using the defaultComponent prop in 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​

You can customize how translations are rendered locally within individual i18n components using the following props:

Prop nameTypeDescription
classNamestringClass name to be added to <span> element
renderFunction(props) -> Element | nullCustom render callback to render translation
componentComponent | nullReact component to wrap the translation
commentstringComment 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​

  • 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​

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​

Message catalogs and the active locale are provided through the context in the I18nProvider. You can access this context using the 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​

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 nameTypeDescription
i18nI18nThe I18n object instance (usually the one imported from @lingui/core)
childrenReact.ReactNodeReact Children node
defaultComponentReact.ComponentTypeA 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 section at the beginning of this document.

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​

The useLingui hook provides access to the Lingui context. It returns an object with the following properties:

KeyTypeDescription
i18nI18nThe I18n object instance that you passed to I18nProvider
_I18n[_]Reference to the i18n._ function, explained below
defaultComponentReact.ComponentTypeThe 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).

To alleviate the issue, useLingui provides the _ function, which is the same as 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 of the useLingui hook which supports all features of the t macro 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.

Server APIs​

Import these APIs from @lingui/react/server. Use setI18n during a Server Component render. React 19+ Server Functions (also called Server Actions when used for mutations) can use runWithI18n when downstream helpers need ambient access to the current instance.

If the function doing the translation already has an i18n instance, call i18n.t(...) directly.

I18nContext​

I18nContext is exported as a type from @lingui/react/server. It is the value returned by getI18n and getI18nOrThrow:

import type { I18nContext } from "@lingui/react/server";

type I18nContext = {
  i18n: I18n;
  _: I18n["_"];
  defaultComponent?: React.ComponentType<TransRenderProps>;
};

setI18n​

Stores an I18n instance in the current Server Component render cache:

setI18n(i18n, defaultComponent?);

Call it in every page or layout that starts an RSC render. A nested RSC render does not inherit a runWithI18n context and needs its own setI18n call.

setI18n only works during a Server Component render. Called elsewhere (for example, inside a Server Function) it warns in development and does nothing — use runWithI18n there instead.

runWithI18n​

Makes an I18n instance available to a callback and the asynchronous work created inside it:

const result = await runWithI18n(i18n, async () => {
  await loadData();
  return getI18nOrThrow().i18n.t(message);
});

The callback result is returned unchanged. Nested and concurrent scopes are isolated, and the previous scope is restored when the callback finishes or throws.

The optional third defaultComponent argument has the same meaning as in setI18n.

runWithI18n works in any runtime that provides AsyncLocalStorage from node:async_hooks: Node.js, the Vercel Edge Runtime, and Cloudflare Workers (enable the nodejs_compat or nodejs_als compatibility flag). Keep the asynchronous work inside the callback on native promises, as edge runtimes can lose context across custom thenables.

AsyncLocalStorage keeps a reference to i18n; it does not clone the instance. Create a separate instance for each Server Function invocation instead of mutating one global instance from concurrent requests.

getI18n​

Returns the current I18nContext, or null outside an initialized Server Component render or runWithI18n scope:

const lingui = getI18n();

Use this nullable form when the context is optional.

getI18nOrThrow​

Returns the current I18nContext. It throws with setup guidance when no context is active:

const { i18n } = getI18nOrThrow();

Use this form in helpers that require Lingui to be initialized.

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

Prop nameTypeDescription
idstringKey, the message ID
messagestringDefault message
valuesobjectVariables 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 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​

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​

If for some reason you cannot use Macros, you can render plurals using the simple Trans component by passing the ICU MessageFormat 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 }}
    />
  );
};