Messages and context
Write complete source messages, explain their meaning, and insert changing values without changing their identity.
A translated message needs enough information to preserve the action or meaning behind the words. Write the complete source text and explain its use in context. Supply names, counts, and other changing data through values.
import { useLingo } from "@lingo.dev/react";
export function Greeting({ name }: { name: string }) {
const l = useLingo();
return (
<h1>
{l.text("Welcome back, {name}.", {
context: "Greeting at the top of the account dashboard",
values: { name },
})}
</h1>
);
}The result is a string. TextOptions requires context: string and accepts values?: Record<string, string | number>. The catalog contains the sentence template; a translation can move {name} to the position its grammar requires.
Explain what an ambiguous message means #
“Save” can mean submitting a form or bookmarking an article. Context makes those separate messages even though their English source is identical:
import { computeKey } from "@lingo.dev/react";
const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");The keys differ. A translator can choose the right verb for each action. Context such as “Text shown to a user” does not resolve that ambiguity; describe the action, audience, or constraint that could change the wording.
The extractor writes this information into the catalog's @context comment. It is guidance for translation, not visible interface text. Put recurring terminology, instructions, and voice requirements in the localization engine's translation context, while keeping message-specific meaning with the call.
Message identity #
computeKey(source: string, context?: string): string generates an eight-character key from the source and context. It joins a nonempty context to the source with a null separator, normalizes the combined input to Unicode NFC, and hashes its UTF-8 bytes.
Canonically equivalent Unicode spellings share a key. Editing wording, punctuation, capitalization, whitespace, or context can produce a new one. Values do not enter the hash, so every name in the greeting uses the same message entry.
After changing the source or context, extract again and inspect the new and orphaned entries. Copying a translation under the new key without checking its meaning can preserve the very wording the source change was meant to replace. Hashes are finite; the extractor detects collisions among the messages it collects.
Keep calls extractable #
Use literal source strings and literal context in calls such as l.text(...). The runtime can receive a computed string, but the extractor cannot infer every string the program might construct. Keep the receiver as l, or a supported variable created from useLingo or createLingo. The extract reference describes the recognized forms.
Use placeholders for changing data rather than generating source strings such as "Welcome, " + name. A stable template can be extracted, translated once per meaning, and reused for each value.
Interpolation and ICU #
Simple placeholders use names such as {name}. Supplied values become text. Missing simple values remain visible, and omitting the values object returns the selected template without interpolation.
For grammar that depends on a quantity or category, the text formatter supports complex ICU patterns through intl-messageformat:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
context: "Number of files attached to a message",
values: { count: 0 },
});This returns No files. The explicit =0 branch distinguishes zero from the locale's ordinary plural categories. Supply every argument the selected template needs. If complex ICU parsing or formatting fails, the runtime returns that template and reports a deduplicated development error; it does not replace a malformed translation with a newly formatted source.
Plurals and selects provides helpers for complete alternatives. Rich text inserts React elements through a separate named-tag parser. Use the appropriate form rather than mixing complex ICU expressions into rich templates.