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:
import { Trans } from 'react-i18next';
function MyComponent({ name, count }) {
return (
<Trans
i18nKey="userMessagesUnread"
count={count}
values={{ name }}
components={{ bold: <strong />, inbox: <Link to="/msgs" /> }}
/>
);
}
{
"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:
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:
<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:
{
"myKey": "This is a <CustomLink href=\"https://example.com/\">link to example.com</CustomLink>."
}
<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:
{
"myKey": "This is a <0 href=\"https://example.com/\">link to example.com</0>."
}
<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:
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:
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>
);
}
{
"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:
- Run
i18next-cli extract: it writes the string into your translation file. - Set
debug: trueini18next.init()and look for the missing key in the console. - Use saveMissing to send the string to your backend or to a function of your own.
- Inspect the
<Trans>element with the React Developer Tools: the tag's number is the element's index inprops.children.
The numbers come from the children like this. For the example above:
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
]
{
"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, wherexis 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
<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>
{
"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(defaulttrue): 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:
<Trans i18nKey="list_map">
My dogs are named: <ul i18nIsDynamicList>
{['rupert', 'max'].map(dog => <li key={dog}>{dog}</li>)}
</ul>
</Trans>
{
"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:
<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:
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:
<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:
// a reusable type helper
type TransInterpolation = Record<string, string | number>;
<Trans>
Hello <i>{{name} as TransInterpolation}</i>
</Trans>
Or cast to any:
<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:
const messages = ['message one', 'message two'];
<Trans i18nKey="newMessages" count={messages.length}>
You have {{ count: messages.length }} messages.
</Trans>
// -> You have 2 messages.
{
"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'(withnsSeparator); with text as keys, use thensprop instead:<Trans i18nKey="myKey" ns="myNS"></Trans>.ns(string): the namespace.t(function): thetfunction to use instead of the one from the nearest provider or the global instance, for example fromuseTranslation('myNamespace').count(number): the value for plurals; see Plural.context(string): the value for context.tOptions(object): more options fort(), such ascontextorpostProcess.parent(node): a component to wrap the content in (set it for all withdefaultTransParent).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;Transalways decodes HTML entities such as< & >to< & >, and warns when the prop is set.
i18next options
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).