Server rendering and hydration
Resolve one locale and catalog for a request, then preserve the rendering inputs when the browser hydrates the page.
A server-rendered page already contains the reader's messages when it reaches the browser. Hydration attaches React to that HTML. Both renders need the same locale, catalog, and values; otherwise the browser can replace a valid translation with source text or report a mismatch.
Resolve the supported locale and load its catalog before rendering. Pass that pair through the framework's data mechanism to the client. For a static export, the same rule applies to the locale-specific build output.
Build the page from one state #
This local fixture requires React 19 and renders a Spanish heading with a known catalog and a fixed timestamp. Use the React quickstart for installation:
import { renderToStaticMarkup } from "react-dom/server";
import { computeKey, createLingo, LingoProvider, useLingo } from "@lingo.dev/react";
const state = {
locale: "es",
messages: {
[computeKey("Hello, {name}.", "Greeting on the account dashboard")]:
"Hola, {name}.",
},
name: "Ana",
updatedAt: Date.parse("2026-10-10T12:00:00Z"),
};
function Page({ name, updatedAt }: { name: string; updatedAt: number }) {
const l = useLingo();
return (
<main>
<h1>{l.text("Hello, {name}.", {
context: "Greeting on the account dashboard",
values: { name },
})}</h1>
<time dateTime={new Date(updatedAt).toISOString()}>
{l.datetime(updatedAt, { timeZone: "UTC" })}
</time>
</main>
);
}
const l = createLingo(state.locale);
const html = renderToStaticMarkup(
<html lang={l.locale} dir={l.direction}>
<body>
<LingoProvider locale={state.locale} messages={state.messages}>
<Page name={state.name} updatedAt={state.updatedAt} />
</LingoProvider>
</body>
</html>,
);The heading is Hola, Ana. and the document has lang="es" and dir="ltr". The fixed instant and explicit timezone make the date inputs reproducible. This fixture produces static markup; use your framework's hydration path, rather than renderToStaticMarkup, for the interactive application.
Carry the same inputs to the client #
Supply the browser with the same state through the framework's serialization mechanism. Messages is a plain string map, so it can travel with other page data. Avoid embedding JSON by concatenating an unescaped <script> string; use the framework's safe data transport.
Keep these inputs aligned:
| Input | What a mismatch changes |
|---|---|
| Source and context | The computed catalog key. Deploy calls and catalogs from compatible revisions. |
| Locale and catalog | Grammar, translated templates, and value formatting. |
| Placeholder values | The visible name, count, or other data. |
| Timestamp and timezone | The displayed time and sometimes the calendar day. |
| Relative-time reference | The offset shown during hydration. Reuse the initial reference instead of reading the clock independently twice. |
Native Intl data can differ between server and browser even with identical inputs. Check representative values in the supported environments. After hydration, the application can refresh time-dependent displays normally.
Use the framework's loading boundary #
The Next.js Pages recipe loads messages into __lingoMessages and supplies them through withLingoApp. Its exports are Pages-only: /pages, /pages/client, and /pages/server. A root import or App Router recipe is not part of this package.
The TanStack Start recipe puts { locale, messages } into route context and renders the root provider and document attributes from that context. The catalog stays fixed for that request; its language switcher uses a full request to load another one.
In either case, inspect initial HTML and then hydrate it in the application. Confirm the translated heading remains unchanged and no mismatch diagnostic appears. A static render test checks the server result, but cannot establish successful hydration.
Check language URLs independently #
A correct heading does not establish that a language switch reaches the right page. Test the selected adapter's URL behavior with query parameters and a fragment, then confirm the next request loads the matching catalog. Use locale-router for prefix and canonicalization policy. Inspect absolute alternate-language URLs as well: Next's helper emits alternates, while TanStack's helper also emits canonical and Open Graph metadata.