Vykreslování na serveru a hydratace

Pro každý požadavek určete jeden jazyk a katalog a stejné vstupy pro vykreslování zachovejte i při hydrataci stránky v prohlížeči.

Stránka vykreslená na serveru už při doručení do prohlížeče obsahuje texty v jazyce čtenáře. Hydratace k tomuto HTML připojí React. Obě vykreslení potřebují stejný jazyk, katalog a hodnoty. Jinak může prohlížeč nahradit správný překlad zdrojovým textem nebo ohlásit nesoulad.

Před vykreslením určete podporovaný jazyk a načtěte jeho katalog. Tuto dvojici předejte klientovi prostřednictvím mechanismu frameworku pro přenos dat. U statického exportu platí stejné pravidlo pro výstup sestavení v daném jazyce.

Sestavte stránku z jednoho stavu #

Tento lokální testovací příklad vyžaduje React 19 a vykreslí nadpis ve španělštině se známým katalogem a pevně daným časovým razítkem. Pokyny k instalaci najdete ve stručném úvodu do Reactu:

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>,
);

Nadpis je Hola, Ana. a dokument má lang="es" a dir="ltr". Pevně daný okamžik a výslovně určené časové pásmo zajišťují reprodukovatelnost vstupů pro datum. Tento testovací příklad vytváří statické HTML. Pro interaktivní aplikaci použijte postup hydratace svého frameworku, nikoli renderToStaticMarkup.

Předejte klientovi stejné vstupy #

Předejte prohlížeči stejné state prostřednictvím serializačního mechanismu frameworku. Messages je prostá mapa řetězců, takže ji lze přenášet spolu s ostatními daty stránky. Nevkládejte JSON zřetězením neescapovaného řetězce <script>. Použijte bezpečný mechanismus frameworku pro přenos dat.

Zajistěte shodu těchto vstupů:

VstupCo se při nesouladu změní
Zdroj a kontextVypočtený klíč katalogu. Nasazujte volání a katalogy z kompatibilních revizí.
Jazyk a katalogGramatika, přeložené šablony a formátování hodnot.
Hodnoty zástupných symbolůZobrazené jméno, počet nebo jiné údaje.
Časové razítko a časové pásmoZobrazený čas a někdy i kalendářní den.
Referenční okamžik pro relativní časČasový rozdíl zobrazený během hydratace. Použijte znovu původní referenční okamžik, místo abyste aktuální čas zjišťovali dvakrát nezávisle na sobě.

Nativní data Intl se mohou na serveru a v prohlížeči lišit i při shodných vstupech. Ověřte reprezentativní hodnoty v podporovaných prostředích. Po hydrataci může aplikace údaje závislé na čase aktualizovat běžným způsobem.

Použijte hranici pro načítání ve frameworku #

Návod pro Next.js Pages načítá texty do __lingoMessages a předává je prostřednictvím withLingoApp. Jeho exporty jsou určeny pouze pro Pages: /pages, /pages/client a /pages/server. Import z kořene balíčku ani návod pro App Router nejsou součástí tohoto balíčku.

Návod pro TanStack Start vkládá { locale, messages } do kontextu trasy a podle tohoto kontextu vykresluje kořenového poskytovatele a atributy dokumentu. Katalog zůstává po dobu daného požadavku neměnný. Přepínač jazyků načítá jiný katalog pomocí úplného požadavku.

V obou případech zkontrolujte počáteční HTML a poté ho v aplikaci hydratujte. Ověřte, že přeložený nadpis zůstává beze změny a neobjeví se žádné diagnostické hlášení o nesouladu. Test statického vykreslení ověří výsledek ze serveru, ale nemůže potvrdit úspěšnou hydrataci.

Adresy URL jazykových verzí ověřte samostatně #

Správný nadpis ještě neznamená, že přepnutí jazyka vede na správnou stránku. Otestujte, jak vybraný adaptér pracuje s adresami URL s parametry dotazu a fragmentem. Poté ověřte, že další požadavek načte odpovídající katalog. Pro pravidla předpon a kanonizace použijte locale-router. Zkontrolujte také absolutní adresy URL alternativních jazykových verzí: pomocná funkce Next.js generuje odkazy na alternativní verze, zatímco pomocná funkce TanStack navíc generuje kanonická metadata a metadata Open Graph.