|
| 1 | +--- |
| 2 | +title: Lazy Translations |
| 3 | +description: Lazy translations allow you to defer translation of a message until it is actually displayed |
| 4 | +--- |
| 5 | + |
| 6 | +# Lazy Translations |
| 7 | + |
| 8 | +Lazy translation allows you to defer translation of a message until it's rendered, giving you flexibility in how and where you define messages in your code. With lazy translation, you can tag a string with the [`msg`](/docs/ref/macro.mdx#definemessage) macro to create a _message descriptor_ that can be saved, passed around as a variable, and rendered later. |
| 9 | + |
| 10 | +## Usage Example |
| 11 | + |
| 12 | +To render the message descriptor as a string-only translation, pass it to the [`i18n._()`](/docs/ref/core.md#i18n._) method: |
| 13 | + |
| 14 | +```jsx |
| 15 | +import { msg } from "@lingui/core/macro"; |
| 16 | +import { i18n } from "@lingui/core"; |
| 17 | + |
| 18 | +const favoriteColors = [msg`Red`, msg`Orange`, msg`Yellow`, msg`Green`]; |
| 19 | + |
| 20 | +export function getTranslatedColorNames() { |
| 21 | + return favoriteColors.map((color) => i18n._(color)); |
| 22 | +} |
| 23 | +``` |
| 24 | + |
| 25 | +## Usage in React |
| 26 | + |
| 27 | +To render the message descriptor in a React component, pass its `id` to the [`Trans`](/docs/ref/react.md#trans) component as a value of the `id` prop: |
| 28 | + |
| 29 | +```jsx |
| 30 | +import { msg } from "@lingui/core/macro"; |
| 31 | +import { Trans } from "@lingui/react"; |
| 32 | + |
| 33 | +const favoriteColors = [msg`Red`, msg`Orange`, msg`Yellow`, msg`Green`]; |
| 34 | + |
| 35 | +export default function ColorList() { |
| 36 | + return ( |
| 37 | + <ul> |
| 38 | + {favoriteColors.map((color) => ( |
| 39 | + <li> |
| 40 | + <Trans id={color.id} /> |
| 41 | + </li> |
| 42 | + ))} |
| 43 | + </ul> |
| 44 | + ); |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +:::info Important |
| 49 | +Please note that we import the `<Trans>` component from `@lingui/react` to use the runtime version, as the message is already defined and we don't need the compile-time macro here. |
| 50 | +::: |
| 51 | + |
| 52 | +### Picking a Message Based on a Variable |
| 53 | + |
| 54 | +Sometimes you need to choose 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 that represents the current status. |
| 55 | + |
| 56 | +An easy way to do this is to create an object that maps the possible values of "status" to message descriptors (tagged with the [`msg`](/docs/ref/macro.mdx#definemessage) macro) and render them as needed with deferred translation: |
| 57 | + |
| 58 | +```jsx |
| 59 | +import { msg } from "@lingui/core/macro"; |
| 60 | +import { useLingui } from "@lingui/react"; |
| 61 | + |
| 62 | +const statusMessages = { |
| 63 | + ["STATUS_OPEN"]: msg`Open`, |
| 64 | + ["STATUS_CLOSED"]: msg`Closed`, |
| 65 | + ["STATUS_CANCELLED"]: msg`Cancelled`, |
| 66 | + ["STATUS_COMPLETED"]: msg`Completed`, |
| 67 | +}; |
| 68 | + |
| 69 | +export default function StatusDisplay({ statusCode }) { |
| 70 | + const { _ } = useLingui(); |
| 71 | + return <div>{_(statusMessages[statusCode])}</div>; |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +### Memoization Pitfall |
| 76 | + |
| 77 | +In the following contrived example, we document how a welcome message will or will not be updated when locale changes. The documented behavior may not be intuitive at first, but it is expected, because of the way the `useMemo` dependencies work. |
| 78 | + |
| 79 | +To avoid bugs with stale translations, use the `_` function returned from the [`useLingui`](/docs/ref/react.md#uselingui) hook: it is safe to use with memoization because its reference changes whenever the Lingui context updates. |
| 80 | + |
| 81 | +:::tip |
| 82 | +You can also use the `t` function from the [`useLingui`](/docs/ref/macro.mdx#uselingui) macro hook, which behaves the same way as `_` from the runtime [`useLingui`](/docs/ref/react.md#uselingui) counterpart. |
| 83 | +::: |
| 84 | + |
| 85 | +Keep in mind that `useMemo` is primarily a performance optimization tool in React. Because of this, there might be no need to memoize your translations. Additionally, this issue is not present when using the `Trans` component, which we recommend using whenever possible. |
| 86 | + |
| 87 | +```jsx |
| 88 | +import { msg } from "@lingui/core/macro"; |
| 89 | +import { i18n } from "@lingui/core"; |
| 90 | +import { useLingui } from "@lingui/react"; |
| 91 | + |
| 92 | +const welcomeMessage = msg`Welcome!`; |
| 93 | + |
| 94 | +// ❌ Bad! This code won't work |
| 95 | +export function Welcome() { |
| 96 | + const buggyWelcome = useMemo(() => { |
| 97 | + return i18n._(welcomeMessage); |
| 98 | + }, []); |
| 99 | + |
| 100 | + return <div>{buggyWelcome}</div>; |
| 101 | +} |
| 102 | + |
| 103 | +// ❌ Bad! This code won't work either because the reference to i18n does not change |
| 104 | +export function Welcome() { |
| 105 | + const { i18n } = useLingui(); |
| 106 | + |
| 107 | + const buggyWelcome = useMemo(() => { |
| 108 | + return i18n._(welcomeMessage); |
| 109 | + }, [i18n]); |
| 110 | + |
| 111 | + return <div>{buggyWelcome}</div>; |
| 112 | +} |
| 113 | + |
| 114 | +// ✅ Good! `useMemo` has i18n context in the dependency |
| 115 | +export function Welcome() { |
| 116 | + const linguiCtx = useLingui(); |
| 117 | + |
| 118 | + const welcome = useMemo(() => { |
| 119 | + return linguiCtx.i18n._(welcomeMessage); |
| 120 | + }, [linguiCtx]); |
| 121 | + |
| 122 | + return <div>{welcome}</div>; |
| 123 | +} |
| 124 | + |
| 125 | +// 🤩 Better! `useMemo` consumes the `_` function from the Lingui context |
| 126 | +export function Welcome() { |
| 127 | + const { _ } = useLingui(); |
| 128 | + |
| 129 | + const welcome = useMemo(() => { |
| 130 | + return _(welcomeMessage); |
| 131 | + }, [_]); |
| 132 | + |
| 133 | + return <div>{welcome}</div>; |
| 134 | +} |
| 135 | +``` |
0 commit comments