# gt-node: General Translation Node.js SDK: 配置
URL: https://generaltranslation.com/zh/docs/node/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 initializeGT 配置 General Translation 的 gt-node 库。gt-node 配置的 API 参考。

`gt-node` 库通过在启动时调用一次 [`initializeGT`](/docs/node/reference/functions/initialize-gt) 进行配置。它不会自动读取 `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`，并在调用中展开其字段：

```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`  | 未提供 `projectId` 时使用的项目 ID。     |
| `GT_DEV_API_KEY` | 未提供 `devApiKey` 时使用的开发 API 密钥。 |
| `GT_API_KEY`     | 未提供 `apiKey` 时使用的生产 API 密钥。    |

## 选项 [#options]

| 选项                                           | 描述                                                                               | 类型                                                                    | 可选 | 默认值                      |
| -------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -- | ------------------------ |
| [`defaultLocale`](#default-locale)           | 源区域设置和后备区域设置。                                                                    | `string`                                                              | 是  | `'en'`                   |
| [`locales`](#locales)                        | 支持的目标区域设置。                                                                       | `string[]`                                                            | 是  | `[defaultLocale]`        |
| [`projectId`](#project-id)                   | 项目 ID；设置后会启用 General Translation CDN 加载器。                                        | `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` 同步的模型 provider 键。运行时不会使用它。                                    | `string`                                                              | 是  | —                        |

*注意：[`initializeGT`](/docs/node/reference/functions/initialize-gt) 还接受内部的以下划线为前缀的键 (`_versionId`、`_branchId`、`_disableDevHotReload`) ，以及一个供 CLI 编译器使用的 `files` 对象。这些不属于稳定的公共接口，因此此处省略。*

## 从环境变量获取凭据 [#environment]

当配置对象中未提供某项凭据时，[`initializeGT`](/docs/node/reference/functions/initialize-gt) 会读取对应的环境变量：

| 选项          | 环境变量             | 优先级                   |
| ----------- | ---------------- | --------------------- |
| `projectId` | `GT_PROJECT_ID`  | 先使用显式提供的非空选项，其次使用环境变量 |
| `devApiKey` | `GT_DEV_API_KEY` | 先使用显式提供的非空选项，其次使用环境变量 |
| `apiKey`    | `GT_API_KEY`     | 先使用显式提供的非空选项，其次使用环境变量 |

显式传入的空字符串会被视为未提供，并回退到环境变量中的值。其他配置字段 (包括区域设置和翻译加载器) 不会从环境变量中读取。

## `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` (如果已设置)

你的 General Translation 项目 ID，是使用 General Translation 云服务所必需的。省略时，会回退到 `GT_PROJECT_ID`。设置后 (未自定义 `loadTranslations` 时) ，它会启用 CDN 加载器，在运行时拉取翻译。

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

**Type** `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`。其他任何值 (包括未设置 `NODE_ENV`) 均视为生产环境，因此请设置 `NODE_ENV=development` 以启用热重载。

## `apiKey` [#api-key]

**类型** `string` · **可选** · **默认值** `GT_API_KEY` (如果已设置)

生产环境 API 密钥。省略时，将回退到 `GT_API_KEY`。需要在生产环境中使用运行时翻译时，请设置此项。对于大多数部署，建议改为提前通过 [`gt` CLI](/docs/cli/quickstart) 生成翻译。

## `cacheUrl` [#cache-url]

**类型** `string | null` · **可选** · **默认值** GT CDN

翻译缓存服务的 URL。将其设为自定义主机后，即可从你自己的 CDN 加载翻译；设为 `null` 则会禁用远程缓存加载。

## `runtimeUrl` [#runtime-url]

**类型** `string | null` · **可选** · **默认值** GT runtime

[`tx`](/docs/node/reference/functions/tx) 和按需开发翻译所使用的运行时翻译服务 URL。将其设为 `null` 或 `''` 可禁用运行时翻译。

## `loadTranslations` [#load-translations]

**类型** `TranslationsLoader` · **可选**

一个自定义函数，用于从你自己的来源 (而非 General Translation CDN) 加载翻译。它接收一个区域设置代码，并返回该区域设置的翻译内容：

```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` · **可选**

区域设置缓存的有效期 (以毫秒为单位) 。保留为 undefined 以使用默认 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 ms

由 [`tx`](/docs/node/reference/functions/tx) 和按需开发翻译使用的运行时翻译设置：

* `timeout?: number` — 请求超时时间，单位为毫秒 (默认 `12000`) 。
* `metadata?: object` — 会合并到每个运行时翻译请求中的元数据。仅在运行时使用的翻译提示应放在这里，包括 `modelProvider` (参见下方的 [`modelProvider`](#model-provider)) 和 `sourceLocale`。

## `batchConfig` [#batch-config]

**类型** `object` · **可选**

控制 [`tx`](/docs/node/reference/functions/tx) 和按需开发翻译如何对运行时翻译请求进行批处理。若未定义，则使用默认值。

* `maxConcurrentRequests?: number` — 并发进行中的批处理请求最大数量。
* `maxBatchSize?: number` — 每个批处理请求的最大条目数。
* `batchInterval?: number` — 批处理请求发送前的延迟时间 (以毫秒为单位) 。

## `modelProvider` [#model-provider]

**类型** `string` · **可选**

与 `gt.config.json` 中的 `modelProvider` 键对应，[`gt` CLI](/docs/cli/quickstart) 会用它来选择翻译模型。`gt-node` Runtime **不会**读取这个顶层键——接受它只是为了避免展开 `gt.config.json` 时报错。要选择运行时翻译 ([`tx`](/docs/node/reference/functions/tx)) 使用的模型，请改为在 [`runtimeTranslation`](#runtime-translation) 的 `metadata` 中设置 `modelProvider`。

## 示例 [#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.