サーバーレンダリングとハイドレーション

リクエストごとにロケールとカタログを一つずつ確定し、ブラウザーでページをハイドレーションする際も、同じ入力でレンダリングします。

サーバーでレンダリングされたページには、ブラウザーに届いた時点で、すでに読者向けのメッセージが含まれています。ハイドレーションは、そのHTMLにReactを接続する処理です。サーバーとブラウザーの両方で、同じロケール、カタログ、値を使ってレンダリングする必要があります。一致していないと、ブラウザーが正しい翻訳を原文に置き換えたり、不一致を報告したりすることがあります。

レンダリング前に、サポート対象のロケールを確定し、対応するカタログを読み込みます。この組み合わせを、フレームワークのデータ受け渡しの仕組みを通じてクライアントに渡します。静的エクスポートでも、ロケールごとのビルド出力に同じルールが適用されます。

一つの状態からページを構築する #

このローカル検証用の構成には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のヘルパーは、それに加えて正規URLとOpen Graphメタデータも出力します。