Rich text messages
Translate a complete sentence while keeping link destinations and React behavior in application code.
A link often belongs inside a sentence. Translating the words before, inside, and after it separately forces the translation to retain the source language's word order. l.rich keeps the whole sentence translatable and lets the translated template place named React elements where they belong.
Keep the sentence together #
import { useLingo } from "@lingo.dev/react";
export function PurchaseNotice({ product }: { product: string }) {
const l = useLingo();
return (
<p>
{l.rich("Read the <link>refund policy</link> before buying {product}.", {
context: "Purchase notice linking to the refund policy",
values: { product },
tags: {
link: (children) => <a href="/refund-policy">{children}</a>,
},
})}
</p>
);
}Render this component beneath a provider. The source and context select the catalog entry just as they do for l.text. The translated template controls the words and tag placement; the callback supplies the destination, attributes, styling, and behavior.
l.rich returns a ReactNode. Its RichOptions requires context, accepts a string/number values map, and accepts tags: Record<string, (children: ReactNode) => ReactNode>. Tag names match exactly, so <link> needs a link callback.
Insert an element without children #
A self-closing tag calls its renderer with null children. For example, this confirmation places a decorative icon after the message:
const confirmation = l.rich("Saved <icon/>", {
context: "Confirmation that account settings were saved",
tags: {
icon: () => <span aria-hidden="true">✓</span>,
},
});Here l is the component's useLingo() result. Both <icon/> and <icon /> are supported. For nested elements, use distinct names, such as <link><strong>refund policy</strong></link>, and supply both callbacks. The parser uses the next matching closing tag; repeated same-name nesting is not a supported balanced-HTML structure.
Check translated tags as well as words #
When a paired or self-closing tag has no callback, it remains literal text. An opening tag without a matching close also remains literal. This keeps the message renderable, but a reader can see <link> instead of a usable link.
Test the translated template with its real callbacks. Assert the link text and href, and include a missing-tag case so accidental markup is visible during development. Rendering tests need no translation request.
The supported markup consists of named tags, not arbitrary HTML. Put attributes in the callback instead of writing them into the translation. Using dangerouslySetInnerHTML to handle an unmatched tag would discard that separation.
Use simple values in rich messages #
Rich text replaces simple {name} values in text segments. It does not run the complex ICU formatter used by l.text. For quantity-dependent grammar, use plurals and selects, or arrange the interface around complete grammatical messages that the supported rich representation can express. A raw ICU plural inside a rich template will not gain plural behavior merely because it contains braces.