Серверный рендеринг и гидратация

Определите локаль и каталог для запроса и используйте те же данные рендеринга при гидратации страницы в браузере.

Страница после серверного рендеринга попадает в браузер уже с сообщениями на языке читателя. Гидратация подключает 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 — обычный словарь строк, который можно передавать вместе с остальными данными страницы. Не встраивайте JSON, присоединяя строку <script> без экранирования. Используйте безопасный механизм передачи данных фреймворка.

Следите, чтобы эти исходные данные совпадали:

Исходные данныеЧто меняется при несовпадении
Исходный текст и контекстВычисленный ключ каталога. Развёртывайте вызовы и каталоги из совместимых версий.
Локаль и каталогГрамматика, переведённые шаблоны и форматирование значений.
Значения подстановокОтображаемое имя, количество или другие данные.
Метка времени и часовой поясОтображаемое время, а иногда и календарная дата.
Точка отсчёта относительного времениСмещение, отображаемое при гидратации. Используйте исходную точку отсчёта повторно, а не считывайте текущее время дважды независимо друг от друга.

Встроенные данные 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.