# General Translation Platform: 构造函数
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class/constructor.mdx
---

title: 构造函数
description: 使用 API 密钥、项目“设置”、默认区域设置和区域设置映射初始化一个 GT 实例。Constructor 的 API 参考。

---

创建一个新的 `GT` 实例，它是 General Translation 所有翻译、格式化和区域设置功能的入口。只需调用一次，并在整个应用中复用该实例。

## 概览 [#overview]

使用可选的配置对象创建一个 `GT` 实例。你在这里设置的任何凭据和区域设置，都会成为该实例所有方法调用的默认值。

```typescript
import { GT } from 'generaltranslation';

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  sourceLocale: 'en',
  targetLocale: 'es',
});
```

签名：

```typescript
new GT(params?: GTConstructorParams): GT
```

*注意：你可以省略 `apiKey`、`devApiKey` 和 `projectId`——如果已设置 `GT_API_KEY`、`GT_DEV_API_KEY` 和 `GT_PROJECT_ID` 环境变量，构造函数会自动从中读取这些值。*

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

* **环境变量回退。** 如果未传入 `apiKey`、`devApiKey` 或 `projectId`，构造函数会从 `GT_API_KEY`、`GT_DEV_API_KEY` 和 `GT_PROJECT_ID` 环境变量中查找它们。
* **先标准化区域设置，再验证。** 每个提供的区域设置代码 (`sourceLocale`、`targetLocale` 以及 `locales` 中的每个条目) 都会先标准化为其规范的 BCP 47 形式，然后再进行验证。**存储的值是标准化/标准化形式**，而不是你传入的原始字符串。若代码无效，构造函数会抛出错误。
* **自定义映射适用于 `sourceLocale`/`targetLocale`，但不适用于 `locales`。** `sourceLocale` 和 `targetLocale` 会**结合** [`customMapping`](/docs/platform/core/reference/types/custom-mapping) 进行验证，因此可以接受自定义别名。`locales` 中的每个条目都会在**不使用**该映射的情况下进行验证，因此如果 `customMapping` 的别名出现在 `locales` 中，就会被拒绝。
* **自定义映射优先级。** [`customMapping`](/docs/platform/core/reference/types/custom-mapping) 允许你定义区域设置别名、覆盖标准 BCP 47 验证规则，以及覆盖标准区域设置属性 (名称、emoji 等) 。自定义映射的优先级高于标准 BCP 47 数据。

## 参数 [#parameters]

构造函数接受一个可选的 [`GTConstructorParams`](/docs/platform/core/reference/types/gt-constructor-params) 对象 (默认值为 `{}`) ，包含以下属性：

