# General Translation React SDKs (gt-react, gt-next, gt-react-native): Конфигурация
URL: https://generaltranslation.com/ru/docs/react/nextjs/config.mdx
---

title: Конфигурация
description: Настройте General Translation в приложении Next.js с помощью конфигурационного плагина `withGTConfig` из `gt-next/config`, его параметров, а также локальных переводов и перевода из CDN. Справочник API для `withGTConfig`.

---

`withGTConfig` — это конфигурационный плагин `gt-next`. Оберните им конфигурацию Next.js в `next.config`, чтобы включить интернационализацию на этапе сборки. Он читает файл `gt.config.json`, объединяет его с переданными параметрами и переменными окружения, а затем настраивает компилятор, загрузку переводов и обработку запросов.

На этой странице описаны плагин и его параметры. Общие настройки локалей и файлов в `gt.config.json` см. в [справочнике по конфигурации `gt-react`](/docs/react/reference/config); схему `files` на стороне CLI — в [справочнике по конфигурации CLI](/docs/cli/reference/config).

## Обзор [#overview]

Импортируйте `withGTConfig` из `gt-next/config` и оберните им конфигурацию Next.js. Параметры можно передать вторым аргументом, но в большинстве проектов настройки локали вместо этого задают в `gt.config.json`.

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // ваша текущая конфигурация Next.js
};

