Trans Component
Important note
While <Trans>
gives you a lot of power by letting you interpolate or translate complex React elements, the truth is: in most cases you don't even need it.
As long you have no React/HTML nodes integrated into a cohesive sentence (text formatting like strong
, em
, link components, maybe others), you won't need it - most of the times you will be using the good old t
function.
You may be looking directly for the Trans props.
It does ONLY interpolation. It does not rerender on language change or load any translations needed. Check useTranslation
hook or withTranslation
HOC for those cases.
Have a look at the i18next documentation for details on the the 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 cohesive string. It supports both plural and interpolation. The <Trans>
component will automatically use the most relevant t()
function (from the context instance or the global instance), unless overridden via the i18n
or t
props.
Let's say you want to create following HTML output:
Hello Arthur, you have 42 unread messages. Go to messages.
Before: Your untranslated React code would have looked something like:
After: With the Trans component just change it to:
Your en.json (translation strings) will look like:
saveMissing will send a valid defaultValue
based on the component children.
Also, The i18nKey
is optional, in case you already use text as translation keys.
Alternative usage which lists the components (v11.6.0)
This format is useful if you want to interpolate the same node multiple times. Another advantage is the simpler named tags, which avoids the trouble with index guessing - however, this can also be achieved with transSupportBasicHtmlNodes
, see the next section.
Existing self-closing HTML tag names are reserved keys and won't work. Examples: link: <Link />
, img: <img src="" />
, media: <img src="" />
Make sure you also adapt your translation resources to include the named tags (<italic>
) instead of the indexed tags (<0>
)!
Overriding React component props (v11.5.0)
In some cases you may want to override the props of a given component based on the active language.
This can be achieved by providing prop values inside of your translations. Such values will override whatever has been passed to the component present in the components
prop of the Trans
component.
In the example below we want our custom link component to have a different href
value based on the active language. This is how our custom link component is being used:
with the following being our translation message:
This setup will render the following JSX:
This approach also works with listed components:
With this then making up our translation message:
Usage with simple HTML elements like <br /> and others (v10.4.0)
There are two options that allow you to have basic HTML tags inside your translations, instead of numeric indexes. However, this only works for elements without additional attributes (like className
), having none or a single text children.
Examples of elements that will be readable in translation strings:
<br/>
<strong>bold</strong>
<p>some paragraph</p>
Examples that will be converted to indexed nodes:
<i className="icon-gear" />
: no attributes allowed<strong title="something">{{name}}</strong>
: only text nodes allowed<b>bold <i>italic</i></b>
: no nested elements, even simple ones
Here is what can be configured in i18next.options.react
that affect this behaviour:
Option | Default | Description |
---|---|---|
|
| Enables keeping the name of simple nodes (e.g. |
|
| Which nodes are allowed to be kept in translations during |
|
| Wrap text nodes in a user-specified element. e.g. set it to |
Interpolation
You can pass in variables to get interpolated into the translation string by using objects containing those key:values.
Plural
You will need to pass the count
prop:
Using with lists (v10.5.0)
You can still use Array.map()
to turn dynamic content into nodes, using an extra option on a wrapping element:
Setting i18nIsDynamicList
on the parent element will assert the nodeToString
function creating the string for saveMissing
will not contain children.
Alternative usage (components array)
Some use cases, such as the ICU format, might be simpler by just passing content as props:
<0>
-> 0 is the index of the component in the components array
E.g. this format is needed when using ICU as translation format as it is not possible to have the needed syntax as children (invalid jsx).
How to get the correct translation string?
Guessing replacement tags (<0></0>) of your component is rather difficult. There are four options to get those translations directly generated by i18next:
use React Developer Tools to inspect the
<Trans>
component instance and look at theprops.children
array for array index of the tag in question.use
debug = true
ini18next.init()
options and watch your console for the missing key outputuse the saveMissing feature of i18next to get those translations pushed to your backend or handled by a custom function.
understand how those numbers get generated from child index:
Sample JSX:
Resulting translation string:
The complete the node tree:
Rules:
child is a string: nothing to wrap; just take the string
child is an object: nothing to do; it's used for interpolation
child is an element: wrap it's children in
<x></x>
wherex
is the index of that element's position in thechildren
list; handle its children with the same rules (startingelement.children
index at 0 again)
Trans props
All properties are optional, although you'll need to use i18nKey
if you're not using natural language keys (text-based).
name | type (default) | description |
|
| If you prefer to use text as keys you can omit this, and the translation will be used as key. Can contain the namespace by prepending it in the form But this is not recommended when used in combination with natural language keys, better use the dedicated ns parameter: |
|
| Namespace to use. May also be embedded in |
|
|
|
|
| Numeric value for pluralizable strings |
|
| Value used for the context feature. |
|
| Extra options to pass to |
|
| A component to wrap the content into (can be globally set on |
|
| i18next instance to use if not provided by context |
|
| Use this instead of using the children as default translation value (useful for ICU) |
|
| Interpolation values if not provided in children |
|
| Components to interpolate based on index of tag |
|
| HTML encoded tags like: |
i18next options
Please be aware if you are using React 15 or below, you are required to set the defaultTransParent
option, or pass a parent
via props.
Are you having trouble when your website is ran through Google Translate?
Google Translate seems to manipulate the DOM and makes React quite unhappy!
There's a work around: you can wrap text nodes with<span>
using transWrapTextNodes: 'span'
.
If you want to know more about the Google Translate issue with React, have a look at this.
Last updated