# gt-node: General Translation Node.js SDK: Конфигурация
URL: https://generaltranslation.com/ru/docs/node/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Настройте библиотеку General Translation gt-node с помощью initializeGT. Справочник API по конфигурации gt-node.

Библиотека `gt-node` настраивается одним вызовом [`initializeGT`](/docs/node/reference/functions/initialize-gt) при запуске. `gt-node` не считывает `gt.config.json` автоматически, но использует переменные окружения как резервный источник учётных данных. На этой странице описаны ключи, которые принимает этот вызов.

## Обзор [#overview]

Вызовите [`initializeGT`](/docs/node/reference/functions/initialize-gt) один раз — до обработки запросов, передав объект конфигурации. Функция работает синхронно и ничего не возвращает.

```ts
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
});
```

Эти ключи соответствуют тем, которые [`gt` CLI](/docs/cli/quickstart) считывает из `gt.config.json`. Чтобы они оставались синхронизированными, импортируйте свой `gt.config.json` и передайте его поля в вызов через spread-оператор:

```ts
import { initializeGT } from 'gt-node';
import gtConfig from './gt.config.json' with { type: 'json' };

initializeGT(gtConfig);
```

Тип конфигурации — `InitializeGTParams`, объединяющий параметры определения локали и параметры кэширования переводов.

## Переменные окружения [#env]

Явные значения, переданные в [`initializeGT`](/docs/node/reference/functions/initialize-gt), имеют приоритет над переменными окружения.

| Переменная       | Описание                                                           |
| ---------------- | ------------------------------------------------------------------ |
| `GT_PROJECT_ID`  | ID проекта, используемый, если `projectId` не указан.              |
| `GT_DEV_API_KEY` | API-ключ для разработки, используемый, если `devApiKey` не указан. |
| `GT_API_KEY`     | API-ключ для продакшена, используемый, если `apiKey` не указан.    |

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

