# General Translation React SDKs (gt-react, gt-next): Конфигурация URL: https://generaltranslation.com/ru/docs/react/reference/config.mdx --- title: Конфигурация description: Настройте General Translation во всей экосистеме React с помощью общего файла gt.config.json и инициализации в рантайме. Справочник API для gt.config.json. --- General Translation настраивается в двух местах: в файле `gt.config.json`, где хранятся настройки локали и файлов, общие с [CLI](/docs/cli/reference/config), и на этапе инициализации в рантайме, где эта конфигурация загружается до первого рендера. Файл `gt.config.json` одинаков для всей экосистемы React; инициализация в рантайме различается в зависимости от фреймворка. *Справочник по `gt.config.json` на этой странице общий для `gt-react`, `gt-next`, `gt-tanstack-start` и `gt-react-native`. Функции инициализации ([`initializeGT`](#initialize), [`initializeGTSPA`](#initialize-spa)) предназначены для `gt-react`; `gt-tanstack-start` и `gt-react-native` также используют `initializeGT`.* *Примечание: `gt-next` не использует эти функции инициализации — он считывает конфигурацию через плагин `withGTConfig`, описанный в разделе Next.js.* ## Обзор [#overview] Приложение `gt-react` с серверным рендерингом настраивается в три шага: инициализируйте библиотеку, загрузите переводы для активной локали и оберните дерево в [``](/docs/react/reference/components/gt-provider). * **Инициализируйте** с помощью [`initializeGT`](#initialize) для конфигураций с серверным рендерингом. Одностраничные приложения используют [`initializeGTSPA`](#initialize-spa), которая также определяет активную локаль по cookie-файлам и данным браузера. * **Загрузите переводы** для активной локали с помощью [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot). * **Передайте** локаль и переводы вашим компонентам с помощью [``](/docs/react/reference/components/gt-provider). ```tsx title="src/routes/root.tsx" import { initializeGT, getTranslationsSnapshot, parseLocale } from 'gt-react'; import gtConfig from '../../gt.config.json'; const loadTranslations = (locale: string) => import(`../_gt/${locale}.json`).then((m) => m.default); initializeGT({ ...gtConfig, loadTranslations }); export async function loadRoot(request: Request) { const locale = parseLocale(request); return { locale, translations: await getTranslationsSnapshot(locale), }; } ``` Файл `gt.config.json` содержит общие настройки локали и файлов. И вызов инициализации, и CLI используют одни и те же значения, поэтому храните их в одном месте. ## Инициализация [#initialization] | Function | Description | Type | Optional | Default | | ------------------------------------ | -------------------------------------------------------------------------------------- | ---------- | -------- | ------- | | [`initializeGT`](#initialize) | Инициализация без определения локали браузера, для приложений с серверным рендерингом. | `function` | Нет | — | | [`initializeGTSPA`](#initialize-spa) | Инициализация одностраничного приложения, включая определение локали браузера. | `function` | Нет | — | Обе функции принимают перечисленные ниже поля. У них одинаковые параметры, но только `initializeGTSPA` выполняет определение локали браузера. | Option | Description | Type | Optional | Default | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | -------- | -------------------------- | | `defaultLocale` | Исходная локаль, с которой выполняется перевод. | `string` | Да | `en` | | `locales` | Поддерживаемые целевые локали. | `string[]` | Да | `[defaultLocale]` | | `locale` | Явно заданная начальная локаль. Если указана, определение локали пропускается. | `string` | Да | Определяется автоматически | | [`loadTranslations`](/docs/react/reference/functions/load-translations) | Функция загрузки, возвращающая переводы для локали. Документация: [`loadTranslations`](/docs/react/reference/functions/load-translations). | `(locale: string) => Promise` | Да | GT CDN | | [`loadDictionary`](/docs/react/reference/functions/load-dictionary) | Функция загрузки, возвращающая словарь для локали. Документация: [`loadDictionary`](/docs/react/reference/functions/load-dictionary). | `(locale: string) => Promise` | Да | — | | `dictionary` | Встроенный словарь как альтернатива `loadDictionary`. | `object` | Да | — | | `projectId` | идентификатор проекта General Translation для CDN и перевода в режиме разработки. | `string` | Да | — | | `devApiKey` | API-ключ для разработки для перевода по запросу и горячей перезагрузки. | `string` | Да | — | | `apiKey` | API-ключ для production. В браузере предпочтительнее использовать `devApiKey`. | `string` | Да | — | | `cacheUrl` | Пользовательский хост для переводов. `null` отключает удалённую загрузку. | `string \| null` | Да | GT CDN | | `runtimeUrl` | Хост для рантайм-перевода, используется для перевода в режиме разработки. | `string \| null` | Да | GT runtime | | `customMapping` | Алиасы локалей и переопределения свойств. | `object` | Да | — | | `region` | Начальный код региона для форматирования с учётом региона. | `string` | Да | — | | `enableI18n` | Переводить контент. Если `false`, отображается исходная локаль. | `boolean` | Да | `true` | | `htmlTagOptions` | Нужно ли синхронизировать атрибуты `lang` и `dir` тега `` при смене локали. | `object` | Да | — | ### `initializeGT` [#initialize] **Тип** `(config) => void` · **Обязательно** Инициализирует конфигурацию и кэш переводов без определения локали браузера. Используйте это в конфигурациях с серверным рендерингом, где фреймворк предоставляет локаль запроса и переводы. ```tsx initializeGT({ ...gtConfig, loadTranslations, }); ``` ### `initializeGTSPA` [#initialize-spa] **Тип** `(config) => Promise` · **Обязательно** Инициализирует `gt-react` в одностраничном приложении. Вызовите её один раз, до первой отрисовки. Она создаёт кэш переводов, определяет активную локаль по cookie-файлам и настройкам браузера, а также предварительно загружает переводы. Доступно только в точке входа браузера. ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, locale: gtConfig.defaultLocale, }); ``` Поскольку `initializeGTSPA` определяет локаль из окружения, `initializeGTSPA` возвращает промис — дождитесь его выполнения перед рендерингом. Используйте `htmlTagOptions`, чтобы указать, должны ли атрибуты `lang` и `dir` элемента `` обновляться при изменении локали: ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // по умолчанию: true updateHtmlDirTag: true, // по умолчанию: true }, }); ``` ## `gt.config.json` [#config-file] `gt.config.json` находится в корне проекта и содержит настройки локалей и файлов, общие с CLI. Импортируйте его и передайте его поля при инициализации. | Ключ | Описание | Тип | Необязательно | По умолчанию | | ------------------------------------------ | ------------------------------------------------------------ | ---------- | ------------- | ------------ | | [`projectId`](#project-id) | Идентификатор проекта General Translation. | `string` | Да | — | | [`defaultLocale`](#default-locale) | Исходная локаль. | `string` | Да | `en` | | [`locales`](#locales) | Целевые локали. | `string[]` | Да | — | | [`customMapping`](#custom-mapping) | Алиасы локалей и переопределения свойств. | `object` | Да | — | | [`cacheUrl`](#cache-url) | Базовый URL для кэшированных переводов. | `string` | Да | GT CDN | | [`runtimeUrl`](#runtime-url) | Базовый URL для переводов рантайм (development). | `string` | Да | GT runtime | | [`stageTranslations`](#stage-translations) | Проверка обязательна перед отправкой переводов в Production. | `boolean` | Да | `false` | | [`files`](#files) | Пути к локальным файлам перевода и флаги парсинга. | `object` | Да | — | | [`_versionId`](#version-id) | Внутренний идентификатор версии перевода. Не редактируйте. | `string` | Да | — | ### `projectId` [#project-id] **Тип** `string` · **Необязательно** Уникальный идентификатор вашего проекта в General Translation. Требуется для доставки через CDN и перевода в режиме разработки по запросу. ### `defaultLocale` [#default-locale] **Тип** `string` · **Необязательно** · **По умолчанию** `en` Исходная локаль, на которой написан ваш интерфейс. Используется как резервная локаль, если перевод отсутствует. ### `locales` [#locales] **Тип** `string[]` · **Необязательно** Целевые локали, поддерживаемые вашим проектом, в виде кодов BCP 47, например `['es', 'fr']`. ### `customMapping` [#custom-mapping] **Тип** `object` · **Необязательно** Алиасы локалей и переопределения свойств для переименования или настройки того, как локали сопоставляются и отображаются. ### `cacheUrl` [#cache-url] **Тип** `string` · **Необязательный** · **По умолчанию** GT CDN Базовый URL-адрес для получения кэшированных переводов. Укажите URL-адрес своего хоста или передайте `null` в вызове инициализации, чтобы отключить удалённую загрузку. ### `runtimeUrl` [#runtime-url] **Тип** `string` · **Необязательно** · **По умолчанию** GT runtime Базовый URL сервиса рантайм-перевода. Используется только для переводов в режиме разработки. ### `stageTranslations` [#stage-translations] **Тип** `boolean` · **Необязательно** · **По умолчанию** `false` Если задано `true`, инструмент `gt` помечает переводы как требующие проверки. Их нужно утвердить, прежде чем их можно будет развернуть в production с помощью [`gt translate`](/docs/cli/reference/commands/translate). ### `files` [#files] **Тип** `object` · **Необязательно** Определяет, куда записываются переводы, хранящиеся локально, как альтернативу хранению в облаке. `files.gt.output` — это шаблон пути, содержащий `[locale]`, а `files.gt.parsingFlags` управляет тем, как компилятор разбирает ваш исходный код. ```json title="gt.config.json" { "files": { "gt": { "output": "src/_gt/[locale].json", "parsingFlags": { "enableAutoJsxInjection": true, "autoderive": true } } } } ``` * `enableAutoJsxInjection` (`boolean`, default `false`) — автоматически оборачивает переводимый текст JSX в компонент перевода на этапе сборки. См. [автоматическая инъекция JSX](/docs/cli/guides/using-auto-jsx). * `autoderive` (`boolean`, default `false`) — автоматически рассматривает интерполируемые значения в вызовах [`t()`](/docs/react/reference/functions/t-function), `gt()` и [`msg()`](/docs/react/reference/functions/msg) как вызовы [`derive()`](/docs/react/reference/functions/derive). См. [autoderive](/docs/cli/guides/using-autoderive). Полное описание схемы `files` см. в [справочнике по конфигурации CLI](/docs/cli/reference/config). ### `_versionId` [#version-id] **Тип** `string` · **Необязательно** Внутренний идентификатор, который CLI использует для отслеживания версии перевода; это позволяет откатываться к предыдущим переводам. Он создаётся автоматически — не редактируйте его. Ключи с префиксом подчёркивания являются внутренними. ## Примеры [#examples] ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "gt": { "output": "src/_gt/[locale].json" } } } ``` ```tsx title="src/routes/root.tsx" import { GTProvider, initializeGT, getTranslationsSnapshot, parseLocale, } from 'gt-react'; import gtConfig from '../../gt.config.json'; const loadTranslations = (locale: string) => import(`../_gt/${locale}.json`).then((m) => m.default); initializeGT({ ...gtConfig, loadTranslations }); export async function loadRoot(request: Request) { const locale = parseLocale(request); return { locale, translations: await getTranslationsSnapshot(locale), }; } export function Root({ locale, translations, children }) { return ( {children} ); } ```