# gt-node: General Translation Node.js SDK: Конфигурация
URL: https://generaltranslation.com/ru/docs/node/reference/config.mdx
---

title: Конфигурация
description: Настройте библиотеку General Translation gt-node с помощью initializeGT. Справочник API по конфигурации gt-node.

---

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

## Обзор [#overview]

Вызовите `initializeGT` один раз — до обработки запросов, передав объект конфигурации. Функция работает синхронно и ничего не возвращает.

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

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
  projectId: process.env.GT_PROJECT_ID,
});
```

Эти ключи соответствуют тем, которые [`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`, объединяющий параметры определения локали и параметры кэша переводов.

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

| Параметр                                     | Описание                                                                                                   | Тип                                                                   | Необязательно | По умолчанию      |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------- | ----------------- |
| [`defaultLocale`](#default-locale)           | Исходная и резервная локаль.                                                                               | `string`                                                              | Да            | `'en'`            |
| [`locales`](#locales)                        | Поддерживаемые целевые локали.                                                                             | `string[]`                                                            | Да            | `[defaultLocale]` |
| [`projectId`](#project-id)                   | ID проекта; при указании включает CDN-загрузчик General Translation.                                       | `string`                                                              | Да            | —                 |
| [`devApiKey`](#dev-api-key)                  | API-ключ для разработки для перевода по запросу.                                                           | `string`                                                              | Да            | —                 |
| [`apiKey`](#api-key)                         | API-ключ для production.                                                                                   | `string`                                                              | Да            | —                 |
| [`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`. Runtime его не использует.                     | `string`                                                              | Да            | —                 |

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

## `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` · **Необязательно**

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

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

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

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

## `apiKey` [#api-key]

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

API-ключ для продакшена. Укажите его, если вам нужен перевод во время выполнения в 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/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'],
  projectId: process.env.GT_PROJECT_ID,
});
```