| Параметр                                     | Описание                                                                                                   | Тип                                                                   | Необязательно | По умолчанию                |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------- | --------------------------- |
| [`defaultLocale`](#default-locale)           | Исходная и резервная локаль.                                                                               | `string`                                                              | Да            | `'en'`                      |
| [`locales`](#locales)                        | Поддерживаемые целевые локали.                                                                             | `string[]`                                                            | Да            | `[defaultLocale]`           |
| [`projectId`](#project-id)                   | ID проекта; при указании включает CDN-загрузчик General Translation.                                       | `string`                                                              | Да            | `GT_PROJECT_ID` если задан  |
| [`devApiKey`](#dev-api-key)                  | API-ключ для разработки для перевода по запросу.                                                           | `string`                                                              | Да            | `GT_DEV_API_KEY` если задан |
| [`apiKey`](#api-key)                         | API-ключ для продакшена.                                                                                   | `string`                                                              | Да            | `GT_API_KEY` если задан     |
| [`cacheUrl`](#cache-url)                     | Хост кэша переводов. `null` отключает удалённую загрузку.                                                  | `string \| null`                                                      | Да            | GT CDN                      |
| [`runtimeUrl`](#runtime-url)                 | Хост для перевода во время выполнения. `null` отключает его.                                               | `string \| null`                                                      | Да            | GT runtime                  |
| [`loadTranslations`](#load-translations)     | Пользовательский загрузчик, возвращающий переводы для локали.                                              | `TranslationsLoader`                                                  | Да            | —                           |
| [`customMapping`](#custom-mapping)           | алиасы локалей и переопределения свойств.                                                                  | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Да            | —                           |
| [`cacheExpiryTime`](#cache-expiry)           | Время жизни кэша локали в миллисекундах. `null` отключает срок действия.                                   | `number \| null`                                                      | Да            | —                           |
| [`dictionary`](#dictionary)                  | Словарь исходного языка, считываемый [`getTranslations`](/docs/node/reference/functions/get-translations). | `Dictionary`                                                          | Да            | —                           |
| [`loadDictionary`](#load-dictionary)         | Загрузчик, возвращающий словарь для локали.                                                                | `DictionaryLoader`                                                    | Да            | —                           |
| [`runtimeTranslation`](#runtime-translation) | `timeout` и `metadata` для перевода во время выполнения.                                                   | `object`                                                              | Да            | `timeout` 12000             |
| [`batchConfig`](#batch-config)               | Лимиты пакетной обработки перевода во время выполнения.                                                    | `object`                                                              | Да            | —                           |
| [`modelProvider`](#model-provider)           | Ключ провайдера модели, унаследованный из `gt.config.json`. Среда выполнения его не использует.            | `string`                                                              | Да            | —                           |

*Примечание: [`initializeGT`](/docs/node/reference/functions/initialize-gt) также принимает внутренние ключи с префиксом подчёркивания (`_versionId`, `_branchId`, `_disableDevHotReload`) и объект `files`, используемый CLI-компилятором. Они не входят в стабильный публичный интерфейс и поэтому здесь опущены.*

## Учетные данные из окружения [#environment]

Если какой-либо параметр учетных данных не указан в объекте конфигурации, [`initializeGT`](/docs/node/reference/functions/initialize-gt) считывает соответствующую переменную окружения:

| Параметр    | Переменная окружения | Приоритет                                                    |
| ----------- | -------------------- | ------------------------------------------------------------ |
| `projectId` | `GT_PROJECT_ID`      | Явно указанное непустое значение, затем переменная окружения |
| `devApiKey` | `GT_DEV_API_KEY`     | Явно указанное непустое значение, затем переменная окружения |
| `apiKey`    | `GT_API_KEY`         | Явно указанное непустое значение, затем переменная окружения |

Пустая явно указанная строка считается отсутствующей, и тогда используется значение из переменной окружения. Другие поля конфигурации, включая locales и загрузчики переводов, из окружения не считываются.

## `defaultLocale` [#default-locale]

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

Локаль по умолчанию для вашего приложения. Это локаль, на которой написан исходный контент, а также резервная локаль, используемая, если перевод не найден. Если параметр не указан, используется локаль библиотеки по умолчанию — `'en'`.

```ts
initializeGT({ defaultLocale: 'en-US' });
```

## `locales` [#locales]

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

Массив [кодов локалей](/docs/platform/core/reference/utility-functions/locales/is-valid-locale), которые поддерживает приложение. `defaultLocale` всегда входит в набор поддерживаемых локалей, даже если здесь его не указывать.

```ts
initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr', 'ja'] });
```

## `projectId` [#project-id]

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

ID вашего проекта в General Translation, необходимый для облачных сервисов General Translation. Если не указан, используется `GT_PROJECT_ID`. Если он указан без пользовательского `loadTranslations`, включается CDN-загрузчик, который получает переводы во время выполнения.

## `devApiKey` [#dev-api-key]

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

API-ключ для разработки. Если он не указан, используется `GT_DEV_API_KEY`. Вместе с `projectId` он включает перевод по запросу во время выполнения и горячую перезагрузку в режиме разработки, поэтому [`getGT`](/docs/node/reference/functions/get-gt), [`getMessages`](/docs/node/reference/functions/get-messages) и [`tx`](/docs/node/reference/functions/tx) могут переводить новый контент по мере разработки. Горячая перезагрузка работает только в среде разработки, то есть когда `NODE_ENV` точно равен `'development'`, или `import.meta.env.MODE` равен `'development'`, или `import.meta.env.DEV` равен `true`. Любое другое значение считается production, включая незаданный `NODE_ENV`, поэтому для горячей перезагрузки установите `NODE_ENV=development`.

## `apiKey` [#api-key]

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

API-ключ для продакшена. Если не указан, используется `GT_API_KEY`. Укажите его, если вам нужен перевод во время выполнения в production. Для большинства развёртываний вместо этого переводы заранее генерируются с помощью [`gt` CLI](/docs/cli/quickstart).

## `cacheUrl` [#cache-url]

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

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

## `runtimeUrl` [#runtime-url]

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

URL сервиса перевода во время выполнения, который используется функцией [`tx`](/docs/node/reference/functions/tx) и для перевода в режиме разработки по запросу. Установите значение `null` или `''`, чтобы отключить перевод во время выполнения.

## `loadTranslations` [#load-translations]

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

Пользовательская функция, которая загружает переводы из вашего собственного источника, а не из CDN General Translation. Она принимает код локали и возвращает переводы для этой локали:

```ts
type TranslationsLoader = (locale: string) => Promise<unknown>;
```

```ts
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  loadTranslations: async (locale) => {
    const res = await fetch(`https://my-api.com/translations/${locale}`);
    return res.json();
  },
});
```

## `customMapping` [#custom-mapping]

**Тип** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Необязательно**

Сопоставление пользовательских кодов локалей со стандартными кодами локалей или переопределениями [свойств локали](/docs/node/reference/functions/get-locale-properties). Используйте его, чтобы задать алиас для кода (например, `cn` вместо `zh`) или переопределить свойства отображения.

## `cacheExpiryTime` [#cache-expiry]

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

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

## `dictionary` [#dictionary]

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

Словарь на исходном языке с единицами перевода, где в качестве ключей используются id. Записи определяются для каждого запроса с помощью [`getTranslations`](/docs/node/reference/functions/get-translations).

## `loadDictionary` [#load-dictionary]

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

Загрузчик, который возвращает словарь для указанной локали:

```ts
type DictionaryLoader = (locale: string) => Promise<Dictionary>;
```

## `runtimeTranslation` [#runtime-translation]

**Тип** `object` · **Необязательно** · **По умолчанию** `timeout` 12000 мс

Настройки перевода во время выполнения, применяемые [`tx`](/docs/node/reference/functions/tx) и on-demand-переводом в режиме разработки:

* `timeout?: number` — тайм-аут запроса в миллисекундах (по умолчанию `12000`).
* `metadata?: object` — метаданные, добавляемые к каждому запросу на перевод во время выполнения. Сюда же относятся подсказки для перевода, используемые только во время выполнения, включая `modelProvider` (см. [`modelProvider`](#model-provider) ниже) и `sourceLocale`.

## `batchConfig` [#batch-config]

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

Управляет тем, как [`tx`](/docs/node/reference/functions/tx) и on-demand development translation группируют запросы на перевод во время выполнения в пакеты. Оставьте значение неопределённым, чтобы использовать настройки по умолчанию.

* `maxConcurrentRequests?: number` — максимальное количество одновременно выполняемых пакетных запросов.
* `maxBatchSize?: number` — максимальное количество элементов в одном пакетном запросе.
* `batchInterval?: number` — задержка в миллисекундах перед отправкой пакета.

## `modelProvider` [#model-provider]

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

Соответствует ключу `modelProvider` в `gt.config.json`, который [`gt` CLI](/docs/cli/quickstart) использует для выбора модели перевода. Среда выполнения `gt-node` **не** использует этот ключ верхнего уровня — он допускается только для того, чтобы spread `gt.config.json` не вызывал ошибку. Чтобы выбрать модель для перевода во время выполнения ([`tx`](/docs/node/reference/functions/tx)), задайте `modelProvider` внутри `metadata` в [`runtimeTranslation`](#runtime-translation).

## Пример [#example]

```ts title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  // Учетные данные считываются из GT_PROJECT_ID, GT_API_KEY и GT_DEV_API_KEY.
});
```

## Sitemap

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