React API Reference

Components from @lingui/react wrap the vanilla JS API from @lingui/core. React components handle changes of active language or interpolated variables better than low-level API and also take care of re-rendering when locale or messages change.

Rendering of Translations

All i18n components render translation as text without a wrapping tag. This can be customized in two different ways:

• globally: using defaultComponent prop on I18nProvider component
• locally: using render prop or component on i18 components

Global Configuration

Default rendering component can be set using defaultComponent prop in I18nProvider. The main use case for this is rendering translations in <Text> component in React Native.

Local Configuration

Prop name	Type	Description
className	string	Class name to be added to <span> element
render	Function(props) -> Element | Component	Custom wrapper rendered as function
component	Component, null	Custom wrapper component to render translation

className is used only for built-in components (when render is string).

Function(props) props returns the translation, an id, and a message.

component is rendered with the translation passed in as its child:

import { Text } from "react-native";

<Trans component={Text}>Link to docs</Trans>;
// renders as <Text>Link to docs</Text>

To get more control over the rendering of translation, use instead the render prop with a render callback. Function passed to render will receive the translation value as a translation parameter:

// custom component
<Trans render={({ translation }) => <Icon label={translation} />}>
   Sign in
</Trans>;
// renders as <Icon label="Sign in" />

render and component also accept null value to render string without a wrapping component. This can be used to override custom defaultComponent config.

<Trans render={null}>Heading</Trans>;
// renders as "Heading"

<Trans component={null}>Heading</Trans>;
// renders as "Heading"

Lingui Context

Message catalogs and the active locale are passed to the context in I18nProvider. Use useLingui hook to access Lingui context.

I18nProvider

Prop name	Type	Description
I18n	i18n	The i18n instance (usually the one imported from @lingui/core)
children	React.ReactNode	React Children node
defaultComponent	React.ComponentType	A React component for rendering <Trans> within this component (optional)
forceRenderOnLocaleChange	boolean	Force re-render when locale changes (default: true)

defaultComponent has the same meaning as component in other i18n components. Rendering of translations is explained at the beginning of this document.

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 = ({ isTranslated, children }) => (
   <span style={{ color: isTranslated ? undefined : 'red' }}>
      {children}
   </span>
)

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

forceRenderOnLocaleChange is true by default and it ensures that:

• Children of I18nProvider aren't rendered before locales are loaded.
• When locale changes, the components consuming i18n context are re-rendered.

Disable forceRenderOnLocaleChange when you have specific needs to handle initial state before locales are loaded and when locale changes.

I18nProvider should live above all other i18n components. A good place is as a top-level application component. However, if the locale is stored in a redux store, this component should be inserted below react-redux/Provider:

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 App = () => {
   return (
      <I18nProvider i18n={i18n}>
         // rest of the app
      </I18nProvider>
   );
}

useLingui

This hook allows access to the Lingui context. It returns an object with the same values that were passed to the I18nProvider component.

Components that use useLingui hook will re-render when locale and / or catalogs change, ensuring that the translations are always up-to-date.

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

const CurrentLocale = () => {
   const { i18n } = useLingui()

   return <span>Current locale: {i18n.locale}</span>
}

Components

The @lingui/react package provides Trans component to render translations. However, you're more likely to use macros instead because they are more convenient and easier to use.

This section is intended for reference purposes.

Trans

Prop name	Type	Description
id	string	Key, the message ID

info

Import Trans macro instead of Trans component if you use macros:

import { Trans } from "@lingui/macro"

// Trans from @lingui/react won't work in this case
// import { Trans } from "@lingui/react"

<Trans>Hello, my name is {name}</Trans>

It's also possible to use Trans component directly without macros. In that case, id is the message being translated. values and components are arguments and components used for formatting translation:

<Trans id="Hello World" />;

<Trans
  id="Hello {name}"
  values={{ name: 'Arthur' }}
/>;

// number of tag corresponds to index in `components` prop
<Trans
  id="Read <link>Description</link> below."
  components={{ link: <a href="/docs" /> }}
/>

Plurals

If you cannot use @lingui/macro for some reason, you can render plurals using the plain Trans component like this:

import React from 'react';
import { Trans } from '@lingui/react';

<Trans
   id="my.plural.msg"
   message="{count, plural, =1 {car} other {cars}}"
   values={{ count: cars.length }}
></Trans>