Provider and hooks
Supply a locale and catalog, combine shared and page messages, and change languages without mixing rendering inputs.
LingoProvider makes one locale and catalog available to a component subtree. useLingo() reads the nearest provider and returns the message and formatting methods for those inputs.
These rendering examples require React 19. Follow the React quickstart installation before using the provider.
import { LingoProvider, useLingo, type Messages } from "@lingo.dev/react";
function SaveButton() {
const l = useLingo();
return (
<button type="submit">
{l.text("Save", { context: "Submit changes to account settings" })}
</button>
);
}
export function Settings({ messages }: { messages: Messages }) {
return (
<LingoProvider locale="fr" messages={messages}>
<SaveButton />
</LingoProvider>
);
}Load the French messages before rendering Settings. The provider accepts Messages, a Record<string, string>, rather than a file path, promise, or parsed JSONC entry list. Catalog loading produces this map.
Provider inputs #
| Prop | Contract |
|---|---|
locale | Required string used for message lookup diagnostics, grammar, and formatting. |
messages | Optional hash-keyed string map; defaults to {}. |
children | Required ReactNode subtree. |
An empty catalog still gives the subtree locale-aware formatting; message calls use their source templates. The provider itself does not set document language or direction.
Call useLingo in a component below the provider. Calling it outside one throws. Returning a provider from the same component does not place that component's hook beneath it, so separate the provider wrapper from the component that reads the hook.
Combine shared and page messages #
Nested providers with the same locale string merge their maps. Child entries override matching parent keys, while the remaining parent entries stay available. A route can therefore add page messages without repeating shared navigation messages.
<LingoProvider locale="fr" messages={sharedMessages}>
<LingoProvider locale="fr" messages={pageMessages}>
<SettingsPage />
</LingoProvider>
</LingoProvider>Here sharedMessages and pageMessages are already loaded French maps. If the inner locale changes to es, it becomes independent: missing Spanish messages use source fallback rather than borrowing French text. The comparison uses the literal locale string, so keep locale spelling consistent across the application.
Switch locale and catalog together #
Store the rendering input as a pair such as { locale: "fr", messages: frenchMessages }. Load the next map, then replace the pair in one state update. Changing only the locale can leave French text displayed with Spanish number formatting.
While the next catalog loads, keep the previous pair visible or show a loading state according to the application's interaction design. In routed applications, use the matching Next Pages or TanStack recipe; their switchers load the new input differently.
Create a Lingo object without a hook #
Use createLingo(locale: string, messages?: Messages): Lingo when a function needs a string outside a React component:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });This returns Account settings and formats the ratio as 12.5% in this locale. It makes no translation request and does not subscribe to a provider. Create a new object when the locale or messages change.
Both createLingo and useLingo expose locale, direction, script, and region. Use locale metadata to apply document attributes, and preserve the same inputs during hydration.