# General Translation React SDKs (gt-react, gt-next, gt-react-native): Разработка с переводом для SPA
URL: https://generaltranslation.com/ru/docs/react/guides/developing-spa-translations.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Как просматривать переводы General Translation во время разработки одностраничного приложения на React.

Перевод для разработки позволяет предварительно просматривать переведённый контент по мере редактирования SPA. Для него требуются GT компилятор и API-ключ проекта с разрешением на runtime-перевод.

**Предварительные требования:**

* Одностраничное приложение React, настроенное с помощью [Быстрый старт SPA](/docs/react/react-spa-quickstart)
* [API-ключ проекта](/docs/platform/dashboard/reference/api-keys#create-project-keys), начинающийся с `gtx-api-`, с включённым разрешением **runtime-перевод**

<Callout type="warn">
  **Ограничение CommonJS:** Для горячей перезагрузки при разработке требуется ESM, поскольку компилятор добавляет `await` верхнего уровня. Это не работает в приложениях, собранных как CommonJS. Переводы для production по-прежнему работают с шаблоном запуска CommonJS из [Быстрый старт SPA](/docs/react/react-spa-quickstart).
</Callout>

## Подготовка [#setup]

### 1. Установите компилятор

Установите `@generaltranslation/compiler` в качестве зависимости для разработки:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i -D @generaltranslation/compiler
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add --dev @generaltranslation/compiler
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add --dev @generaltranslation/compiler
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add --save-dev @generaltranslation/compiler
    ```
  </Tab>
</Tabs>

### 2. Добавьте плагин компилятора

Включите горячую перезагрузку при разработке в общей конфигурации для CLI и компилятора:

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json",
      "parsingFlags": {
        "devHotReload": true
      }
    }
  }
}
```

Затем добавьте плагин для своего сборщика.

<Callout type="info">
  **Bazel и Rolldown:** компилятор не предоставляет отдельных адаптеров для этих систем сборки. Вместо того чтобы полагаться на горячую перезагрузку на базе компилятора, [храните переводы локально](/docs/react/guides/storing-translations).
</Callout>

<Tabs items={['Vite', 'webpack', 'Rollup', 'Rspack', 'esbuild']}>
  <Tab value="Vite">
    ```ts title="vite.config.ts"
    import react from '@vitejs/plugin-react';
    import { vite as gtCompiler } from '@generaltranslation/compiler'; // [!code highlight]
    import { defineConfig } from 'vite';

    export default defineConfig({
      plugins: [react(), gtCompiler()], // [!code highlight]
    });
    ```

    `gtCompiler()` автоматически загружает корневой `gt.config.json`.
  </Tab>

  <Tab value="webpack">
    Установите `dotenv` как зависимость для разработки, чтобы webpack мог читать `.env` и `.env.local`, затем добавьте компилятор перед остальными плагинами. Используйте `DefinePlugin`, чтобы предоставить браузерному коду только учетные данные для разработки:

    ```js title="webpack.config.mjs"
    import { webpack as gtCompiler } from '@generaltranslation/compiler';
    import dotenv from 'dotenv';
    import webpack from 'webpack';
    import gtConfig from './gt.config.json' with { type: 'json' };

    dotenv.config({ path: '.env' });
    dotenv.config({ path: '.env.local', override: true });

    export default (_env, argv) => {
      const isProduction = (argv.mode ?? 'production') === 'production';

      return {
        // Сохраните существующие настройки webpack.
        plugins: [
          gtCompiler({ ...gtConfig }),
          new webpack.DefinePlugin({
            'process.env.GT_PROJECT_ID': JSON.stringify(
              isProduction ? '' : (process.env.GT_PROJECT_ID ?? '')
            ),
            'process.env.GT_DEV_API_KEY': JSON.stringify(
              isProduction ? '' : (process.env.GT_DEV_API_KEY ?? '')
            ),
          }),
        ],
      };
    };
    ```

    Полный пример webpack для [`gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/webpack-spa) см. в разделе о лоадерах, локальных файлах перевода и настройках сервера разработки.
  </Tab>

  <Tab value="Rollup">
    Подключите компилятор перед другими плагинами Rollup:

    ```js title="rollup.config.mjs"
    import { rollup as gtCompiler } from '@generaltranslation/compiler';

    export default {
      input: 'src/index.ts',
      plugins: [
        gtCompiler(),
        // Другие ваши плагины Rollup
      ],
    };
    ```

    Rollup не может анализировать полностью динамический импорт переводов. Укажите для каждой локали статический спецификатор импорта:

    ```ts title="src/loadTranslations.ts"
    const translationLoaders = {
      es: () => import('./_gt/es.json'),
      fr: () => import('./_gt/fr.json'),
    };

    export default async function loadTranslations(locale: string) {
      const loader =
        translationLoaders[locale as keyof typeof translationLoaders];
      return loader ? (await loader()).default : {};
    }
    ```

    Обычный Rollup не поддерживает интеграцию учетных данных для разработки, показанную для Vite и webpack. При изменении исходного содержимого заново генерируйте локальные файлы перевода. См. [полный пример Rollup для `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/rollup-spa).
  </Tab>

  <Tab value="Rspack">
    Добавьте адаптер Rspack в список плагинов:

    ```js title="rspack.config.mjs"
    import { rspack as gtCompiler } from '@generaltranslation/compiler';

    export default {
      plugins: [gtCompiler()],
    };
    ```

    Для перевода в режиме разработки также необходимо передать `GT_PROJECT_ID` и `GT_DEV_API_KEY` браузерному коду, не включая ни одно из этих значений в production-бандлы.
  </Tab>

  <Tab value="esbuild">
    Добавьте адаптер esbuild в массив `plugins`:

    ```js title="build.mjs"
    import { build } from 'esbuild';
    import { esbuild as gtCompiler } from '@generaltranslation/compiler';

    await build({
      entryPoints: ['src/index.ts'],
      bundle: true,
      format: 'esm',
      outdir: 'dist',
      plugins: [gtCompiler()],
    });
    ```

    *Примечание: адаптер esbuild не поддерживает автоматическую инъекцию JSX. Явно оборачивайте переводимый JSX или используйте другой адаптер, если требуется `enableAutoJsxInjection`.*
  </Tab>
</Tabs>

Полный пример настройки Vite см. в [примере Vite для `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/vite-spa).

### 3. Добавьте учетные данные для разработки

В разделе **проект &gt; API Keys** создайте ключ с включённым **runtime-переводом**. Ключи с полным доступом также подойдут. Чтобы минимизировать риски, рекомендуем выбрать разрешения **Custom**, где для **Runtime translation** установлено **Enabled**, а для всех остальных ресурсов — **None**.

Добавьте ID проекта и ключ проекта в `.env.local`, затем передайте их в функцию инициализации. SDK по-прежнему использует настройку `devApiKey` для включения горячей перезагрузки в разработке:

<Tabs items={['Vite', 'webpack']}>
  <Tab value="Vite">
    ```bash title=".env.local"
    VITE_GT_PROJECT_ID="your-project-id"
    VITE_GT_DEV_API_KEY="gtx-api-your-runtime-key"
    ```

    ```ts
    await initializeGTSPA({
      ...gtConfig,
      projectId: import.meta.env.VITE_GT_PROJECT_ID,
      devApiKey: import.meta.env.DEV
        ? import.meta.env.VITE_GT_DEV_API_KEY
        : undefined,
      loadTranslations,
    });
    ```
  </Tab>

  <Tab value="webpack">
    ```bash title=".env.local"
    GT_PROJECT_ID="your-project-id"
    GT_DEV_API_KEY="gtx-api-your-runtime-key"
    ```

    ```ts
    await initializeGTSPA({
      ...gtConfig,
      projectId: process.env.GT_PROJECT_ID,
      devApiKey: process.env.GT_DEV_API_KEY,
      loadTranslations,
    });
    ```

    Приведённая выше конфигурация webpack заменяет оба значения пустыми строками в production-сборках, поэтому учётные данные для разработки не попадают в production бандл.
  </Tab>
</Tabs>

<Callout type="warn">
  **Только для разработки:** API-ключи можно использовать в клиентском коде, который отдаёт ваш локальный сервер разработки. Никогда не включайте API-ключи в развёрнутые клиентские бандлы, независимо от их разрешений. Чтобы минимизировать риски, рекомендуется ограничивать локальные ключи разработки только **runtime-переводом**.
</Callout>

### 4. Начните разработку

Запустите сервер разработки и переключитесь на локаль, отличную от локали по умолчанию. Когда вы редактируете переводимый контент, компилятор фиксирует изменения, а `gt-react` запрашивает обновлённый перевод для разработки.

## Next steps

- /docs/react/guides/storing-translations
- /docs/react/guides/configuring
- /docs/react/guides/translating-jsx
- /docs/react/guides/managing-locales

## Sitemap

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