Renderizado en el servidor e hidratación

Determina un idioma y un catálogo para cada solicitud y conserva los datos de entrada del renderizado cuando el navegador hidrata la página.

Cuando una página renderizada en el servidor llega al navegador, ya contiene los mensajes del lector. La hidratación conecta React con ese HTML. Ambos renderizados necesitan el mismo idioma, catálogo y valores; de lo contrario, el navegador puede reemplazar una traducción válida por el texto de origen o informar una discrepancia.

Determina el idioma compatible y carga su catálogo antes de renderizar. Transfiere ambos al cliente mediante el mecanismo de datos del framework. En una exportación estática, la misma regla se aplica al resultado de la compilación de cada idioma.

Construye la página a partir de un único estado #

Este ejemplo de prueba local requiere React 19 y renderiza un encabezado en español con un catálogo conocido y una marca de tiempo fija. Sigue la guía de inicio rápido de React para la instalación:

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

El encabezado es Hola, Ana. y el documento tiene lang="es" y dir="ltr". El instante fijo y la zona horaria explícita permiten reproducir los datos de entrada de la fecha. Este ejemplo de prueba genera marcado estático; para la aplicación interactiva, usa el mecanismo de hidratación de tu framework en lugar de renderToStaticMarkup.

Transfiere los mismos datos de entrada al cliente #

Proporciona al navegador el mismo state mediante el mecanismo de serialización del framework. Messages es un mapa simple de cadenas, por lo que puede transferirse junto con otros datos de la página. Evita insertar JSON concatenando una cadena <script> sin escapar; usa el mecanismo seguro de transferencia de datos del framework.

Mantén estos datos de entrada sincronizados:

Dato de entradaQué cambia si hay una discrepancia
Origen y contextoLa clave calculada del catálogo. Despliega las llamadas y los catálogos de revisiones compatibles.
Idioma y catálogoLa gramática, las plantillas traducidas y el formato de los valores.
Valores de los marcadores de posiciónEl nombre, la cantidad u otros datos visibles.
Marca de tiempo y zona horariaLa hora que se muestra y, a veces, el día del calendario.
Referencia de tiempo relativoLa diferencia de tiempo que se muestra durante la hidratación. Reutiliza la referencia inicial en lugar de consultar el reloj dos veces de forma independiente.

Los datos nativos de Intl pueden diferir entre el servidor y el navegador, incluso con datos de entrada idénticos. Verifica valores representativos en los entornos compatibles. Después de la hidratación, la aplicación puede actualizar con normalidad los elementos que dependen del tiempo.

Usa el límite de carga del framework #

La receta para Next.js Pages carga los mensajes en __lingoMessages y los proporciona mediante withLingoApp. Sus exportaciones son exclusivas de Pages: /pages, /pages/client y /pages/server. Este paquete no incluye una importación desde la raíz ni una receta para App Router.

La receta para TanStack Start coloca { locale, messages } en el contexto de la ruta y, a partir de ese contexto, renderiza el proveedor raíz y los atributos del documento. El catálogo se mantiene fijo durante esa solicitud; su selector de idioma realiza una solicitud completa para cargar otro.

En ambos casos, inspecciona el HTML inicial y luego hidrátalo en la aplicación. Confirma que el encabezado traducido no cambie y que no aparezca ningún diagnóstico de discrepancia. Una prueba de renderizado estático verifica el resultado del servidor, pero no permite confirmar que la hidratación se haya completado correctamente.

Verifica las URL de idioma por separado #

Un encabezado correcto no garantiza que un cambio de idioma lleve a la página correcta. Prueba el comportamiento de las URL del adaptador seleccionado con parámetros de consulta y un fragmento; luego, confirma que la siguiente solicitud cargue el catálogo correspondiente. Usa locale-router para la política de prefijos y canonicalización. Inspecciona también las URL absolutas de idiomas alternativos: la función auxiliar de Next genera las alternativas, mientras que la de TanStack también genera metadatos canónicos y de Open Graph.