# General Translation React SDKs (gt-react, gt-next): Конфигурация 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`, и в параметрах, но значения не совпадают, при сборке возникает ошибка конфликта, поэтому храните каждое значение в одном месте. * **Учетные данные берутся из окружения.** Нельзя передавать `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-`), для перевода по запросу в процессе разработки. | *Предупреждение: никогда не добавляйте префикс `NEXT_PUBLIC_` к API-ключу для production и не включайте ключ для разработки в production — сборка завершится с ошибкой, если `GT_DEV_API_KEY` задан вместе с `NODE_ENV=production`.* ## Параметры [#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`. | `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`. | `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` для [локального перевода](#translations). По умолчанию плагин автоматически определяет файл `loadTranslations.[js|ts]` в корне проекта или в `src/`. ### `loadDictionaryPath` [#load-dictionary-path] **Тип** `string` · **Необязательно** Путь к пользовательскому файлу `loadDictionary`. По умолчанию плагин автоматически определяет файл `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` | ### `headersAndCookies` [#headers-and-cookies] **Тип** `object` · **Необязательно** Переопределяет имена заголовков и cookie-файлов, которые `gt-next` использует для передачи локали и связанного с запросом состояния. Поля: `localeHeaderName`, `localeCookieName`, `enableI18nCookieName`, `referrerLocaleCookieName`, `localeRoutingEnabledCookieName` и `resetLocaleCookieName`. По умолчанию для каждого поля используется стандартное имя библиотеки. ### Пути к функциям запроса [#request-function-paths] **Type** `string` · **Необязательно** `getLocalePath` и `getRegionPath` указывают пути к пользовательским реализациям `getLocale` и `getRegion`, позволяя переопределить способ определения локали и региона запроса. ### `pathRegex` [#path-regex] **Тип** `string` · **Необязательно** Строка с шаблоном регулярного выражения JavaScript. Если она задана, middleware i18n и клиентская граница маршрутизации по локали выполняются только для тех путей, которые ей соответствуют, — например, `^/(?!uk(?:/|$)).*`, чтобы пропускать всё под `/uk`. Некорректное выражение вызовет ошибку на этапе сборки. Этот параметр задаётся здесь, в `withGTConfig`, а не в [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware); плагин передаёт его в middleware на этапе сборки. **Обрабатывайте алиасы локалей вручную:** Для отфильтрованных путей нормализация локали не выполняется. Если в `locales` указаны `en`, `en-GB` и `fr`, сегмент пути `uk` не распознаётся как `en-GB`. Пользовательская функция `getLocale()` должна возвращать `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()`: ```ts registerLocale(locale === 'uk' ? 'en-GB' : locale); ``` Если `getLocale()` или `registerLocale()` получает неизвестную локаль, `gt-next` выводит предупреждение и использует `defaultLocale`. ### Параметры 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`. Либо вы можете включить переводы в бандл приложения и загружать их локально. Локальные переводы загружаются быстрее и работают офлайн, но увеличивают размер бандла и требуют повторного деплоя при каждом изменении контента. Чтобы использовать их, добавьте файл `loadTranslations`, который возвращает переводы для локали: ```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/react/guides/storing-translations). ## Возвращает [#returns] `withGTConfig` возвращает объект `NextConfig`, дополненный настройками General Translation. На этапе сборки будет выброшена ошибка, если в конфигурации есть конфликты, отсутствует обязательный API-ключ, с сервисами General Translation используется недопустимая локаль или ключ разработки присутствует в Production.