export default withGTConfig(nextConfig, {
  defaultLocale: 'en',
  locales: ['es', 'fr', 'ja'],
});
```

`withGTConfig` необходимо использовать в `next.config` — только здесь интернационализация подключается к процессу сборки.

## Как это работает [#how-it-works]

* **Разрешение конфигурации.** По умолчанию плагин загружает `./gt.config.json` (также проверяются `./.gt/gt.config.json` и `./.locadex/gt.config.json`). Значения объединяются с таким приоритетом: **переданные вами параметры > переменные окружения > `gt.config.json` > значения по умолчанию.** Если один и тот же ключ задан и в `gt.config.json`, и в параметрах, но значения не совпадают, при сборке возникает ошибка конфликта, поэтому храните каждое значение в одном месте.
* **Маршрутизация по локалям Pages Router.** Если задан `nextConfig.i18n`, его `locales` и `defaultLocale` должны соответствовать явно указанным значениям в `gt.config.json`. При несоответствии выводится предупреждение во время сборки, но сборка не останавливается. Порядок локалей игнорируется, а при сравнении General Translation включает `defaultLocale` в свой эффективный набор локалей. Next.js передает активную локаль функциям получения данных Pages Router.
* **Учетные данные берутся из окружения.** Нельзя передавать `projectId`, `apiKey` или `devApiKey` как параметры — задайте их через переменные окружения (см. [Учетные данные](#credentials)).
* **Стандартизация локалей.** Когда сервисы General Translation включены, коды локалей приводятся к канонической форме BCP 47, а недопустимые локали выбрасывают исключение при сборке.
* **Доставка переводов.** Если найден файл [`loadTranslations`](/docs/react/reference/functions/load-translations), переводы загружаются из вашего бандла; в противном случае они запрашиваются из CDN General Translation. См. [Локальные переводы и переводы из CDN](#translations).

## Учетные данные [#credentials]

Задайте идентификатор проекта и API-ключи через переменные окружения, а не через параметры плагина:

| Переменная                                         | Описание                                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `GT_PROJECT_ID` (or `NEXT_PUBLIC_GT_PROJECT_ID`)   | Идентификатор вашего проекта в General Translation.                                              |
| `GT_API_KEY`                                       | API-ключ для production (с префиксом `gtx-api-`), используется CLI и в production-сборках.       |
| `GT_DEV_API_KEY` (or `NEXT_PUBLIC_GT_DEV_API_KEY`) | API-ключ для разработки (с префиксом `gtx-dev-`), для перевода по запросу в процессе разработки. |

<Callout type="warn">
  **Предупреждение:** Никогда не добавляйте префикс `NEXT_PUBLIC_` к API-ключу для production и не включайте ключ для разработки в production. Сборка выбрасывает исключение, если `GT_DEV_API_KEY` задан вместе с `NODE_ENV=production`.
</Callout>

## Параметры [#options]

Все параметры необязательны. Параметры локали обычно задаются в `gt.config.json`, а не здесь.

### Параметры локали [#locale-options]

| Параметр                                                         | Описание                                                                                  | Тип        | Необязательно | По умолчанию |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------- | ------------- | ------------ |
| [`defaultLocale`](#default-locale)                               | Исходная локаль, на которой написано ваше приложение.                                     | `string`   | Да            | `en`         |
| [`locales`](#locales)                                            | Целевые локали, на которые будет переводиться приложение.                                 | `string[]` | Да            | `[]`         |
| [`ignoreBrowserLocales`](#ignore-browser-locales)                | Игнорировать предпочтительные локали браузера при определении локали.                     | `boolean`  | Да            | `false`      |
| [`disableInvalidLocaleWarning`](#disable-invalid-locale-warning) | Отключить предупреждения о недопустимых локалях в запросе.                                | `boolean`  | Да            | `false`      |
| [`description`](#description)                                    | Описание вашего приложения на естественном языке, используемое как ориентир при переводе. | `string`   | Да            | —            |

### Доставка переводов [#delivery-options]

| Параметр                                          | Описание                                                                                                | Тип              | Необязательно | По умолчанию               |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------- | ------------- | -------------------------- |
| [`runtimeUrl`](#runtime-url)                      | Базовый URL API General Translation. Пустая строка отключает перевод во время выполнения.               | `string \| null` | Да            | GT runtime                 |
| [`cacheUrl`](#cache-url)                          | URL для кэшированных переводов.                                                                         | `string \| null` | Да            | GT CDN                     |
| [`cacheExpiryTime`](#cache-expiry-time)           | Через сколько миллисекунд истекает локальный кэш переводов.                                             | `number`         | Да            | `60000`                    |
| [`loadTranslationsPath`](#load-translations-path) | Путь к пользовательскому файлу [`loadTranslations`](/docs/react/reference/functions/load-translations). | `string`         | Да            | Определяется автоматически |
| [`loadDictionaryPath`](#load-dictionary-path)     | Путь к пользовательскому файлу [`loadDictionary`](/docs/react/reference/functions/load-dictionary).     | `string`         | Да            | Определяется автоматически |
| [`dictionary`](#dictionary)                       | Путь к вашему файлу словаря.                                                                            | `string`         | Да            | Определяется автоматически |
| [`config`](#config-path)                          | Путь к файлу `gt.config.json`.                                                                          | `string`         | Да            | `./gt.config.json`         |

### Рендеринг [#rendering-options]

| Параметр                             | Описание                                                             | Тип      | Необязательно | По умолчанию |
| ------------------------------------ | -------------------------------------------------------------------- | -------- | ------------- | ------------ |
| [`renderSettings`](#render-settings) | Как отображаются переводы во время выполнения, пока они загружаются. | `object` | Да            | См. ниже     |

### Производительность [#performance-options]

| Параметр                                            | Описание                                                   | Тип      | Необязательный | По умолчанию |
| --------------------------------------------------- | ---------------------------------------------------------- | -------- | -------------- | ------------ |
| [`maxConcurrentRequests`](#max-concurrent-requests) | Максимальное количество одновременных запросов на перевод. | `number` | Да             | `100`        |
| [`maxBatchSize`](#max-batch-size)                   | Максимальное количество переводов в пакете.                | `number` | Да             | `25`         |
| [`batchInterval`](#batch-interval)                  | Интервал между пакетными запросами в миллисекундах.        | `number` | Да             | `50`         |

### Сборка и интеграция [#build-options]

| Параметр                                           | Описание                                                                                          | Тип                 | Необязательно | По умолчанию |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------- | ------------- | ------------ |
| [`experimentalCompilerOptions`](#compiler-options) | Параметры плагина компилятора.                                                                    | `object`            | Да            | См. ниже     |
| [`headersAndCookies`](#headers-and-cookies)        | Пользовательские имена заголовка локали и cookie-файла.                                           | `object`            | Да            | См. ниже     |
| [`getLocalePath`](#request-function-paths)         | Путь к пользовательской функции [`getLocale`](/docs/node/reference/functions/get-locale).         | `string`            | Да            | —            |
| [`getRegionPath`](#request-function-paths)         | Путь к пользовательской функции [`getRegion`](/docs/react/nextjs/reference/functions/get-region). | `string`            | Да            | —            |
| [`pathRegex`](#path-regex)                         | Применяет i18n middleware только к путям, соответствующим шаблону.                                | `string`            | Да            | —            |
| [`eslint`](#eslint-options)                        | Создаёт конфигурацию ESLint для General Translation.                                              | `boolean`           | Да            | `true`       |
| [`eslintSeverity`](#eslint-options)                | Уровень серьёзности для сгенерированных правил ESLint.                                            | `'error' \| 'warn'` | Да            | `'warn'`     |
| [`overwriteESLintConfig`](#eslint-options)         | Перезаписывает существующий `eslint.config.mjs`.                                                  | `boolean`           | Да            | `false`      |

### `defaultLocale` [#default-locale]

**Тип** `string` · **Необязательно** · **По умолчанию** `en`

Исходная локаль вашего приложения. Используется как резервная, если перевод отсутствует.

### `locales` [#locales]

**Тип** `string[]` · **Необязательно** · **По умолчанию** `[]`

Целевые локали для перевода. Для запросов с неподдерживаемой локалью сначала используется ближайшее совпадение, а затем `defaultLocale`. Выбирайте из [поддерживаемых локалей](/docs/platform/dashboard/reference/supported-locales).

### `ignoreBrowserLocales` [#ignore-browser-locales]

**Тип** `boolean` · **Необязательно** · **По умолчанию** `false`

Если `true`, предпочтения браузера `Accept-Language` игнорируются при определении локали.

### `disableInvalidLocaleWarning` [#disable-invalid-locale-warning]

**Тип** `boolean` · **Необязательно** · **По умолчанию** `false`

Если указано `true`, предупреждения о недопустимых локалях в запросе не выводятся.

### `description` [#description]

**Тип** `string` · **Необязательно**

Описание вашего приложения на естественном языке. Оно передаётся в качестве контекста для повышения качества перевода.

### `runtimeUrl` [#runtime-url]

**Тип** `string | null` · **Необязательно** · **По умолчанию** General Translation runtime

Базовый URL API General Translation, используемый для перевода по запросу. Установите пустую строку, чтобы полностью отключить перевод во время выполнения.

### `cacheUrl` [#cache-url]

**Тип** `string | null` · **Необязательно** · **По умолчанию** General Translation CDN

URL-адрес, по которому отдаются кэшированные переводы. Укажите собственный хост кэша или задайте значение `null`, чтобы отключить удалённую загрузку.

### `cacheExpiryTime` [#cache-expiry-time]

**Тип** `number` · **Необязательно** · **По умолчанию** `60000`

Время в миллисекундах до истечения срока действия локально кэшированных переводов. Это значение по умолчанию используется для удалённой загрузки в production без ключа разработки.

### `loadTranslationsPath` [#load-translations-path]

**Тип** `string` · **Необязательно**

Путь к пользовательскому файлу [`loadTranslations`](/docs/react/reference/functions/load-translations) для [локального перевода](#translations). По умолчанию плагин автоматически определяет файл `loadTranslations.[js|ts]` в корне проекта или в `src/`.

### `loadDictionaryPath` [#load-dictionary-path]

**Тип** `string` · **Необязательно**

Путь к пользовательскому файлу [`loadDictionary`](/docs/react/reference/functions/load-dictionary). По умолчанию плагин автоматически определяет файл `loadDictionary.[js|ts]` в корне проекта или в `src/`.

### `dictionary` [#dictionary]

**Тип** `string` · **Необязательно**

Путь к файлу словаря. Файлы с именем `dictionary.[js|ts|json]` в корне проекта или в `src/` подхватываются автоматически.

### `config` [#config-path]

**Тип** `string` · **Необязательный** · **По умолчанию** `./gt.config.json`

Путь к файлу `gt.config.json`, который будет загружен.

### `renderSettings` [#render-settings]

**Тип** `{ method: 'skeleton' | 'replace' | 'default'; timeout?: number }` · **Необязательно**

Управляет тем, как отображается содержимое, пока загружается перевод во время выполнения. Это относится только к переводам, выполняемым по запросу; кэшированные переводы отображаются сразу.

* `method` — одно из значений:
  * `skeleton` — ничего не отображать (пустой фрагмент), пока идёт загрузка.
  * `replace` — пока идёт загрузка, отображать содержимое на языке по умолчанию.
  * `default` — вести себя как `replace` для локалей одного языка (например, `en-US` и `en-GB`) и как `skeleton` для разных языков.
* `timeout` — количество миллисекунд до истечения времени ожидания метода отображения, после чего выполняется возврат к исходному содержимому. По умолчанию — `8000` в development и `12000` в production.

```ts title="next.config.ts"
export default withGTConfig(nextConfig, {
  renderSettings: {
    method: 'skeleton',
    timeout: 10000,
  },
});
```

### `maxConcurrentRequests` [#max-concurrent-requests]

**Тип** `number` · **Необязательно** · **По умолчанию** `100`

Максимальное количество одновременных запросов на перевод к API General Translation.

### `maxBatchSize` [#max-batch-size]

**Тип** `number` · **Необязательно** · **По умолчанию** `25`

Максимальное число переводов в одном пакетном запросе.

### `batchInterval` [#batch-interval]

**Тип** `number` · **Необязательно** · **По умолчанию** `50`

Интервал ожидания в миллисекундах между пакетными запросами на перевод для управления частотой запросов.

### `experimentalCompilerOptions` [#compiler-options]

**Тип** `object` · **Необязательно**

Параметры плагина компилятора, который анализирует ваш исходный код на этапе сборки. Поля:

| Поле                     | Описание                                                   | Тип                                                  | По умолчанию |
| ------------------------ | ---------------------------------------------------------- | ---------------------------------------------------- | ------------ |
| `type`                   | Какой плагин компилятора использовать.                     | `'babel' \| 'swc' \| 'none'`                         | `'none'`     |
| `logLevel`               | Уровень детализации логов компилятора.                     | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'`     |
| `compileTimeHash`        | Предварительно вычислять хэши переводов на этапе сборки.   | `boolean`                                            | `true`       |
| `disableBuildChecks`     | Отключить проверки при сборке.                             | `boolean`                                            | `false`      |
| `enableAutoJsxInjection` | Автоматически оборачивать переводимый JSX на этапе сборки. | `boolean`                                            | `false`      |

