# General Translation Platform: 构造函数
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class/constructor.mdx
Docs index: https://generaltranslation.com/llms.txt
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` 环境变量中查找它们。
* **已配置的标识。** 请使用 `en-US` 等标准代码；已配置的代码会按原样保留。若要接受其他写法 (例如 `en-us`) ，请通过 [`customMapping`](/docs/platform/core/reference/types/custom-mapping) 进行映射：`{ 'en-us': { code: 'en-US' } }`。`sourceLocale`、`targetLocale` 以及 `locales` 中的每个条目都会依据当前生效的映射 (包括自定义别名) 进行验证。代码无效时会抛出错误。
* **返回的区域设置代码。** 项目和文件的响应会尽可能沿用你配置的写法和别名。如果多个已配置的代码指向同一区域设置，则使用第一个匹配项，除非你的请求对它们作了区分。不会用其他方言代替。运行时翻译结果使用 API 自身的区域设置代码。
* **自定义映射优先级。** [`customMapping`](/docs/platform/core/reference/types/custom-mapping) 允许你定义区域设置别名、覆盖标准 BCP 47 验证规则，以及覆盖标准区域设置属性 (名称、表情符号 等) 。自定义映射的优先级高于标准 BCP 47 数据。

## 参数 [#parameters]

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

| 参数                                 | 描述                              | 类型                                                                    | 可选 | 默认值                   |
| ---------------------------------- | ------------------------------- | --------------------------------------------------------------------- | -- | --------------------- |
| [`apiKey`](#api-key)               | 翻译服务的项目 API Key。                | `string`                                                              | 是  | `GT_API_KEY` env      |
| [`devApiKey`](#dev-api-key)        | 备用项目 API Key，在未设置 `apiKey` 时使用。 | `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)             | API 基础 URL。                     | `string`                                                              | 是  | `https://api.gtx.dev` |
| [`customMapping`](#custom-mapping) | 自定义区域设置代码映射及属性覆盖。               | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | —                     |

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

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

用于翻译服务的项目 API Key。未提供时，将从 `GT_API_KEY` 读取。执行 API 操作需要提供 API Key (包括已弃用的别名 `devApiKey`) 和项目 ID，并具备该操作的相应权限。

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

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

`apiKey` 的兼容性别名 (已弃用) ，并非针对特定环境的独立密钥类型。当 `apiKey` 未设置时使用。如果未提供，则会从 `GT_DEV_API_KEY` 中读取。

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

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

唯一的项目标识符。未提供时，将从 `GT_PROJECT_ID` 中读取。执行 API 操作时，除凭据外还需要提供此 ID。

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

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

翻译的默认源区域设置，例如 `en`。其配置时的写法会原样保留，并结合任何 `customMapping` 进行验证，因此也接受自定义别名。

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

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

翻译的默认目标区域设置，例如 `es`。该值会保留其配置时的拼写形式，并连同任何 `customMapping` 一并验证，因此接受自定义别名。

### `locales` [#locales]

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

受支持的区域设置标识数组。每个代码都会原样保留，并使用当前生效的 `customMapping` 进行验证；此处同样接受自定义别名。

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

**类型** `string` · **可选** · **默认值** `https://api.gtx.dev`

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 操作需要提供 API Key 和 `projectId`。
* 已配置的区域设置拼写和别名会原样保留；返回的代码遵循上述规则。
* 所有区域设置字段都会依据当前生效的自定义映射进行验证。
* 自定义映射的优先级高于标准 BCP 47 验证和属性。
* 请使用 [`setConfig`](/docs/platform/core/reference/gt-class/set-config) 重新配置实例，而不要直接为属性赋值。

*注意：`GT` 继承自 [`GTRuntime`](/docs/platform/core/reference/runtime)，后者提供运行时翻译、格式化和区域设置功能。文件/项目管理功能仍由 `GT` 提供。*

## Sitemap

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