Localize rich interactive messages
Translate a complete sentence while React code retains control of its links, components, and values.
“Read the policy before continuing” is one sentence, even when “policy” is a link. Keeping it as one translation lets another language move the link to the right place without moving control of its destination out of application code.
The React package's rich method represents that link as a named slot. The catalog supplies the sentence; a React renderer supplies the component for that slot.
Render one complete linked sentence #
Install @lingo.dev/react in an existing React 19 application. This local example uses an illustrative Spanish catalog and needs no translation request:
npm install @lingo.dev/reactimport { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";
const messages = {
[computeKey(
"Read the <policy>policy</policy> before continuing.",
"Notice before account creation",
)]: "Antes de continuar, lee la <policy>política</policy>.",
};
function ConsentNotice() {
const l = useLingo();
return (
<p>
{l.rich("Read the <policy>policy</policy> before continuing.", {
context: "Notice before account creation",
tags: {
policy: (children) => <a href="/policy">{children}</a>,
},
})}
</p>
);
}
export function App() {
return (
<LingoProvider locale="es" messages={messages}>
<ConsentNotice />
</LingoProvider>
);
}The paragraph should read “Antes de continuar, lee la política.” The translated sentence moves the policy reference, while the link still points to /policy. The literal source and context in the call also make the message recognizable to extraction. computeKey constructs the fixture's real identity instead of relying on an invented hash.
The provider currently uses React 19 context syntax, despite the package declaring React 18/19 peers. Verify React 18 separately. The React quickstart explains the provider setup and first catalog.
Keep values and behavior in code #
The policy name identifies a slot, not an HTML element supplied by a translator. Its renderer owns the destination and behavior. Resolve a locale-specific destination from a known route mapping in code; keep event handlers and arbitrary HTML attributes out of the catalog.
For changing values, use named placeholders:
const greeting = l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});
const countLabel = l.plural(
count,
{ one: "# item", other: "# items" },
{ context: "Number of items in the cart" },
);
const roleLabel = l.select(
role,
{ admin: "Administrator", other: "Member" },
{ context: "Account role label" },
);These calls belong inside a component with const l = useLingo() and application values for name, count, and role. text returns plain text, plural resolves count-dependent grammar, and select matches an exact selector with an other fallback. The rich path supports named tags and simple value interpolation; it does not run the text path's complex ICU formatter. Use plurals, dates, and numbers for those runtime decisions.
Keep the source static. Putting a person's name into the source string would create different source text for each person and prevent reliable extraction. Context should explain the use, such as “Account role label,” because source and context together determine identity. Change context deliberately once translations exist.
Replace the local fixture with extracted catalogs #
With the current CLI installed, run:
lingo extract --src src --source-locale enWithout path overrides, this writes locales/en.jsonc and lingo.d.ts. Inspect the extracted source, context, and key. Include the declaration in the application's TypeScript configuration. Extraction supports recognizable message calls; it does not discover arbitrary dynamically generated source strings.
Follow the CLI quickstart to authenticate and link a localization engine, then select this actual locales/en.jsonc source and the required target locales in .lingo/config.json. Translate and retrieve the catalog through that file workflow. Use the catalog-loading procedure to parse JSONC, select active keys from the matching source revision, and supply target strings to the provider. The general file translator does not preserve source catalog comments in target output.
Load the same notice with the retrieved Spanish catalog. Missing or empty entries fall back to source text, so compare required target keys as well as visible output.
Test the interaction and malformed cases #
Follow the policy link with a keyboard and check its accessible name. Read the surrounding punctuation after the link moves. A complete translation must preserve both the sentence's meaning and the action available to the reader.
In a local catalog fixture, remove the tag handler, introduce an unknown tag, and leave a tag unclosed. The current renderer leaves unknown or unpaired markup as text; same-name nesting has limited pairing behavior. It is not an arbitrary HTML renderer or a validator that rejects every malformed message.
For plain text, check missing values and malformed complex ICU: unresolved placeholders or the unformatted template can remain visible, with development diagnostics. For count and role messages, test target-language plural categories and an unknown role. Use the rich-text reference and React testing guidance for the exact behavior behind these checks.