Как перевести приложение 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.
Задайте правила выбора локали и каталог #
Установите пакеты:
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:
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:
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 используйте определённую локаль и тексты как контекст роутера:
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 сохраните оболочку фреймворка и добавьте провайдер:
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:
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, войдите в систему, привяжите движок локализации и получите первый целевой каталог:
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.
Переключайте язык с новым запросом к серверу #
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.