# General Translation React SDKs (gt-react, gt-next, gt-react-native): Конфигурация URL: https://generaltranslation.com/ru/docs/react/reference/config.mdx Docs index: https://generaltranslation.com/llms.txt Description: Настройте экосистему React с помощью общего файла gt.config.json и инициализации в рантайме. Справочник по 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 | Описание | Тип | необязательно | По умолчанию | | ------------------------------------ | -------------------------------------------------------------------------------------- | ---------- | ------------- | ------------ | | [`initializeGT`](#initialize) | Инициализация без определения локали браузера, для приложений с серверным рендерингом. | `function` | Нет | — | | [`initializeGTSPA`](#initialize-spa) | Инициализация одностраничного приложения, включая определение локали браузера. | `function` | Нет | — | Обе функции принимают следующие общие поля: | Option | Описание | Тип | необязательно | По умолчанию | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | ------------- | ----------------- | | `defaultLocale` | Исходная локаль, с которой выполняется перевод. | `string` | Да | `en` | | `locales` | Поддерживаемые целевые локали. | `string[]` | Да | `[defaultLocale]` | | [`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`](/docs/react/reference/functions/load-dictionary). | `object` | Да | — | | `projectId` | ID проекта 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` | Да | — | | [`_tagIds`](#tag-ids) | Предоставляет хэш перевода каждого [``](/docs/react/reference/components/t) в качестве DOM-атрибута `data-_gt-hash`. | `boolean` | Да | `false` | ### `initializeGT` [#initialize] **Тип** `(config) => void` · **Обязательно** Инициализирует конфигурацию и кэш переводов без определения локали браузера. Используйте это в конфигурациях с серверным рендерингом, где фреймворк предоставляет локаль запроса и переводы. ```tsx initializeGT({ ...gtConfig, loadTranslations, }); ``` ### `initializeGTSPA` [#initialize-spa] **Тип** `(config) => Promise` · **Обязательно** Инициализирует `gt-react` в одностраничном приложении. Вызовите её один раз, до первой отрисовки. Она создаёт кэш переводов, определяет активную локаль по cookie-файлам и настройкам браузера, а также предварительно загружает переводы. Доступно только в точке входа браузера. Также принимает следующие поля, доступные только в браузере: | Параметр | Описание | Тип | Необязательно | По умолчанию | | ----------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- | ------------- | ------------ | | `locale` | Явно заданная начальная локаль. При указании обнаружение пропускается. | `string` | Да | Обнаружено | | `region` | Начальный код региона для форматирования с учётом региона. | `string` | Да | — | | `enableI18n` | Переводить контент. Если `false`, рендерит исходную локаль. | `boolean` | Да | `true` | | [`htmlTagOptions`](#htmltagoptions) | Поле совместимости, которое не обновляет HTML-элемент автоматически. | `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` | Да | — | ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, locale: gtConfig.defaultLocale, }); ``` Поскольку `initializeGTSPA` определяет локаль из окружения, `initializeGTSPA` возвращает промис — дождитесь его выполнения перед рендерингом. Обновляйте атрибуты `lang` и `dir` элемента `` в приложении при изменении локали. #### `htmlTagOptions` **Тип** `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` · **Необязательный** Поле совместимости, поддерживаемое только в браузере и принимаемое `initializeGTSPA`. Его передача не приводит к автоматическому обновлению атрибутов `lang` или `dir` элемента `` при изменении локали; обновляйте эти атрибуты в приложении. ## `gt.config.json` [#config-file] `gt.config.json` находится в корне проекта и содержит настройки локалей и файлов, общие с CLI. Импортируйте его и передайте его поля при инициализации. | Ключ | Описание | Тип | Необязательно | По умолчанию | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------- | ------------- | --------------------- | | [`projectId`](#project-id) | ID проекта General Translation. | `string` | Да | — | | [`defaultLocale`](#default-locale) | Исходная локаль. | `string` | Да | `en` | | [`locales`](#locales) | Целевые локали. | `string[]` | Да | — | | [`localeRouting`](#locale-routing) | Сохранять активную локаль в пути URL. | `boolean` | Да | Зависит от фреймворка | | [`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` | Да | — | | [`_tagIds`](#tag-ids) | Представлять хэш перевода каждого [``](/docs/react/reference/components/t) как DOM-атрибут `data-_gt-hash`. | `boolean` | Да | `false` | | [`_versionId`](#version-id) | Внутренний идентификатор версии перевода. Не редактируйте. | `string` | Да | — | ### `projectId` [#project-id] **Тип** `string` · **Необязательно** Уникальный идентификатор вашего проекта в General Translation. Требуется для доставки через CDN и перевода в режиме разработки по запросу. ### `defaultLocale` [#default-locale] **Тип** `string` · **Необязательно** · **По умолчанию** `en` Исходная локаль, на которой написан ваш интерфейс. Используется как резервная локаль, если перевод отсутствует. ### `locales` [#locales] **Тип** `string[]` · **Необязательно** Целевые локали, поддерживаемые вашим проектом, в виде кодов BCP 47, например `['es', 'fr']`. ### `localeRouting` [#locale-routing] **Тип** `boolean` · **Необязательно** · **По умолчанию** зависит от фреймворка Управляет URL-адресами с префиксом локали в TanStack Start. Эта возможность включается явно и по умолчанию имеет значение `false`. Эта опция не определяет маршруты: настройте необязательные параметры пути `/{-$locale}` или перенаправление URL-адресов, чтобы TanStack Router принимал URL-адреса как без префикса, так и с префиксом локали. См. [руководство по настройке TanStack Start](/docs/react/tanstack-start/setup#locale-routing). После включения [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) отдает приоритет первому поддерживаемому сегменту пути, локаль по умолчанию остается без префикса, а при изменении локали на клиенте страница перезагружается с соответствующим путём URL. В Next.js маршрутизация настраивается отдельно через [`createNextMiddleware({ localeRouting })`](/docs/react/nextjs/reference/functions/create-next-middleware), где по умолчанию используется `true`. Эта опция не влияет на обычные React SPA или React Native. ### `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). ## `_tagIds` [#tag-ids] **Тип** `boolean` · **Необязательно** · **По умолчанию** `false` Включает добавление DOM-идентификаторов к отрисованному выводу [``](/docs/react/reference/components/t) и [``](/docs/react/nextjs/reference/components/tx) в `gt-react`, `gt-next` и `gt-tanstack-start`. Такие инструменты, как локализованное воспроизведение и контекстное QA, используют атрибут `data-_gt-hash`, чтобы сопоставить отрисованный узел с соответствующим переводом. Укажите `_tagIds` в общем файле конфигурации, затем передайте эту конфигурацию в [`initializeGT`](#initialize) или [`initializeGTSPA`](#initialize-spa). Плагин `withGTConfig` считывает тот же файл в Next.js: ```json title="gt.config.json" { "_tagIds": true } ``` Значение должно быть литералом `true`. Любое другое значение, включая истинное значение не типа boolean, оставляет тегирование отключённым. React Native принимает общее поле config, но пропускает тегирование DOM. **Включение этой возможности может добавить элементы-обёртки.** Инъекция `` сведена к необходимому минимуму: * **Один хост-элемент** (например, `…`) аннотируется на месте. Обёртка не добавляется, поэтому разметка остаётся корректной внутри ограниченных родительских элементов, таких как ``, `