Renderizado en el servidor e hidratación

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

Cuando una página renderizada en el servidor llega al navegador, ya contiene los mensajes para quien la lee. La hidratación conecta React a ese HTML. Ambos renderizados necesitan el mismo idioma, catálogo y valores; de lo contrario, el navegador puede sustituir una traducción válida por el texto de origen o señalar una discrepancia.

Determina el idioma admitido 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 para 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. Para la instalación, consulta la guía de inicio rápido de React:

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 procedimiento 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 simple mapa de cadenas, por lo que puede transferirse junto con los demás datos de la página. Evita incrustar JSON concatenando una cadena <script> sin escapar; utiliza el mecanismo seguro de transferencia de datos del framework.

Mantén estos datos de entrada sincronizados:

Dato de entradaQué cambia si hay una discrepancia
Texto de origen y contextoLa clave calculada del catálogo. Despliega llamadas y 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 variar entre el servidor y el navegador, incluso con datos de entrada idénticos. Comprueba valores representativos en los entornos admitidos. Tras 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 de 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 de TanStack Start incorpora { locale, messages } al contexto de la ruta y renderiza el proveedor raíz y los atributos del documento a partir de ese contexto. El catálogo se mantiene fijo durante esa solicitud; el selector de idioma realiza una solicitud completa para cargar otro.

En ambos casos, inspecciona el HTML inicial y después hidrátalo en la aplicación. Confirma que el encabezado traducido se mantiene sin cambios y que no aparece ningún diagnóstico de discrepancia. Una prueba de renderizado estático comprueba el resultado del servidor, pero no permite confirmar que la hidratación se haya completado correctamente.

Comprueba las URL de cada idioma por separado #

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