Как перевести приложение TanStack Start

Обрабатывайте запросы с префиксом локали, загружайте нужный каталог и показывайте переведённые страницы с каноническими URL и переключателем языка.

Сохраните маршруты приложения, например /about, независимыми от языка, а посетители будут открывать /en/about или /de/about. @lingo.dev/react-tanstack связывает эти правила построения URL с контекстом запроса и каталогами. Маршрут по-прежнему соответствует /about, а локаль запроса определяет тексты и URL, которые для него создаются.

В этом руководстве мы добавим английский и немецкий языки в существующее приложение TanStack Start с React 19, TanStack Router 1.170+ и Start 1.168+. Start объявлен как необязательная peer-зависимость, но корневой модуль пакета импортирует createIsomorphicFn из Start. Установите Start вместе с адаптером, даже если приложение на обычном Router явно передаёт URL.

Задайте правила выбора локали и каталог #

Установите пакеты:

sh
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-tanstack@1.17.1 @lingo.dev/locale-router@0.2.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latest

Добавьте функцию loadMatchedMessages из раздела Загрузка каталогов как src/catalog.ts. Затем создайте src/i18n.ts:

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";
import type { Catalog } from "@lingo.dev/react-tanstack";
import source from "../locales/en.jsonc?raw";
import { loadMatchedMessages } from "./catalog";

export const locales = createLocaleRouter(["en", "de"] as const, {
  defaultLocale: "en",
  exclude: ["api", "assets"],
});

const targets = import.meta.glob<string>("../locales/*.jsonc", {
  query: "?raw",
  import: "default",
});

export const catalog: Catalog = async (locale) => {
  const load = targets[`../locales/${locale}.jsonc`];
  if (!load) throw new Error(`Missing catalog for ${locale}`);
  return loadMatchedMessages(source, await load());
};

Этот загрузчик Vite проверяет файлы в исходном виде и выбирает активные ключи из соответствующего английского оригинала. Так переведённые файлы без комментариев не активируют заново ключи, которых больше нет в исходнике. Если файл отсутствует или имеет неверный формат, загрузчик выдаёт ошибку, а не молча возвращает пустой объект. Описанный ниже этап извлечения создаёт импортируемый исходный файл до запуска приложения.

Определите локаль запроса до создания роутера #

Зарегистрируйте middleware для путей без префикса в src/start.ts, сохранив все существующие middleware:

ts
import { createStart } from "@tanstack/react-start";
import { localeMiddleware } from "@lingo.dev/react-tanstack/server";
import { locales } from "./i18n";

export const startInstance = createStart(() => ({
  requestMiddleware: [localeMiddleware(locales)],
}));

В src/router.tsx используйте определённую локаль и тексты как контекст роутера:

tsx
import { createRouter } from "@tanstack/react-router";
import { lingoContext, localeRewrite } from "@lingo.dev/react-tanstack";
import { routeTree } from "./routeTree.gen";
import { catalog, locales } from "./i18n";

export async function getRouter() {
  const state = await lingoContext(locales, catalog);
  return createRouter({
    routeTree,
    context: state,
    rewrite: localeRewrite(locales, state.locale),
  });
}

declare module "@tanstack/react-router" {
  interface Register {
    router: Awaited<ReturnType<typeof getRouter>>;
  }
}

Сохраните остальные настройки роутера приложения. lingoContext берёт локаль из распознанного префикса URL или использует локаль по умолчанию. На сервере функция читает URL запроса, а в браузере — location.href. Необязательный третий аргумент URL позволяет задать этот адрес явно. Сама функция не выбирает язык по Accept-Language. Для подходящих запросов к путям без префикса это делает middleware, возвращая перенаправление с кодом 302.

localeRewrite убирает распознанный префикс при сопоставлении маршрутов и добавляет локаль запроса к подходящим исходящим путям. Оставьте определения маршрутов без префиксов и исключите пути API и статических ресурсов из локализации, как показано выше.

Отобразите корневой компонент на основе контекста запроса #

В src/routes/__root.tsx сохраните оболочку фреймворка и добавьте провайдер:

tsx
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";

type LocaleContext = { locale: "en" | "de"; messages: Messages };

export const Route = createRootRouteWithContext<LocaleContext>()({
  component: Outlet,
  shellComponent: ({ children }) => {
    const { locale, messages } = Route.useRouteContext();
    return (
      <html lang={locale} dir={createLingo(locale).direction}>
        <head>
          <HeadContent />
        </head>
        <body>
          <LingoProvider locale={locale} messages={messages}>
            {children}
          </LingoProvider>
          <Scripts />
        </body>
      </html>
    );
  },
});

