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:

tsx
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:

InputWhat a mismatch changes
Source and contextThe computed catalog key. Deploy calls and catalogs from compatible revisions.
Locale and catalogGrammar, translated templates, and value formatting.
Placeholder valuesThe visible name, count, or other data.
Timestamp and timezoneThe displayed time and sometimes the calendar day.
Relative-time referenceThe 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.