# 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 }}

    />

  );

};
```