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:
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:
| Entrada | O que uma divergência altera |
|---|---|
| Origem e contexto | A chave calculada do catálogo. Implante chamadas e catálogos de revisões compatíveis. |
| Idioma e catálogo | Gramática, modelos traduzidos e formatação de valores. |
| Valores dos espaços reservados | O nome, a contagem ou outros dados visíveis. |
| Instante e fuso horário | O horário exibido e, às vezes, o dia no calendário. |
| Referência de tempo relativo | A 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.