Установите `@generaltranslation/compiler`, затем задайте `enableAutoJsxInjection` здесь или в `files.gt.parsingFlags` в `gt.config.json`. Предпочтительно использовать `gt.config.json`, чтобы синхронизировать извлечение CLI и преобразования компилятора; см. [Использование автоматической инъекции JSX](/docs/cli/guides/using-auto-jsx). В любом случае требуется `type: 'babel'`, чтобы `gt-next` загружал компилятор:

```ts title="next.config.ts"
export default withGTConfig(nextConfig, {
  experimentalCompilerOptions: {
    type: 'babel',
    enableAutoJsxInjection: true,
  },
});
```

Автоматическая инъекция JSX работает только в сборках webpack. Во время разработки запускайте `next dev --webpack`, а для production — `next build --webpack`. В Next.js 16 по умолчанию используется Turbopack; Turbopack отключает компилятор Babel, а `type: 'swc'` или `type: 'none'` не поддерживают инъекцию. Во всех этих случаях `gt-next` предупреждает, что инъекция была пропущена.

### `headersAndCookies` [#headers-and-cookies]

**Тип** `object` · **Необязательно**

Переопределяет имена заголовков и cookie-файлов, которые `gt-next` использует для передачи локали и связанного с запросом состояния. Поля: `localeHeaderName`, `localeCookieName`, `enableI18nCookieName`, `referrerLocaleCookieName`, `localeRoutingEnabledCookieName` и `resetLocaleCookieName`. По умолчанию для каждого поля используется стандартное имя библиотеки.

