# General Translation Integrations: Payload 插件配置
URL: https://generaltranslation.com/zh/docs/integrations/payload/reference/plugin-configuration.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 为 Payload CMS 配置 General Translation 的 gt-payload 插件。gtPlugin 的 API 参考。

将 `gtPlugin` 添加到 Payload 的 `plugins` 数组中。该插件会读取 Payload 的本地化配置，从而确定源语言区域、目标语言区域和可翻译字段。

```ts title="src/payload.config.ts"
import { buildConfig } from 'payload';
import { gtPlugin } from 'gt-payload';

export default buildConfig({
  // ... 现有配置
  localization: {
    locales: ['en', 'es', 'fr'],
    defaultLocale: 'en',
  },
  plugins: [gtPlugin()],
});
```

## 选项 [#options]

| 选项                                 | 说明                              | 类型                                                                    | 可选 | 默认值             |
| ---------------------------------- | ------------------------------- | --------------------------------------------------------------------- | -- | --------------- |
| [`projectId`](#project-id)         | General Translation 项目 ID。      | `string`                                                              | 是  | `GT_PROJECT_ID` |
| [`apiKey`](#api-key)               | General Translation 项目 API Key。 | `string`                                                              | 是  | `GT_API_KEY`    |
| [`customMapping`](#custom-mapping) | Payload 的区域设置别名和属性覆盖。           | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | —               |
| [`client`](#client)                | 用于发送翻译请求的预配置客户端。                | [`GtClient`](/docs/integrations/payload/reference/api#gtclient)       | 是  | 基于其他选项构建        |

## `projectId` [#project-id]

**类型** `string` · **可选** · **默认值** `GT_PROJECT_ID`

用于文件上传、翻译任务和下载的项目。仅当服务器端无法读取 `GT_PROJECT_ID` 时，才需要直接传入此参数。

```ts title="src/payload.config.ts"
gtPlugin({
  projectId: process.env.GT_PROJECT_ID,
});
```

## `apiKey` [#api-key]

**类型** `string` · **可选** · **默认值** `GT_API_KEY`

Payload 服务器端使用的项目 API Key。请将其存放在仅限服务器端使用的环境变量中；切勿将其打包进客户端应用包，也不要将其提交到源代码管理系统。

```ts title="src/payload.config.ts"
gtPlugin({
  apiKey: process.env.GT_API_KEY,
});
```

## `customMapping` [#custom-mapping]

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

将 Payload 的区域设置代码映射为受支持的 General Translation 代码，并可覆盖区域设置属性。请使用与 [`gt.config.json`](/docs/cli/reference/config#custom-mapping) 中 `customMapping` 密钥相同的数据结构。

```ts title="src/payload.config.ts"
gtPlugin({
  customMapping: {
    cn: {
      code: 'zh',
      name: 'Mandarin',
    },
  },
});
```

管理面板仍会显示未映射且不受支持的区域设置，但会将其禁用，使其无法被选作翻译目标。

## `client` [#client]

**类型** [`GtClient`](/docs/integrations/payload/reference/api#gtclient) · **可选** · **默认值** 根据 `projectId`、`apiKey`、Payload 默认区域设置和 `customMapping` 构造

一个 server-side 客户端，实现了插件所用的 General Translation 方法。可通过此选项传入测试替身，或传入带有自定义传输行为的现有客户端。

设置 `client` 后，插件将不再自行构造 `GT` 实例。该客户端必须实现文档所述 [`GtClient`](/docs/integrations/payload/reference/api#gtclient) 类型中的所有方法。

## 工作方式 [#how-it-works]

配置 Payload 本地化后，该插件会添加：

* 为包含可翻译本地化字段的 collections 和 globals 提供 **Translate** 控件
* 位于 `/translations` 的全站范围 **Translations** 管理视图
* `gt-translation-runs` 和 `gt-translation-locks` collections
* 一个 `gtTranslationRun` Payload job
* Payload API 路由下用于查询运行记录和覆盖率的需认证端点

如果未配置 `localization`，该插件会原样返回配置。

添加或升级插件后，请运行 `npx payload generate:importmap`。在生产环境中使用翻译功能前，请先为新增的 collections 执行数据库迁移。

管理端点要求 Payload 用户处于登录状态，并遵循该用户的文档访问规则。General Translation 凭据始终保留在服务器端。

## Sitemap

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