# General Translation React SDKs (gt-react, gt-next, gt-react-native): Настройка TanStack Start
URL: https://generaltranslation.com/ru/docs/react/tanstack-start/setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Зарегистрируйте middleware запросов General Translation, инициализируйте приложение TanStack Start, определите локаль и гидратируйте провайдер.

`gt-tanstack-start` использует глобальное middleware запросов, инициализацию маршрутизатора на уровне модуля и загрузчик корневого маршрута. Middleware создаёт локальное для запроса состояние для серверного кода, а корневой загрузчик гидратирует [`<GTProvider>`](/docs/react/reference/components/gt-provider) локалью и переводами.

На этой странице описана настройка для TanStack Start. Полную инструкцию, включая установку и CLI, см. в [TanStack Start Quickstart](/docs/react/tanstack-start-quickstart).

<Callout type="warn">
  **Предупреждение:** `gt-tanstack-start` является экспериментальным, и в нём возможны несовместимые изменения.
</Callout>

*Примечание: `gt-tanstack-start` поддерживает только ESM. Используйте синтаксис `import` вместо CommonJS `require()`.*

*Примечание: для этой настройки требуется `gt-tanstack-start` версии 11.1.5 или новее, чтобы [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) разрешался из основной точки входа пакета в клиентских сборках.*

## Загрузка переводов [#load-translations]

Создайте функцию [`loadTranslations`](/docs/react/reference/functions/load-translations), которая импортирует файл перевода для локали. Храните файлы в `src/`, чтобы Vite мог их импортировать.

```ts title="loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./src/_gt/${locale}.json`);
  return translations.default;
}
```

CLI создаёт эти файлы при запуске [`npx gt translate`](/docs/cli/reference/commands/translate).

## Зарегистрируйте middleware запросов [#middleware]

Создайте `src/start.ts` и зарегистрируйте [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) как глобальное middleware запросов. При создании пользовательского экземпляра start сохраните middleware Cross-Site Request Forgery (CSRF) из TanStack Start.

```ts title="src/start.ts"
import { createCsrfMiddleware, createStart } from '@tanstack/react-start';
import { gtMiddleware } from 'gt-tanstack-start';

const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware, gtMiddleware],
}));
```

Middleware один раз для каждого запроса определяет локаль, регион и настройку интернационализации. Он сохраняет определённую локаль в cookie-файле локали и делает состояние запроса доступным для [изоморфных runtime-функций](/docs/react/tanstack-start/using-server-functions) на сервере.

## Инициализация и определение локали [#initialize]

[`initializeGT`](/docs/react/reference/config#initialize), [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) и [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) импортируются из `gt-tanstack-start`:

* **[`initializeGT`](/docs/react/reference/config#initialize)** — вызовите один раз на уровне модуля в `src/router.tsx`. Передайте содержимое `gt.config.json` через spread и укажите [`loadTranslations`](/docs/react/reference/functions/load-translations).
* **[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)** — возвращает локаль из активной области middleware на сервере и из инициализированного хранилища условий браузера на клиенте.
* **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)** — загружает переводы для локали в формате, который ожидает [`<GTProvider>`](/docs/react/reference/components/gt-provider), чтобы контент отображался без мерцания при загрузке. См. [справочник](/docs/react/reference/functions/get-translations-snapshot).

## Включите маршрутизацию по локалям [#locale-routing]

Маршрутизация по локалям подключается явно. Перед ее включением настройте TanStack Router так, чтобы он сопоставлял как URL локали по умолчанию без префикса, например `/about`, так и URL с префиксом локали, например `/es/about`.

Вы можете добавить [необязательный сегмент `/{-$locale}`](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#i18n-with-optional-path-parameters) в маршруты на основе файлов или кода либо использовать [опцию `rewrite`](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#url-localization-via-router-rewrite) TanStack Router, чтобы сопоставить публичные URL с префиксом локали с существующим деревом маршрутов. Например, необязательный путь маршрута `/{-$locale}/about` сопоставляется с `/about`, `/es/about` и `/ja/about`.

После того как маршрутизатор начнет принимать оба формата URL, установите `localeRouting` в `true` в `gt.config.json`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "localeRouting": true
}
```

`gt-tanstack-start` не создает и не изменяет структуру маршрутов вашего приложения. Эта опция указывает ему определять локаль по поддерживаемому префиксу пути и обновлять `pathname` при смене локали. Локаль по умолчанию остается без префикса, например `/about`, тогда как для других локалей используется префикс, например `/es/about`.

На сервере [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) определяет локаль по пути, затем по cookie-файлу локали, заголовку `Accept-Language` и `defaultLocale`. На клиенте при смене локали страница перезагружается по соответствующему `pathname` с сохранением строки запроса и хеша.

Базовый путь TanStack Router учитывается через `TSS_ROUTER_BASEPATH`.

## Инициализируйте маршрутизатор и настройте корневой маршрут [#root-route]

Добавьте импорты и инициализатор [`initializeGT`](/docs/react/reference/config#initialize) в существующий файл `src/router.tsx`:

```tsx title="src/router.tsx"
import { initializeGT } from 'gt-tanstack-start';
import gtConfig from '../gt.config.json';
import loadTranslations from '../loadTranslations';

initializeGT({ ...gtConfig, loadTranslations });
```

Затем определите локаль и загрузите снимок в корневом загрузчике `src/routes/__root.tsx`. Передайте `locale` и `translations` в [`<GTProvider>`](/docs/react/reference/components/gt-provider) через компонент-оболочку.

```tsx title="src/routes/__root.tsx"
import {
  HeadContent,
  Scripts,
  createRootRoute,
} from '@tanstack/react-router';
import {
  GTProvider,
  getLocale,
  getTranslationsSnapshot,
  LocaleSelector,
} from 'gt-tanstack-start';

export const Route = createRootRoute({
  loader: async () => {
    const locale = getLocale();
    return {
      locale,
      translations: await getTranslationsSnapshot(locale),
    };
  },
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  const { locale, translations } = Route.useLoaderData();
  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <GTProvider locale={locale} translations={translations}>
          <LocaleSelector />
          {children}
        </GTProvider>
        <Scripts />
      </body>
    </html>
  );
}
```

[`<GTProvider>`](/docs/react/reference/components/gt-provider) требует здесь и `locale`, и `translations` — в отличие от Next.js, где сервер сам их получает, или React Native, где провайдер сам их загружает.

[`initializeGT`](/docs/react/reference/config#initialize) должен выполниться до того, как [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) начнет обрабатывать запрос. Завершите настройку маршрутизатора и корневого маршрута до запуска сервера разработки.

## Пометьте контент для перевода [#content]

В компонентах маршрутов оборачивайте JSX в [`<T>`](/docs/react/reference/components/t), а строки переводите с помощью [`useGT`](/docs/react/reference/hooks/use-gt). Импортируйте их из `gt-react`, чтобы CLI распознал их при сканировании исходного кода.

```tsx title="src/routes/index.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { T, useGT } from 'gt-react';

export const Route = createFileRoute('/')({ component: Home });

function Home() {
  const gt = useGT();

  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content is translated automatically.</p>
      </T>
      <input aria-label={gt('Email input field')} />
    </main>
  );
}
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.