Common i18n patterns in React¶
Following page describes the most common i18n patterns in React. It’s a follow-up to tutorial with practical examples. See the API reference for detailed information about all components.
Macros¶
Using jsx macros is the most straightforward way how to translate your React components.
<Trans> handles translations of messages including variables and other React components:
import { Trans } from "@lingui/macro"
<h1><Trans>LinguiJS example</Trans></h1>
<p><Trans>Hello <a href="/profile">{name}</a>.</Trans></p>
You don’t need anything special to use <Trans> inside your app (except of wrapping the root component in <I18nProvider>).
Using ID generated from message¶
Using custom ID¶
With <Trans>¶
If you’re using custom IDs in your project, add id
prop to i18n components:
import { Trans } from "@lingui/macro"
<h1><Trans id="msg.header">LinguiJS example</Trans></h1>
<p><Trans id="msg.hello">Hello <a href="/profile">{name}</a>.</Trans></p>
Messages msg.header
and msg.hello
will be extracted with default values
LinguiJS example
and Hello <0>{name}</0>.
.
With t¶
If you’re using custom IDs in your project, call t with ID as a first argument and then use string templates as usual:
import { useLingui } from "@lingui/react"
import { t } from "@lingui/macro"
export default function ImageWithCaption() {
const { i18n } = useLingui()
return <img src="..." alt={i18n._(t('msg.caption')`Image caption`)} />
}
Message msg.caption
will be extracted with default value Image caption
.
For all other js macros (plural, select, selectOrdinal),
pass ID as the first param (in this case, 'msg.caption'
):
import { useLingui } from "@lingui/react"
import { plural } from "@lingui/macro"
export default function ImageWithCaption({ count }) {
const { i18n } = useLingui()
return (
<img src="..." alt={i18n._(plural('msg.caption', {
value: count,
one: "# image caption",
other: "# image captions",
}))} />
)
}
Element attributes and string-only translations¶
Sometimes you can’t use <Trans> component, for example when translating element attributes:
<img src="..." alt="Image caption" />
In such case you need to use i18n
object and t macro to wrap message:
Use
withI18n()
HOC oruseLingui()
hook from@lingui/react
, to accessi18n
object.Call
i18n._()
to translate message wrapped in JS macros. t is equivalent for <Trans>, plural is equivalent to <Plural>.
// using the withI18n HOC
import { withI18n } from "@lingui/react"
import { t } from "@lingui/macro"
function ImageWithCaption({ i18n }) {
return <img src="..." alt={i18n._(t`Image caption`)} />
}
export default withI18n(ImageWithCaption)
// using the useLingui hook
import { useLingui } from "@lingui/react"
import { t } from "@lingui/macro"
export default function ImageWithCaption() {
const { i18n } = useLingui()
return <img src="..." alt={i18n._(t`Image caption`)} />
}
Translations outside React components¶
Another common pattern is when you need to access translations (i18n
object)
outside React components, for example inside redux-saga
:
Create your own instance of
i18n
usingsetupI18n()
form@lingui/core
Pass this instance as
i18n
prop to <I18nProvider>.// App.js import { setupI18n } from "@lingui/core" import { I18nProvider } from "@lingui/react" export const i18n = setupI18n() export default function App() { return ( <I18nProvider i18n={i18n}> {/* Our app */} </I18nProvider> ) }
Whenever you are outside React context (i.e. you can’t access props), you can use this
i18n
object.import { i18n } from "./App.js" import { t } from "@lingui/macro" export function alert() { // use i18n as if you were inside a React component alert(i18n._(t`...`)) }
Lazy translations¶
Messages don’t have to be declared at the same code location where they’re displayed.
Tag a string with the t macro, and you’ve created a “message descriptor”, which
can then be passed around as a variable, and can be displayed as a translated string by
passing it to <Trans> as its id
prop:
import { t, Trans } from "@lingui/macro"
const favoriteColors = [
t`Red`,
t`Orange`,
t`Yellow`,
t`Green`,
]
export default function ColorList() {
return (
<ul>
{favoriteColors.map(color => (
<li><Trans id={color}/></li>
}
</ul>
)
}
Or to render the message descriptor as a string-only translation, just pass it to
the I18n._()
method as usual:
import { t } from "@lingui/macro"
const favoriteColors = [
t`Red`,
t`Orange`,
t`Yellow`,
t`Green`,
]
const translatedColorNames = favoriteColors.map(
color => i18n._(color)
)
Passing messages as props¶
It’s often convenient to pass messages around as component props, for example as a “label” prop on a button. The easiest way to do this is to pass a <Trans> element as the prop:
import { Trans } from "@lingui/macro"
export default function FancyButton(props) {
return <button>{props.label}</button>
}
export function LoginLogoutButtons(props) {
return <div>
<FancyButton label={<Trans>Log in</Trans>} />
<FancyButton label={<Trans>Log out</Trans>} />
</div>
}
If you need the prop to be displayed as a string-only translation, you can pass a message descriptor (tagged with the t macro), and have the component render it as a string using lazy translation:
import { t } from "@lingui/macro"
import { useLingui } from "@lingui/react"
export default function ImageWithCaption(props) {
const { i18n } = useLingui()
return <img src="..." alt={i18n._(props.caption)} />
}
export function HappySad(props) {
return <div>
<ImageWithCaption caption={t`I'm so happy!`} />
<ImageWithCaption caption={t`I'm so sad.`} />
</div>
}
Picking a message based on a variable¶
Sometimes you need to pick between different messages to display, depending on the value of a variable. For example, imagine you have a numeric “status” code that comes from an API, and you need to display a message representing the current status.
A simple way to do this, is to make an object that maps the possible values of “status” to message descriptors (tagged with the t macro), and render them as needed with lazy translation:
import { Trans } from "@lingui/macro";
const STATUS_OPEN = 1,
STATUS_CLOSED = 2,
STATUS_CANCELLED = 4,
STATUS_COMPLETED = 8
const statusMessages = {
[STATUS_OPEN]: t`Open`,
[STATUS_CLOSED]: t`Closed`,
[STATUS_CANCELLED]: t`Cancelled`,
[STATUS_COMPLETED]: t`Completed`,
}
export default function StatusDisplay(statusCode) {
return <div><Trans id={statusMessages[statusCode]} /></div>
}