Когда настроена интернационализированная маршрутизация Next.js и `localeDetection` не равно `false`, `gt-next` использует стандартный cookie-файл предпочтений `NEXT_LOCALE`, даже если для `localeCookieName` задано другое значение. Next.js считывает этот cookie-файл только при автоматическом определении локали. Установка `nextConfig.i18n.localeDetection` в значение `false` сохраняет настроенное имя cookie-файла General Translation.

<Callout type="info">
  **Изменено в v11.1.3:** Определение локали в Pages Router теперь использует `context.locale` Next.js и согласует сохранение на стороне клиента с `NEXT_LOCALE`. Установите `localeDetection: false`, чтобы сохранить пользовательский cookie-файл локали General Translation.
</Callout>

### Пути к функциям запроса [#request-function-paths]

**Type** `string` · **Необязательно**

`getLocalePath` и `getRegionPath` указывают пути к пользовательским реализациям [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) и [`getRegion`](/docs/react/nextjs/reference/functions/get-region), позволяя переопределить способ определения локали и региона запроса.

### `pathRegex` [#path-regex]

**Тип** `string` · **Необязательно**

Строка с шаблоном регулярного выражения JavaScript. Если она задана, middleware i18n и клиентская граница маршрутизации по локали выполняются только для тех путей, которые ей соответствуют, — например, `^/(?!uk(?:/|$)).*`, чтобы пропускать всё под `/uk`. Некорректное выражение выбросит исключение на этапе сборки. Этот параметр задаётся здесь, в `withGTConfig`, а не в [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware); плагин передаёт его в middleware на этапе сборки.

