Renderização no servidor e hidratação

Determine o idioma e o catálogo de cada pedido e mantenha os mesmos dados de entrada da renderização quando o navegador hidratar a página.

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

Determine o idioma suportado e carregue o respetivo catálogo antes de renderizar a página. Transmita esse par ao cliente através do mecanismo de dados da framework. Numa exportação estática, a mesma regra aplica-se ao resultado da compilação específico de cada idioma.

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

Este exemplo de teste local requer o React 19 e renderiza um título em espanhol com um catálogo conhecido e uma marca temporal fixa. Siga o guia de início rápido do React para efetuar a instalação:

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 reproduzíveis os dados de entrada da data. Este exemplo de teste produz marcação estática; para a aplicação interativa, utilize o processo de hidratação da sua framework em vez de renderToStaticMarkup.

Transmita os mesmos dados de entrada ao cliente #

Forneça ao navegador o mesmo state através do mecanismo de serialização da framework. Messages é um mapa simples de cadeias de caracteres, pelo que pode ser transmitido juntamente com os restantes dados da página. Evite incorporar JSON concatenando uma cadeia <script> sem os devidos caracteres de escape; utilize o mecanismo seguro de transporte de dados da framework.

Mantenha estes dados de entrada consistentes:

Dados de entradaO que uma discrepância altera
Origem e contextoA chave de catálogo calculada. Publique chamadas e catálogos de revisões compatíveis.
Idioma e catálogoA gramática, os modelos traduzidos e a formatação dos valores.
Valores dos marcadores de posiçãoO nome, a contagem ou outros dados visíveis.
Marca temporal e fuso horárioA hora apresentada e, por vezes, o dia do calendário.
Referência de tempo relativoA diferença temporal apresentada 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 diferir entre o servidor e o navegador, mesmo com dados de entrada idênticos. Verifique valores representativos nos ambientes suportados. Após a hidratação, a aplicação pode atualizar normalmente os elementos apresentados que dependem do tempo.

Utilize o limite de carregamento da framework #

O exemplo de implementação com Next.js Pages carrega as mensagens em __lingoMessages e disponibiliza-as através de withLingoApp. As suas exportações são exclusivas do Pages: /pages, /pages/client e /pages/server. Este pacote não disponibiliza uma importação a partir da raiz nem um exemplo de implementação com o App Router.

O exemplo de implementação com TanStack Start coloca { locale, messages } no contexto da rota e renderiza o fornecedor de raiz e os atributos do documento a partir desse contexto. O catálogo mantém-se fixo durante esse pedido; o seletor de idioma faz um pedido completo para carregar outro catálogo.

Em ambos os casos, inspecione o HTML inicial e, em seguida, hidrate-o na aplicação. Confirme que o título traduzido permanece inalterado e que não surge qualquer diagnóstico de discrepância. Um teste de renderização estática verifica o resultado do servidor, mas não permite confirmar que a hidratação foi bem-sucedida.

Verifique os URLs dos idiomas em separado #

Um título correto não garante que a mudança de idioma conduza à página certa. Teste o comportamento dos URLs do adaptador selecionado com parâmetros de consulta e um fragmento e, em seguida, confirme que o pedido seguinte carrega o catálogo correspondente. Utilize locale-router para definir a política de prefixos e de canonicalização. Inspecione também os URLs absolutos das versões noutros idiomas: a função auxiliar do Next gera as alternativas, enquanto a função auxiliar do TanStack também gera metadados canónicos e Open Graph.