Теперь один и тот же контекст определяет тексты, форматирование и атрибуты документа. Сохраняйте его при гидратации: если на клиенте заменить тексты пустым объектом, отображаемая страница изменится.

Добавьте переведённую страницу и метаданные head #

Создайте src/routes/about.tsx:

tsx
import { createFileRoute } from "@tanstack/react-router";
import { useLingo } from "@lingo.dev/react";
import { getLingo, lingoHead } from "@lingo.dev/react-tanstack";
import { locales } from "../i18n";

export const Route = createFileRoute("/about")({
  head: (options) => {
    const l = getLingo(options);
    const localized = lingoHead({
      router: locales,
      locale: options.match.context.locale,
      pathname: options.match.pathname,
      origin: "https://example.com",
    });
    return {
      meta: [{ title: l.text("About us", { context: "About page title" }) }, ...localized.meta],
      links: localized.links,
    };
  },
  component: About,
});

function About() {
  const l = useLingo();
  return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}

Замените базовый адрес из примера на доверенный базовый адрес вашего сайта. Привяжите const l = getLingo(options) перед извлекаемыми вызовами в head. Цепочка вызовов getLingo(options).text(...) при извлечении не поддерживается.

Метаданные head #

lingoHead возвращает { meta, links }: канонические и альтернативные ссылки для каждой локали, а также x-default и og:url/og:locale. Передайте путь без префикса, строки запроса и фрагмента. Для немецкого /about канонический URL — https://example.com/de/about, а альтернативный URL для английского, языка по умолчанию при этих правилах, — /en/about.

Вспомогательная функция убирает один завершающий слеш у всех путей, кроме корневого. Локаль Open Graph определяется по языку и региону после дополнения недостающих компонентов, например de_DE. Необязательные переопределения ogLocale позволяют учесть особенности написания на разных платформах. LingoHead — это тип результата, а не JSX-компонент адаптера Next.

Извлеките тексты и получите каталоги #

Выполните npx lingo extract --src src --source-locale en. Для новой конфигурации инициализируйте locales/en.jsonc с целевыми локалями de, войдите в систему, привяжите движок локализации и получите первый целевой каталог:

sh
npx lingo init --source en --targets de --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Если конфигурация уже существует, сохраните её привязки и расширенные настройки. После извлечения выполните обычное обновление существующих целевых каталогов, получите и проверьте их. Затем добавьте de и заполните недостающие переводы, не меняя ревизию исходного текста. Для этого сценария следуйте разделу Загрузка каталогов и инструкции по добавлению языка. Запускайте приложение только после появления locales/en.jsonc и нужного locales/de.jsonc. Откройте /en/about и /de/about, проверьте заголовок страницы и заголовок вкладки, а также их канонические и альтернативные URL.

Переключайте язык с новым запросом к серверу #

tsx
import { useLocaleSwitch } from "@lingo.dev/react-tanstack";
import { locales } from "./i18n";

export function Languages() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <a key={option.locale} href={option.href} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </a>
      ))}
    </nav>
  );
}

Поместите этот компонент внутрь src и отображайте его в приложении с маршрутизацией. Каждый вариант содержит locale, самоназвание языка label, href и current. Обычные ссылки отправляют новый запрос и загружают каталог выбранной локали. Ссылки с маршрутизацией только на клиенте могут сохранить тексты предыдущего запроса. Переключатель сохраняет строку запроса и фрагмент и исключает x-default из списка доступных языков.

Встроенные функции для каталогов и сервера #

createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) предоставляет кешируемый Catalog для файлов, метаданные которых можно использовать напрямую. Его модули должны разрешаться в объекты со строковыми экспортами default. Он отфильтровывает ключи, которых больше нет в исходнике, кеширует по одному промису на локаль и возвращает {}, если модуль отсутствует или возникает ошибка загрузки либо разбора. Если задан sourceLocale, в рабочей среде он пропускает файл этой локали и использует исходные тексты. Он не проверяет, что структура плоская, а все значения — строки, не фильтрует данные по маршруту и не восстанавливает утраченные метаданные. Для переведённого JSONC эти задачи решает описанный выше загрузчик, который сопоставляет данные с исходным файлом.

Серверная точка входа экспортирует localeMiddleware и canonicalSearch. Middleware сохраняет параметры запроса, но заново сериализует их по правилам TanStack по умолчанию. Серверные запросы не содержат фрагмент URL из браузера. Пути с уже добавленным префиксом, исключённые пути и пути, для которых предусмотрена отдельная каноническая нормализация, передаются в next(). Точные правила работы с префиксами и канонизации описаны в locale-router.

Приложение на обычном TanStack Router может передать URL в lingoContext и реализовать собственные перенаправления, сохранив зависимость корневого пакета от Start. Middleware и оболочка запроса в этом руководстве предназначены именно для Start.