<Callout type="warn">
  **Обрабатывайте алиасы локалей вручную:** Для отфильтрованных путей нормализация локали не выполняется. Если в `locales` указаны `en`, `en-GB` и `fr`, сегмент пути `uk` не распознаётся как `en-GB`. Пользовательская функция [`getLocale()`](/docs/react/nextjs/reference/functions/get-locale) должна возвращать `en-GB` для `uk`:

  ```ts title="getLocale.ts"
  import { locale } from 'next/root-params';

  export default async function getLocale() {
    const pathnameLocale = await locale();
    if (pathnameLocale === 'uk') return 'en-GB';
    return pathnameLocale;
  }
  ```

  Примените то же сопоставление перед вызовом [`registerLocale()`](/docs/react/nextjs/reference/functions/register-locale):

  ```ts
  registerLocale(locale === 'uk' ? 'en-GB' : locale);
  ```

  Если [`getLocale()`](/docs/react/nextjs/reference/functions/get-locale) или [`registerLocale()`](/docs/react/nextjs/reference/functions/register-locale) получает неизвестную локаль, `gt-next` выводит предупреждение и использует `defaultLocale`.
</Callout>

### Параметры ESLint [#eslint-options]

* `eslint` (`boolean`, default `true`) — генерировать конфигурацию ESLint для General Translation во время настройки.
* `eslintSeverity` (`'error' | 'warn'`, default `'warn'`) — уровень серьёзности сгенерированных правил.
* `overwriteESLintConfig` (`boolean`, default `false`) — разрешить перезаписывать существующий файл `eslint.config.mjs`.

Описание самих правил см. в разделе [Проверка кода линтером](/docs/react/guides/linting-your-code).

## Локальные переводы и перевод из CDN [#translations]

По умолчанию `gt-next` загружает переводы из CDN General Translation во время выполнения — переведённый контент автоматически загружается туда при запуске [`npx gt translate`](/docs/cli/reference/commands/translate). Либо вы можете включить переводы в бандл приложения и загружать их локально.

Локальные переводы загружаются быстрее и работают офлайн, но увеличивают размер бандла и требуют повторного деплоя при каждом изменении контента. Чтобы использовать их, добавьте файл [`loadTranslations`](/docs/react/reference/functions/load-translations), который возвращает переводы для локали:

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

`withGTConfig` автоматически находит файл `loadTranslations.[js|ts]` в корне проекта или в каталоге `src/` (или явно укажите [`loadTranslationsPath`](#load-translations-path)). Затем укажите для CLI тот же каталог, чтобы [`npx gt translate`](/docs/cli/reference/commands/translate) записывал туда файлы. Полное описание процесса см. в разделе [Локальное хранение переводов](/docs/react/guides/storing-translations).

<Callout type="info">
  **Изменено в v11.1.0:** webpack-сборки теперь корректно обрабатывают пользовательские файлы [`loadDictionary`](/docs/react/reference/functions/load-dictionary), [`loadTranslations`](/docs/react/reference/functions/load-translations) и `dictionary`. Обновитесь с v11.0.x, если каждый поиск в словаре webpack сообщает об отсутствующей записи, несмотря на то что файлы присутствуют; Turbopack это не затронуло.
</Callout>

## Возвращает [#returns]

`withGTConfig` возвращает объект `NextConfig`, дополненный настройками General Translation. На этапе сборки будет выброшена ошибка, если в конфигурации есть конфликты, отсутствует обязательный API-ключ, с сервисами General Translation используется недопустимая локаль или ключ разработки присутствует в Production.