Render your first translated message
Display a Spanish greeting, substitute a name, and check source fallback using a local catalog.
Render Hola, Ana. from an English source message. This example supplies its own Spanish translation so you can see exactly how a component, catalog, and provider work together. It needs no Lingo.dev account or API key.
Install in a React 19 application #
npm install @lingo.dev/react@1.17.1Use an existing React 19 application for this recipe. Although the package declares React 18 and 19 peers, its provider uses React 19's context-provider shorthand. Installing the package in a React 18 project does not establish that it can render there.
Add the greeting and catalog #
Put this component in src/App.tsx and render it through your application's existing entry point:
import { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";
const messages = {
[computeKey("Hello, {name}.", "Greeting on the account dashboard")]:
"Hola, {name}.",
};
function Greeting() {
const l = useLingo();
return (
<h1>
{l.text("Hello, {name}.", {
context: "Greeting on the account dashboard",
values: { name: "Ana" },
})}
</h1>
);
}
export default function App() {
return (
<LingoProvider locale="es" messages={messages}>
<Greeting />
</LingoProvider>
);
}Run your application's development command and open the page. The heading reads Hola, Ana. The runtime computes the same key from the source and context, finds the Spanish template, and replaces {name} with Ana.
The catalog contains the whole sentence, so a translation can change its word order. The name is a value, not part of the key; another name uses the same catalog entry. Keep the literal source and context in the l.text call so the extractor can discover them later.
Check what happens without a translation #
Temporarily pass messages={{}} to the provider. The heading now reads Hello, Ana. The source is the fallback template, and value substitution still runs. An entry whose value is "" also selects the source.
Restore messages, then change only the call's context to "Greeting on the profile page". That is a different message identity, so the original translation no longer matches. Restore the original context to return to Hola, Ana. These checks distinguish a missing catalog from a mismatch between the message being requested and the one translated.
Replace the local map with extracted catalogs #
The component is ready for extraction. Catalog extraction and loading shows how to generate locales/en.jsonc, select it in the CLI configuration, retrieve a Spanish target, and load it safely. That is the next complete task; the local example above remains useful as a rendering test.
For a routed application, continue with Next.js Pages or TanStack Start. A locale switch needs the new locale and its messages together, so the interface never combines one language's text with another language's formatting.