Serverseitiges Rendering und Hydration

Bestimme für jede Anfrage eine Sprache und einen Katalog und behalte diese Rendering-Eingaben bei, wenn der Browser die Seite hydriert.

Eine serverseitig gerenderte Seite enthält bereits die Texte in der Sprache der lesenden Person, wenn sie im Browser ankommt. Bei der Hydration wird React mit diesem HTML verbunden. Beide Rendering-Durchläufe benötigen dieselbe Sprache, denselben Katalog und dieselben Werte. Andernfalls kann der Browser eine gültige Übersetzung durch den Quelltext ersetzen oder eine Abweichung melden.

Bestimme vor dem Rendering die unterstützte Sprache und lade den zugehörigen Katalog. Übergib beides über den Datenmechanismus des Frameworks an den Client. Bei einem statischen Export gilt dieselbe Regel für die sprachspezifische Build-Ausgabe.

Erstelle die Seite aus einem einheitlichen Zustand #

Dieses lokale Testbeispiel erfordert React 19 und rendert eine spanische Überschrift mit einem bekannten Katalog und einem festen Zeitstempel. Nutze für die Installation die React-Schnellstartanleitung:

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

Die Überschrift lautet Hola, Ana., und das Dokument hat lang="es" und dir="ltr". Der feste Zeitpunkt und die explizit angegebene Zeitzone machen die Datumseingaben reproduzierbar. Dieses Testbeispiel erzeugt statisches Markup. Nutze für die interaktive Anwendung den Hydrationsablauf deines Frameworks statt renderToStaticMarkup.

Übergib dieselben Eingaben an den Client #

Stelle dem Browser über den Serialisierungsmechanismus des Frameworks dieselben state bereit. Messages ist eine einfache Zuordnung von Zeichenketten und lässt sich zusammen mit anderen Seitendaten übertragen. Bette JSON nicht durch Verketten einer nicht maskierten <script>-Zeichenkette ein. Nutze stattdessen die sichere Datenübertragung des Frameworks.

Halte diese Eingaben konsistent:

EingabeWas sich bei einer Abweichung ändert
Quelltext und KontextDer berechnete Katalogschlüssel. Stelle Aufrufe und Kataloge aus kompatiblen Revisionen bereit.
Sprache und KatalogGrammatik, übersetzte Vorlagen und Formatierung der Werte.
PlatzhalterwerteDer angezeigte Name, die Anzahl oder andere Daten.
Zeitstempel und ZeitzoneDie angezeigte Uhrzeit und manchmal auch der Kalendertag.
Referenzzeitpunkt für relative ZeitangabenDie bei der Hydration angezeigte Zeitdifferenz. Verwende den ursprünglichen Referenzzeitpunkt erneut, statt die Uhrzeit zweimal unabhängig voneinander abzurufen.

Native Intl-Daten können sich zwischen Server und Browser auch bei identischen Eingaben unterscheiden. Teste repräsentative Werte in den unterstützten Umgebungen. Nach der Hydration kann die Anwendung zeitabhängige Anzeigen wie gewohnt aktualisieren.

Nutze die Ladegrenze des Frameworks #

Die Anleitung für Next.js Pages lädt Texte in __lingoMessages und stellt sie über withLingoApp bereit. Die zugehörigen Exporte sind ausschließlich für Pages vorgesehen: /pages, /pages/client und /pages/server. Ein Import aus dem Paketstamm oder eine Anleitung für den App Router ist nicht Bestandteil dieses Pakets.

Die Anleitung für TanStack Start legt { locale, messages } im Routenkontext ab und rendert den Provider auf Wurzelebene sowie die Dokumentattribute aus diesem Kontext. Der Katalog bleibt für diese Anfrage unverändert. Der Sprachumschalter lädt einen anderen Katalog über eine vollständige Anfrage.

Sieh dir in beiden Fällen das initiale HTML an und hydriere es anschließend in der Anwendung. Stelle sicher, dass die übersetzte Überschrift unverändert bleibt und keine Diagnosemeldung zu einer Abweichung erscheint. Ein statischer Rendering-Test kontrolliert das Serverergebnis, kann aber keine erfolgreiche Hydration nachweisen.

Teste Sprach-URLs separat #

Eine korrekte Überschrift belegt nicht, dass ein Sprachwechsel zur richtigen Seite führt. Teste das URL-Verhalten des ausgewählten Adapters mit Abfrageparametern und einem Fragment. Stelle anschließend sicher, dass die nächste Anfrage den passenden Katalog lädt. Nutze locale-router für die Regeln zu Präfixen und Kanonisierung. Sieh dir auch die absoluten URLs für alternative Sprachen an: Die Hilfsfunktion von Next gibt Sprachalternativen aus, während die Hilfsfunktion von TanStack zusätzlich kanonische Metadaten und Open-Graph-Metadaten ausgibt.