# gt-node: General Translation Node.js SDK: initializeGT
URL: https://generaltranslation.com/zh/docs/node/reference/functions/initialize-gt.mdx
---

title: initializeGT
description: 在服务器启动时一次性配置 General Translation 的 gt-node 库。initializeGT 的 API 参考。

---

配置 General Translation 以在 Node.js 运行时中使用。在调用任何其他翻译函数之前，先调用一次 `initializeGT`，以设置区域设置、凭据和翻译交付。

## 概览 [#overview]

在服务器入口文件的开头调用 `initializeGT`。它会从 `GT_PROJECT_ID`、`GT_API_KEY` 和 `GT_DEV_API_KEY` 中读取后备凭据，但不会自动读取 `gt.config.json`。完整的选项列表请参阅[配置参考](/docs/node/reference/config)。

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

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

签名：

```ts
initializeGT(config: InitializeGTParams): void
```

*注意：在使用 [`withGT`](/docs/node/reference/functions/with-gt)、[`getGT`](/docs/node/reference/functions/get-gt)、[`getMessages`](/docs/node/reference/functions/get-messages) 或任何其他翻译函数之前，必须先调用 `initializeGT`。如果先调用这些函数，就会抛出错误。*

## 工作原理 [#how-it-works]

* **一次性初始化。** 在服务器初始化期间只调用一次 `initializeGT`。它会设置区域设置配置、翻译缓存，以及按请求存储区域设置的机制。
* **凭据优先级。** 显式提供且非空的 `projectId`、`apiKey` 和 `devApiKey` 的优先级更高。省略或空值则会回退到对应的环境变量。
* **交付模式。** 提供 `projectId` 以从 General Translation CDN 加载翻译，或使用 [`loadTranslations`](/docs/react/reference/functions/load-translations) 加载你自己的源内容。若要在开发环境中进行按需翻译，还需提供 `devApiKey`。
* **同步。** 该调用会立即返回，不会等待网络请求。

## 参数 [#parameters]

| 参数                  | 描述                                             | 类型                   | 可选 | 默认值 |
| ------------------- | ---------------------------------------------- | -------------------- | -- | --- |
| [`config`](#config) | 配置对象。请参阅[配置参考文档](/docs/node/reference/config)。 | `InitializeGTParams` | 否  | —   |

### `config` [#config]

**类型** `InitializeGTParams` · **必填**

一个整合了区域设置、凭据、缓存和 dictionary 选项的对象。该对象是必填的，但其中每个字段都是可选的。所有字段都记录在[配置参考](/docs/node/reference/config)中。常用字段：

* `defaultLocale` — source 区域设置和后备区域设置 (默认值为 `'en'`) 。
* `locales` — 支持的目标区域设置。
* `projectId` — 项目 ID；设置后会启用 CDN 加载器。
* `apiKey` — production API key。
* `devApiKey` — 用于按需翻译的开发 API 密钥。
* `loadTranslations` — 返回某个区域设置翻译内容的自定义加载器。
* `customMapping` — 区域设置别名和属性覆盖。

## 返回值 [#returns]

**类型** `void`

## 示例 [#examples]

```ts title="server.js"
// 基本设置
import { initializeGT } from 'gt-node';

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

```ts title="server.js"
// 使用自定义翻译加载器
import { initializeGT } from 'gt-node';

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

## 版本历史 [#version-history]

| 版本              | 变更                                                                               |
| --------------- | -------------------------------------------------------------------------------- |
| `gt-node` 1.0.8 | 新增了对 `GT_PROJECT_ID`、`GT_API_KEY` 和 `GT_DEV_API_KEY` 环境变量后备值的支持。显式提供的非空参数仍然优先生效。 |