View as Markdown
On this page

Trans component

Trans keeps markup and links inside one translatable sentence, so translators see it whole.

When you need it

Only when markup or components (strong, em, a link) sit inside a sentence. For everything else, use t() from useTranslation.

Trans does not load translations: it uses the i18next instance, and the translations load through useTranslation. It renders again when the language changes, like useTranslation.

Named components

Name each component in components and use the name as a tag in the translation:

jsx
import { Trans } from 'react-i18next';

function MyComponent({ name, count }) {
  return (
    <Trans
      i18nKey="userMessagesUnread"
      count={count}
      values={{ name }}
      components={{ bold: <strong />, inbox: <Link to="/msgs" /> }}
    />
  );
}
translation.json
{
  "userMessagesUnread_one": "Hello <bold>{{name}}</bold>, you have {{count}} unread message. <inbox>Go to messages</inbox>.",
  "userMessagesUnread_other": "Hello <bold>{{name}}</bold>, you have {{count}} unread messages. <inbox>Go to messages</inbox>."
}

With name: 'Arthur' and count: 42 this renders:

html
Hello <strong>Arthur</strong>, you have 42 unread messages.
<a href="/msgs">Go to messages</a>.

values holds the interpolation values. defaults is the text when the key has no translation yet:

jsx
<Trans
  i18nKey="myKey"
  defaults="hello <italic>beautiful</italic> <bold>{{what}}</bold>"
  values={{ what: 'world' }}
  components={{ italic: <i />, bold: <strong /> }}
/>
// -> hello <i>beautiful</i> <strong>world</strong>

A named component can be used several times in one translation. When a component has children of its own, an empty tag keeps them: components={{ wrap: <a href="#"><svg /></a> }} with "myKey": "Link: <wrap></wrap>" renders the icon inside the link (<wrap/> does the same). Put text inside <wrap>...</wrap> when the translation should provide the children.

Names of self-closing HTML tags are reserved and won't work as component names, for example link: <Link />, img: <img src="" /> or media: <img src="" />.

Overriding component props

A translation can set props of a component, for example a different href per language. Values in the translation override the ones passed in components:

translation.json
{
  "myKey": "This is a <CustomLink href=\"https://example.com/\">link to example.com</CustomLink>."
}
jsx
<Trans
  i18nKey="myKey"
  components={{
    CustomLink: <MyCustomLinkComponent href="value-to-be-overridden" />
  }}
/>

This renders MyCustomLinkComponent with href="https://example.com/". It works the same with a components array and indexed tags:

translation.json
{
  "myKey": "This is a <0 href=\"https://example.com/\">link to example.com</0>."
}
jsx
<Trans
  i18nKey="myKey"
  components={[<MyCustomLinkComponent href="value-to-be-overridden" />]}
/>

Indexed children

You can also write the sentence as children. The translation then refers to each element by its position among the children.

Before:

jsx
function MyComponent({ name, count }) {
  return (
    <>
      Hello <strong title="This is your name">{name}</strong>, you
      have {count} unread message(s). <Link to="/msgs">Go to messages</Link>.
    </>
  );
}

After:

jsx
import { Trans, useTranslation } from 'react-i18next';

function MyComponent({ name, count }) {
  const { t } = useTranslation();

  return (
    <Trans i18nKey="userMessagesUnread" count={count}>
      Hello <strong title={t('nameTitle')}>{{ name }}</strong>, you
      have {{ count }} unread messages. <Link to="/msgs">Go to messages</Link>.
    </Trans>
  );
}
translation.json
{
  "nameTitle": "This is your name",
  "userMessagesUnread_one": "Hello <1>{{name}}</1>, you have {{count}} unread message. <5>Go to messages</5>.",
  "userMessagesUnread_other": "Hello <1>{{name}}</1>, you have {{count}} unread messages. <5>Go to messages</5>."
}

i18next-cli extract writes the children as the default text. The i18nKey is optional if you use the text as the key.

How to get the correct translation string?

The indexed tags (<1></1>) are hard to guess, and hard for translators too: a tag moved to the wrong place breaks the sentence, and a spreadsheet gives no clue what element 1 is. To get them generated:

  1. Run i18next-cli extract: it writes the string into your translation file.
  2. Set debug: true in i18next.init() and look for the missing key in the console.
  3. Use saveMissing to send the string to your backend or to a function of your own.
  4. Inspect the <Trans> element with the React Developer Tools: the tag's number is the element's index in props.children.

The numbers come from the children like this. For the example above:

javascript
Trans.children = [
  'Hello ',                         // 0: a string
  { children: [{ name: 'Jan' }] },  // 1: <strong> with an interpolation object
  ', you have ',                    // 2: a string
  { count: 10 },                    // 3: an interpolation object
  ' unread messages. ',             // 4: a string
  { children: ['Go to messages'] }, // 5: <Link> with a string child
  '.'                               // 6: a string
]
translation.json
{
  "userMessagesUnread_other": "Hello <1>{{name}}</1>, you have {{count}} unread messages. <5>Go to messages</5>."
}
  • A string stays as it is.
  • An object is used for interpolation.
  • An element becomes <x></x> around its children, where x is its index; its own children follow the same rules, counting from 0 again.

Simple HTML elements

Simple HTML elements keep their name in the translation instead of an index. That works for elements without attributes (like className) and with no child or a single text child:

  • <br/>
  • <strong>bold</strong>
  • <p>some paragraph</p>

