Important note

While the Trans components gives you a lot of power by letting you interpolate or translate complex react elements - the truth is - in most cases you won't need it.

As long you have no react nodes you like to be integrated into a translated text (text formatting, like strong, i, ...) or adding some link component - you won't need it - most can be done by using the good old t function.

Samples

Using with react components

So you learned there is no need to use the Trans component everywhere (the plain t function will just do fine in most cases).

This component enables you to nest any react content to be translated as one string. Supports both plural and interpolation.

Let's say you want to create following html output:

Hello Arthur, you have 42 unread messages. Go to messages.

Before: Your react code would have looked something like:

<div>
  Hello <strong title="this is your name">{name}</strong>, you have {count} unread message(s). <Link to="/msgs">Go to messages</Link>.
</div>

After: With the trans component just change it to:

<Trans i18nKey="userMessagesUnread" count={count}>
  Hello <strong title={t('nameTitle')}>{{name}}</strong>, you have {{count}} unread message. <Link to="/msgs">Go to messages</Link>.
</Trans>

Your en.json (translation strings) will look like:

"userMessagesUnread": "Hello <1>{{name}}</1>, you have {{count}} unread message. <5>Go to message</5>.",
"userMessagesUnread_plural": "Hello <1>{{name}}</1>, you have {{count}} unread messages.  <5>Go to messages</5>.",

Using for <br /> and other simple html elements in translations (v10.4.0)

It allows you to have basic html tags inside your translations which will get converted to valid react elements:

<Trans i18nKey="welcomeUser">
  Hello <strong>{{name}}</strong>.
</Trans>
// JSON -> "welcomeUser": "Hello <strong>{{name}}</strong>.",
<Trans i18nKey="multiline">
  Some newlines <br/> would be <br/> fine
</Trans>
// JSON -> "multiline": "Some newlines <br/> would be <br/> fine"

You can use i18next.options.react to adapt this behaviour:

Using with lists (v10.5.0)

You can use list.map as children. Mapping dynamic content.

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

Setting i18nIsDynamicList on the wrapping element will assert the nodeToString function creating the string for saveMissing will not contain children.

Alternative usage

Depending on using ICU as translation format it is not possible to have the needed syntax as children (invalid jsx). You can alternatively use the component like:

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

How to get the correct translation string?

Guessing replacement tags (<0></0>) of your component right is rather difficult. There are two options to get those translations directly generated by i18next.

1. use debug = true in i18next init call and watch your console for the missing key output

2. use the saveMissing feature of i18next to get those translations pushed to your backend or handled by a custom missing key handler.

3. understand how those numbers get generated from child index:

jsx:

<Trans i18nKey="userMessagesUnread" count={count}>
    Hello <strong title={t('nameTitle')}>{{name}}</strong>, you have {{count}} unread message. <Link to="/msgs">Go to messages</Link>.
</Trans>

results in string:

"Hello <1>{{name}}</1>, you have {{count}} unread message. <5>Go to message</5>."

based on the node tree:

Trans.children = [
  'Hello ',                           // index 0: only a string
  { children: [{ name: 'Jan'  }] },   // index 1: element strong -> child object for interpolation
  ', you have',                       // index 2: only a string
  { count: 10 },                      // index 3: just object for interpolation
  ' unread messages. ',               // index 4
  { children: [ 'Go to messages' ] }, // index 5: element link -> child just a string
  '.'
]

Rules:

• child is a string => nothing to wrap just take the string

• child is an object => nothing to to it's used for interpolation

• child is an element: wrap it's children in <i></i> where i is the index of that element position in children and handle it's children with same rules (starting element.children index at 0 again)

Trans props

Additional options on i18next.init

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 - required before react 16
    transEmptyNodeValue: '', // what to return for empty Trans
    transSupportBasicHtmlNodes: true, // allow <br/> and simple html elements in translations
    transKeepBasicHtmlNodesFor: ['br', 'strong', 'i'], // don't convert to <1></1> if simple react elements
  }
});