Rendu côté serveur et hydratation
Déterminez une langue et un catalogue pour chaque requête, puis conservez les mêmes paramètres de rendu lorsque le navigateur hydrate la page.
Lorsqu'une page rendue côté serveur arrive dans le navigateur, elle contient déjà les messages destinés au lecteur. L'hydratation rattache React à ce HTML. Les deux rendus doivent utiliser la même langue, le même catalogue et les mêmes valeurs ; sinon, le navigateur risque de remplacer une traduction valide par le texte source ou de signaler une incohérence.
Déterminez la langue prise en charge et chargez son catalogue avant le rendu. Transmettez ces deux éléments au client via le mécanisme de transfert de données du framework. Pour un export statique, la même règle s'applique aux fichiers générés pour la langue concernée.
Construisez la page à partir d'un état unique #
Cet exemple de test local nécessite React 19 et affiche un titre en espagnol à partir d'un catalogue connu et d'un horodatage fixe. Pour l'installation, consultez le guide de démarrage rapide de React :
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>,
);Le titre est Hola, Ana. et le document comporte lang="es" et dir="ltr". L'instant fixe et le fuseau horaire défini explicitement rendent les paramètres de date reproductibles. Cet exemple de test produit du balisage statique ; pour l'application interactive, utilisez le mécanisme d'hydratation de votre framework plutôt que renderToStaticMarkup.
Transmettez les mêmes paramètres au client #
Fournissez au navigateur le même state via le mécanisme de sérialisation du framework. Messages est une simple table de correspondance de chaînes de caractères et peut donc être transmis avec les autres données de la page. Évitez d'intégrer du JSON en concaténant une chaîne <script> non échappée ; utilisez le mécanisme sécurisé de transfert de données du framework.
Veillez à ce que ces paramètres restent cohérents :
| Paramètre | Ce qu'une incohérence modifie |
|---|---|
| Source et contexte | La clé calculée du catalogue. Déployez des appels et des catalogues issus de révisions compatibles. |
| Langue et catalogue | La grammaire, les modèles traduits et la mise en forme des valeurs. |
| Valeurs des espaces réservés | Le nom, le nombre ou les autres données visibles. |
| Horodatage et fuseau horaire | L'heure affichée et, parfois, le jour du calendrier. |
| Référence pour le temps relatif | Le décalage affiché pendant l'hydratation. Réutilisez la référence initiale plutôt que de consulter l'horloge deux fois, indépendamment. |
Les données natives de Intl peuvent différer entre le serveur et le navigateur, même avec des paramètres identiques. Vérifiez des valeurs représentatives dans les environnements pris en charge. Après l'hydratation, l'application peut actualiser normalement les affichages qui dépendent du temps.
Utilisez la limite de chargement du framework #
L'exemple d'intégration de Next.js Pages charge les messages dans __lingoMessages et les fournit via withLingoApp. Ses exports sont réservés à Pages : /pages, /pages/client et /pages/server. Ce paquet ne propose ni import depuis la racine ni exemple d'intégration pour App Router.
L'exemple d'intégration de TanStack Start place { locale, messages } dans le contexte de la route, puis s'appuie sur ce contexte pour le rendu du fournisseur racine et des attributs du document. Le catalogue reste inchangé pour cette requête ; le sélecteur de langue effectue une requête complète pour en charger un autre.
Dans les deux cas, inspectez le HTML initial, puis hydratez-le dans l'application. Vérifiez que le titre traduit reste inchangé et qu'aucun diagnostic d'incohérence n'apparaît. Un test de rendu statique vérifie le résultat côté serveur, mais ne permet pas de confirmer que l'hydratation a réussi.
Vérifiez séparément les URL des langues #
Un titre correct ne garantit pas qu'un changement de langue mène à la bonne page. Testez le comportement des URL de l'adaptateur choisi avec des paramètres de requête et un fragment, puis vérifiez que la requête suivante charge le catalogue correspondant. Utilisez locale-router pour définir les règles de préfixes et de canonicalisation. Inspectez également les URL absolues des autres versions linguistiques : l'utilitaire de Next génère les variantes linguistiques, tandis que celui de TanStack génère aussi les métadonnées canoniques et Open Graph.