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:
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 entrada | O que uma discrepância altera |
|---|---|
| Origem e contexto | A chave de catálogo calculada. Publique chamadas e catálogos de revisões compatíveis. |
| Idioma e catálogo | A gramática, os modelos traduzidos e a formatação dos valores. |
| Valores dos marcadores de posição | O nome, a contagem ou outros dados visíveis. |
| Marca temporal e fuso horário | A hora apresentada e, por vezes, o dia do calendário. |
| Referência de tempo relativo | A 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.