Renderização no servidor e hidratação

Defina um único idioma e catálogo para cada requisição e preserve os dados de renderização quando o navegador hidratar a página.

Uma página renderizada no servidor já contém as mensagens do leitor ao chegar ao navegador. A hidratação conecta o React a esse HTML. As duas renderizações precisam usar o mesmo idioma, catálogo e valores; caso contrário, o navegador pode substituir uma tradução válida pelo texto de origem ou apontar uma divergência.

Defina o idioma compatível e carregue o catálogo correspondente antes de renderizar. Envie esse par ao cliente pelo mecanismo de dados do framework. Em uma exportação estática, a mesma regra vale para o resultado da compilação de cada idioma.

Crie a página a partir de um único estado #

Este exemplo de teste local requer React 19 e renderiza um título em espanhol com um catálogo conhecido e um instante fixo. Para instalar, siga o guia de início rápido do 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>,
);

O título é Hola, Ana., e o documento tem lang="es" e dir="ltr". O instante fixo e o fuso horário explícito tornam os dados de entrada da data reproduzíveis. Este exemplo de teste gera marcação estática; na aplicação interativa, use o fluxo de hidratação do seu framework em vez de renderToStaticMarkup.

Envie os mesmos dados de entrada ao cliente #

Forneça ao navegador o mesmo state pelo mecanismo de serialização do framework. Messages é um mapa simples de strings e pode ser enviado junto com os outros dados da página. Evite incorporar JSON concatenando uma string <script> sem escape; use o mecanismo seguro de transporte de dados do framework.

Mantenha estes dados de entrada alinhados:

EntradaO que uma divergência altera
Origem e contextoA chave calculada do catálogo. Implante chamadas e catálogos de revisões compatíveis.
Idioma e catálogoGramática, modelos traduzidos e formatação de valores.
Valores dos espaços reservadosO nome, a contagem ou outros dados visíveis.
Instante e fuso horárioO horário exibido e, às vezes, o dia no calendário.
Referência de tempo relativoA diferença de tempo exibida durante a hidratação. Reutilize a referência inicial em vez de consultar o relógio duas vezes de forma independente.

Os dados nativos de Intl podem variar entre o servidor e o navegador, mesmo com dados de entrada idênticos. Verifique valores representativos nos ambientes compatíveis. Após a hidratação, a aplicação pode atualizar normalmente as exibições que dependem do tempo.

Use o limite de carregamento do framework #

A receita para Next.js Pages carrega as mensagens em __lingoMessages e as disponibiliza por meio de withLingoApp. Suas exportações são exclusivas do Pages: /pages, /pages/client e /pages/server. Este pacote não oferece uma importação pela raiz nem uma receita para App Router.

A receita para TanStack Start insere { locale, messages } no contexto da rota e usa esse contexto para renderizar o provedor raiz e os atributos do documento. O catálogo permanece fixo durante essa requisição; o seletor de idioma faz uma requisição completa para carregar outro catálogo.

Em ambos os casos, inspecione o HTML inicial e depois faça a hidratação na aplicação. Confirme que o título traduzido permanece inalterado e que nenhum diagnóstico de divergência é exibido. Um teste de renderização estática verifica o resultado do servidor, mas não comprova que a hidratação foi bem-sucedida.

Verifique as URLs de idioma separadamente #

Um título correto não garante que a troca de idioma leve à página certa. Teste o comportamento das URLs do adaptador selecionado com parâmetros de consulta e um fragmento. Em seguida, confirme que a próxima requisição carrega o catálogo correspondente. Use locale-router para definir a política de prefixos e canonicalização. Inspecione também as URLs absolutas das versões em outros idiomas: a função auxiliar do Next gera URLs alternativas, enquanto a do TanStack também gera metadados canônicos e Open Graph.