React messages

Keep source text and context in your components, then render translated catalogs with values, grammar, and React elements.

A component's message belongs with the action it explains. “Save” on a form submits changes; “Save” on an article creates a bookmark. Keeping the source text and its meaning together gives translators that distinction and lets developers understand the component without looking up a key in another file.

@lingo.dev/react uses explicit message calls:

tsx
import { useLingo } from "@lingo.dev/react";

export function SaveButton() {
  const l = useLingo();
  return <button type="submit">{l.text("Save", { context: "Submit changes to account settings" })}</button>;
}

The source and context identify a message in a catalog, a map of keys to translated strings. A provider supplies that catalog and the active locale. The component receives the translated text, or its source text when the entry is missing or empty.

From a component to another language #

First, render a local translation. A small catalog makes the lookup visible without an account or network request.

For the application workflow, lingo extract collects recognizable calls into a source JSONC catalog and generates TypeScript declarations. The CLI sends that file for translation and retrieves the target. Your loader converts the file into the provider's string map. Catalog extraction and loading carries that process through, including how to retain active messages when translated JSONC has lost its metadata comments.

Rendering is local. The runtime does not contact a localization engine or carry an API key. Keep server translation in the API integration; deliver the resulting catalogs to the application through its normal build or request-loading process.

Write the message the reader needs #

Use a complete sentence with placeholders instead of concatenating separately translated fragments. Another language may put the name, count, or link elsewhere in the sentence.

Message needsUse
Plain text with valuesl.text.
Links, emphasis, or another React elementl.rich, with named render callbacks.
Quantity-dependent grammar or a categorical choicel.plural and l.select.
Numbers, dates, lists, or locale-aware text operationsFormatting methods, which use native Intl.

The provider and hooks reference explains nested catalogs and createLingo for code outside components. Locale metadata supplies direction, script, and region information for deliberate document and layout choices.

Connect the application around the messages #

The Next.js Pages and TanStack Start adapters connect catalogs to their respective routing systems. In another setup, load the locale and messages before rendering and preserve that pair during server rendering and hydration.

Use generated types to catch source, context, and value mistakes while editing. Use rendering tests to check the actual loaded templates. If a translation does not appear, troubleshooting follows the lookup from component to catalog.

Exports #

The root exports LingoProvider, useLingo, createLingo, and computeKey, plus the types LingoProviderProps, Lingo, Messages, LingoMessages, MessageKey, TextOptions, RichOptions, PluralForms, SelectForms, and FormatMethods. The separate @lingo.dev/react/testing entry exports withLingo and renderStatic.