These become indexed tags:

  • <i className="icon-gear" />: has an attribute
  • <strong title="something">{{name}}</strong>: has a child that is not text
  • <b>bold <i>italic</i></b>: has a nested element
jsx
<Trans i18nKey="welcomeUser">
  Hello <strong>{{ name }}</strong>. <Link to="/inbox">See my profile</Link>
</Trans>

<Trans i18nKey="multiline">
  Some newlines <br/> would be <br/> fine
</Trans>
translation.json
{
  "welcomeUser": "Hello <strong>{{name}}</strong>. <3>See my profile</3>",
  "multiline": "Some newlines <br/> would be <br/> fine"
}

Options in i18next.options.react for this:

  • transSupportBasicHtmlNodes (default true): keeps the names of simple elements in translations instead of indexes.
  • transKeepBasicHtmlNodesFor (default ['br', 'strong', 'i', 'p']): the elements whose names are kept.
  • transWrapTextNodes (default ''): wraps each text node in the element you name, for example 'span'. Text nodes are not wrapped by default. It works around pages that break when a browser translates them; see i18next options.

Lists

Set i18nIsDynamicList on the element that wraps an Array.map(). Its items then stay out of the translation string:

jsx
<Trans i18nKey="list_map">
  My dogs are named: <ul i18nIsDynamicList>
    {['rupert', 'max'].map(dog => <li key={dog}>{dog}</li>)}
  </ul>
</Trans>
translation.json
{
  "list_map": "My dogs are named: <1></1>"
}

Components array

components also takes an array; <0> in the text is the component at index 0:

jsx
<Trans
  i18nKey="myKey"
  defaults="hello <0>{{what}}</0>"
  values={{ what: 'world' }}
  components={[<strong>univers</strong>]}
/>
// -> hello <strong>world</strong>

With ICU as translation format you need this form or the named components, because the ICU syntax is not valid as JSX children.

Interpolation

Pass the values as objects in the children:

jsx
const person = { name: 'Henry', age: 21 };
const { name } = person;

<Trans>
  Hello {{ name }}.
</Trans>
// translation string: "Hello {{name}}."

<Trans>
  Hello {{ firstname: person.name }}.
</Trans>
// translation string: "Hello {{firstname}}."

TypeScript usage

TypeScript reports an error for an object inside a React element:

tsx
<Trans>
  Hello <i>{{name}}</i>
</Trans>
// Error: Object literal may only specify known properties...

React's types don't expect objects as children, but react-i18next turns them into text at run time, so a type assertion is safe:

tsx
// a reusable type helper
type TransInterpolation = Record<string, string | number>;

<Trans>
  Hello <i>{{name} as TransInterpolation}</i>
</Trans>

Or cast to any:

tsx
<Trans>
  Hello <i>{{name} as any}</i>
</Trans>

The type option allowObjectInHTMLChildren also removes the error, but it weakens type safety across your whole React app. It needs import 'react-i18next/augment-react'; next to your CustomTypeOptions declaration, and skipLibCheck: true with current @types/react (see Migrating v17 to v18).

Plural

Pass the count prop:

jsx
const messages = ['message one', 'message two'];

<Trans i18nKey="newMessages" count={messages.length}>
  You have {{ count: messages.length }} messages.
</Trans>
// -> You have 2 messages.
translation.json
{
  "newMessages_one": "You have one message.",
  "newMessages_other": "You have {{count}} messages."
}

When the children hold {{ count }} as a number, you can leave out the count prop: react-i18next takes it from the children. An explicit count prop wins, also count={0}. Without children (only i18nKey), count is required.

Trans props

All props are optional, but without i18nKey the text of the children is the key.

  • i18nKey (string): the key. It can carry the namespace as 'ns:key' (with nsSeparator); with text as keys, use the ns prop instead: <Trans i18nKey="myKey" ns="myNS"></Trans>.
  • ns (string): the namespace.
  • t (function): the t function to use instead of the one from the nearest provider or the global instance, for example from useTranslation('myNamespace').
  • count (number): the value for plurals; see Plural.
  • context (string): the value for context.
  • tOptions (object): more options for t(), such as context or postProcess.
  • parent (node): a component to wrap the content in (set it for all with defaultTransParent).
  • i18n (object): the i18next instance, if none comes from the context.
  • defaults (string): the default text instead of the children (useful for ICU).
  • values (object): interpolation values that are not in the children.
  • components (object or array): the components for named or indexed tags.
  • shouldUnescape (boolean): ignored; Trans always decodes HTML entities such as &lt; &amp; &gt; to < & >, and warns when the prop is set.

i18next options

javascript
i18next.init({
  // ...
  react: {
    // ...
    hashTransKey: function(defaultValue) {
      // return a key based on defaultValue or if you prefer to just remind you
      // should set a key return false and throw an error
    },
    defaultTransParent: 'div', // a valid React element
    transEmptyNodeValue: '', // what to return for empty Trans
    // allow <br/> and simple HTML elements in translations
    transSupportBasicHtmlNodes: true,
    // don't convert to <1></1> if simple React elements
    transKeepBasicHtmlNodesFor: ['br', 'strong', 'i', 'p'],
    // wrap text nodes in an element, e.g. 'span' (not wrapped by default)
    transWrapTextNodes: '',
    // default props for Trans: tOptions, values, components
    transDefaultProps: undefined,
  }
});

Google Translate in the browser changes the DOM of a page, which can break a React app; transWrapTextNodes: 'span' works around it (the React issue).