服务端渲染与水合

为请求确定一个语言区域及其消息目录,并在浏览器水合页面时保持渲染输入一致。

服务端渲染的页面到达浏览器时,已包含面向读者的消息文本。水合会将 React 连接到这份 HTML 上。两次渲染必须使用相同的语言区域、消息目录和值;否则,浏览器可能会将正确的译文替换为源文本,或报告不匹配。

渲染前,先确定受支持的语言区域并加载对应的消息目录,再通过框架的数据机制将两者传递给客户端。静态导出时,各语言区域的构建输出也应遵循同样的规则。

基于同一状态构建页面 #

这个本地测试示例需要 React 19,使用已知的消息目录和固定时间戳来渲染西班牙语标题。安装步骤请参阅 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>,
);

标题为 Hola, Ana.,文档包含 lang="es" 和 dir="ltr"。固定时间点并明确指定时区,可确保日期输入可复现。这个测试示例生成的是静态标记;交互式应用应使用框架的水合流程,而不是 renderToStaticMarkup。

将相同的输入传递给客户端 #

通过框架的序列化机制,将相同的 state 提供给浏览器。Messages 是简单的字符串映射,可以随其他页面数据一起传递。不要通过拼接未经转义的 <script> 字符串来嵌入 JSON;请使用框架的安全数据传输机制。

确保以下输入保持一致:

输入不匹配时的影响
源文本和上下文计算得到的消息目录键。部署时,调用代码和消息目录应来自相互兼容的版本。
语言区域和消息目录语法、翻译后的模板和值的格式。
占位符值显示的名称、数量或其他数据。
时间戳和时区显示的时间,有时也会影响日期。
相对时间基准水合期间显示的时间偏移量。请复用初始基准,不要在两次渲染中分别读取当前时间。

即使输入完全相同,服务端和浏览器的原生 Intl 数据也可能不同。请在受支持的环境中检查具有代表性的值。水合完成后,应用可以正常刷新与时间相关的显示内容。

使用框架的加载边界 #

Next.js Pages 实现指南将消息加载到 __lingoMessages 中,并通过 withLingoApp 提供这些消息。其导出项仅适用于 Pages:/pages、/pages/client 和 /pages/server。此包不提供根入口导入或 App Router 实现指南。

TanStack Start 实现指南将 { locale, messages } 放入路由上下文,再根据该上下文渲染根提供器和文档属性。消息目录在该请求期间保持不变;其语言切换器会发起一次完整请求,以加载另一个消息目录。

无论采用哪种方式,都应先检查初始 HTML,再在应用中进行水合。确认翻译后的标题保持不变,且未出现不匹配的诊断信息。静态渲染测试能检查服务端结果,但无法确认水合是否成功。

单独检查语言 URL #

标题正确,并不代表切换语言后就能到达正确的页面。请使用带有查询参数和片段的 URL 测试所选适配器的行为,再确认下一个请求加载了匹配的消息目录。前缀和规范化策略请使用 locale-router。还应检查其他语言版本的绝对 URL:Next 的辅助函数会输出其他语言版本链接,而 TanStack 的辅助函数还会输出规范链接和 Open Graph 元数据。