# General Translation React SDKs (gt-react, gt-next, gt-react-native): Быстрый старт с TanStack Start
URL: https://generaltranslation.com/ru/docs/react/tanstack-start-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Добавьте General Translation в приложение TanStack Start с помощью gt-tanstack-start и переведите свой первый текст.

`gt-tanstack-start` добавляет в приложения TanStack Start автоматическую интернационализацию. Вы инициализируете General Translation в точке входа маршрутизатора, определяете локаль запроса и гидратируете [`GTProvider`](/docs/react/reference/components/gt-provider) из загрузчика маршрута.

Используйте этот Быстрый старт для приложений TanStack Start. Для обычного React SPA используйте [Быстрый старт для React](/docs/react/react-quickstart).

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

## Быстрый старт [#quickstart]

Установите пакеты, создайте файл конфигурации и загрузчик переводов, добавьте middleware для запросов, инициализируйте маршрутизатор, настройте корневой маршрут, пометьте содержимое для перевода и сгенерируйте переводы.

### 1. Установите `gt-tanstack-start`

Установите `gt-tanstack-start` и `gt-react` как зависимости, а [`gt` CLI](/docs/cli/quickstart) — как зависимость для разработки. `gt-react` нужно установить напрямую, чтобы CLI мог обнаруживать компоненты [`<T>`](/docs/react/reference/components/t) в исходном коде.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-tanstack-start gt-react && npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-tanstack-start gt-react && yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-tanstack-start gt-react && bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-tanstack-start gt-react && pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

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

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

### 2. Создайте `gt.config.json`

Создайте файл `gt.config.json` в корне проекта. В нём задаются исходный язык, целевые локали и путь, по которому сохраняются файлы перевода.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

* `defaultLocale` — язык, на котором написано ваше приложение.
* `locales` — языки, на которые нужно переводить. Выберите их из [поддерживаемых локалей](/docs/platform/dashboard/reference/supported-locales).
* `files.gt.output` — путь, куда CLI записывает файлы перевода. Храните их в `src/`, чтобы Vite мог их импортировать; файлы в `public/` не будут резолвиться.

### 3. Создайте загрузчик переводов

Создайте файл `loadTranslations.ts`, который импортирует файл перевода для локали при выполнении приложения.

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

### 4. Добавьте middleware для запросов

Создайте `src/start.ts` и зарегистрируйте [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) как глобальное middleware для запросов. При определении собственного экземпляра start сохраните CSRF-middleware из 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 задает локаль, регион и параметры интернационализации для каждого запроса, чтобы серверные функции использовали нужный язык. На следующем шаге завершите инициализацию, прежде чем запускать сервер разработки.

### 5. Инициализируйте General Translation и настройте корневой маршрут

Один раз вызовите [`initializeGT`](/docs/react/tanstack-start/setup#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 });
```

Затем определите локаль с помощью [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) и загрузите снимок переводов в загрузчике `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>
  );
}
```

[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) считывает локаль из области запроса на сервере, а на клиенте — инициализированную локаль браузера. [`GTProvider`](/docs/react/reference/components/gt-provider) требует оба параметра: `locale` и `translations`.

<Callout type="warn">
  **Предупреждение:** Эти файлы перевода (`src/_gt/[locale].json`) не появятся, пока вы их не создадите. Локаль по умолчанию по-прежнему отображается, но при выборе целевой локали в переключателе языка будет возвращаться HTTP 500, пока файлы не будут созданы. Сначала выполните [`npx gt generate`](/docs/cli/reference/commands/generate) (API key не требуется) или [`npx gt translate`](/docs/cli/reference/commands/translate) (с учетными данными), чтобы создать их.
</Callout>

### 6. Пометьте содержимое для перевода

Оберните JSX в компонент [`<T>`](/docs/react/reference/components/t), чтобы переводить его на месте. Импортируйте [`<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>
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) сразу возвращает функцию перевода, поэтому вызывайте её так: `const gt = useGT();`.

### 7. Сгенерируйте переводы

Запустите CLI, чтобы перевести проект с помощью API General Translation.

```bash
npx gt translate
```

Добавьте команду в скрипт сборки, чтобы production-сборки всегда содержали актуальные переводы:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && vite build"
  }
}
```

<Callout type="info">
  **Примечание:** для [`npx gt translate`](/docs/cli/reference/commands/translate) требуются идентификатор проекта и production API key, заданные в переменных окружения `GT_PROJECT_ID` и `GT_API_KEY`. Выполните [`npx gt auth`](/docs/cli/reference/commands/auth) или перейдите в [Dashboard](/docs/platform/dashboard/get-started), чтобы получить их.
</Callout>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

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