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:
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ů:
| Vstup | Co se při nesouladu změní |
|---|---|
| Zdroj a kontext | Vypočtený klíč katalogu. Nasazujte volání a katalogy z kompatibilních revizí. |
| Jazyk a katalog | Gramatika, 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ásmo | Zobrazený č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.