| 参数                                 | 描述                               | 类型                                                                    | 可选 | 默认值                  |
| ---------------------------------- | -------------------------------- | --------------------------------------------------------------------- | -- | -------------------- |
| [`apiKey`](#api-key)               | 翻译服务的生产 API 密钥。                  | `string`                                                              | 是  | `GT_API_KEY` env     |
| [`devApiKey`](#dev-api-key)        | 开发 API 密钥，在开发环境中优先使用。            | `string`                                                              | 是  | `GT_DEV_API_KEY` env |
| [`projectId`](#project-id)         | 唯一的项目标识符。                        | `string`                                                              | 是  | `GT_PROJECT_ID` env  |
| [`sourceLocale`](#source-locale)   | 翻译使用的默认源区域设置。                    | `string`                                                              | 是  | —                    |
| [`targetLocale`](#target-locale)   | 翻译使用的默认目标区域设置。                   | `string`                                                              | 是  | —                    |
| [`locales`](#locales)              | 支持的区域设置代码。                       | `string[]`                                                            | 是  | —                    |
| [`baseUrl`](#base-url)             | 用于 enterprise 部署的自定义 API 基础 URL。 | `string`                                                              | 是  | —                    |
| [`customMapping`](#custom-mapping) | 自定义区域设置代码映射和属性覆盖。                | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | —                    |

### `apiKey` [#api-key]

**类型** `string` · **可选** · **默认值** `GT_API_KEY` 环境变量

用于翻译服务的 Production API Key。未提供时，将从 `GT_API_KEY` 环境变量读取。执行任何 API 操作都需要此项。

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

**类型** `string` · **可选** · **默认值** `GT_DEV_API_KEY` 环境变量

开发 API 密钥。在开发环境中，其优先级高于 `apiKey`。如果未提供，则会从 `GT_DEV_API_KEY` 环境变量中读取。

### `projectId` [#project-id]

**类型** `string` · **可选** · **默认值** `GT_PROJECT_ID` 环境变量

项目的唯一标识符。未提供时，将从 `GT_PROJECT_ID` 环境变量中读取。任何 API 操作都需要此参数。

### `sourceLocale` [#source-locale]

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

翻译的默认源区域设置，例如 `en`。该值会被标准化为其规范形式，并以该标准化形式存储，随后再结合任何 `customMapping` 进行验证 (因此这里也接受自定义 alias) 。

### `targetLocale` [#target-locale]

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

翻译的默认目标区域设置，例如 `es`。该值会被标准化为其规范形式，并以标准化后的形式存储；随后还会连同任何 `customMapping` 一并验证 (因此此处接受自定义别名) 。

### `locales` [#locales]

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

受支持的区域设置代码数组。每个代码都会被标准化为其规范形式，并以该标准化形式存储，然后在**不使用** `customMapping` 的情况下进行验证——因此，如果某个仅作为 `sourceLocale`/`targetLocale` 的有效 `customMapping` 别名出现在 `locales` 中，就会被拒绝。

### `baseUrl` [#base-url]

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

自定义 API 基础 URL，用于指向自托管或特定区域端点的企业部署。

### `customMapping` [#custom-mapping]

**类型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **可选**

自定义区域设置代码映射及属性覆盖。可用于 (1) 为区域设置代码定义别名，(2) 覆盖标准的 BCP 47 验证规则，以及 (3) 覆盖标准的 BCP 47 区域设置属性，如名称和 emoji。

## 返回值 [#returns]

**类型** `GT`

一个新的 `GT` 实例，包含所有可用的翻译、格式化和区域设置方法。

## 示例 [#examples]

```typescript
import { GT } from 'generaltranslation';

// 最简配置 — 从环境变量读取凭据
const gt = new GT();
```

```typescript
// 使用 API 凭据
const gt = new GT({
  projectId: 'my-project-id',
  apiKey: 'my-api-key',
  targetLocale: 'fr',
});
```

```typescript
// 使用自定义区域设置别名：将 `cn` 作为 `zh` 的别名。
// General Translation API 不支持 `cn`，因此需要自定义映射（custom mapping）。
const gt = new GT({
  projectId: 'my-project-id',
  apiKey: 'my-api-key',
  targetLocale: 'es',
  customMapping: {
    cn: { code: 'zh' },
  },
});
```

```typescript
// 自定义映射还可以覆盖名称、表情符号和其他区域设置属性
const gt = new GT({
  projectId: 'my-project-id',
  apiKey: 'my-api-key',
  targetLocale: 'es',
  customMapping: { 'en-US': { name: 'Mandarin', emoji: '🇫🇷' } },
});
```

## 备注 [#notes]

* 所有参数都是可选的，但 API 操作需要 `apiKey` (或 `devApiKey`) 和 `projectId`。
* 构造函数会将每个区域设置代码标准化为其规范形式 (存储的值为标准化形式) ，然后对其进行验证；如果代码无效，则会抛出错误。
* `sourceLocale` 和 `targetLocale` 会结合 `customMapping` 进行验证；`locales` 中的每个条目则不结合它进行验证。
* 自定义映射的优先级高于标准 BCP 47 的验证和属性。

*注意：`GT` 类扩展自 `GTRuntime`。在 9.0 中，翻译、格式化和区域设置辅助方法位于 `GTRuntime` 上，而文件工作流方法 (上传、入队、下载等) 位于 `GT` 上。构造函数和 [`setConfig`](/docs/platform/core/reference/gt-class/set-config) 都定义在 `GTRuntime` 上，因此通过继承使用时不受影响。*