# General Translation Integrations: 编程式 API
URL: https://generaltranslation.com/zh/docs/integrations/payload/reference/api.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在服务器端代码中调用 gt-payload，并查看其导出的结果类型和管理面板组件。gt-payload 导出内容的 API 参考。

根 package 导出服务端翻译函数及其类型。`gt-payload/client` 和 `gt-payload/rsc` 子路径则导出了 [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) 在 Payload 管理面板中注册的各个组件。

## 导出 [#exports]

| 导出                                                                         | 入口                  | 说明                            |
| -------------------------------------------------------------------------- | ------------------- | ----------------------------- |
| [`translateDocument`](#translate-document)                                 | `gt-payload`        | 翻译单个集合文档或全局对象。                |
| [`translateSite`](#translate-site)                                         | `gt-payload`        | 翻译所有受支持的文档和全局对象。              |
| [`saveTranslations`](#save-translations)                                   | `gt-payload`        | 保存单个目标在当前区域设置下的值。             |
| [`saveSiteTranslations`](#save-site-translations)                          | `gt-payload`        | 保存整个站点在当前区域设置下的值。             |
| [`gtPlugin`](#plugin)                                                      | `gt-payload`        | 将管理工作流添加到 Payload 配置中。        |
| [`GtDocumentControls`](#admin-components)                                  | `gt-payload/client` | document-level 翻译控制项。         |
| [`GtNavLink`](#admin-components)                                           | `gt-payload/client` | 指向全站范围“译文”视图的链接。              |
| [`GtRunsProvider`](#admin-components)                                      | `gt-payload/client` | 恢复未完成的翻译运行。                   |
| [`GtTranslationsClient`](#admin-components)                                | `gt-payload/client` | “译文”视图的客户端内容。                 |
| [`GtTranslationsView`](#admin-components)                                  | `gt-payload/rsc`    | 注册在 `/translations` 的服务器端视图。  |
| [`GtPluginOptions`](#gtpluginoptions)                                      | `gt-payload`        | `gtPlugin` 接受的选项。             |
| [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload`        | 单文档操作的输入。                     |
| [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput)     | `gt-payload`        | 全站范围操作的输入。                    |
| [`TranslateTarget`](#translatetarget)                                      | `gt-payload`        | 集合文档或全局对象的标识。                 |
| [`TranslateResult`](#translateresult-and-localeresult)                     | `gt-payload`        | 单个目标的翻译结果。                    |
| [`LocaleResult`](#translateresult-and-localeresult)                        | `gt-payload`        | 单个目标区域设置的结果。                  |
| [`SkippedReason`](#skippedstring-and-skippedreason)                        | `gt-payload`        | 字符串未写入的原因。                    |
| [`SkippedString`](#skippedstring-and-skippedreason)                        | `gt-payload`        | 已跳过的键及原因。                     |
| [`SiteResult`](#siteresult-and-documentresult)                             | `gt-payload`        | 全站范围的翻译结果。                    |
| [`DocumentResult`](#siteresult-and-documentresult)                         | `gt-payload`        | 目标及其对应的结果。                    |
| [`SaveTranslationsResult`](#savetranslationsresult)                        | `gt-payload`        | 保存本地编辑的结果。                    |
| [`GtClient`](#gtclient)                                                    | `gt-payload`        | 插件所需的 General Translation 方法。 |

## `translateDocument` [#translate-document]

**输入** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **返回值** `Promise<TranslateResult>`

上传单个集合文档或全局对象，等待其相关任务完成 (最长一小时) ，并将已完成的翻译写入 Payload。

```ts
import { GT } from 'generaltranslation';
import { translateDocument } from 'gt-payload';

const result = await translateDocument({
  payload,
  gt: new GT({
    projectId: process.env.GT_PROJECT_ID,
    apiKey: process.env.GT_API_KEY,
    sourceLocale: payload.config.localization
      ? payload.config.localization.defaultLocale
      : undefined,
  }),
  target: { collection: 'pages', id: pageId },
  locales: ['es', 'fr'],
});
```

对于预期内的文档、权限、job 和翻译错误，结果会报告失败，而不会抛出异常。如果发生意外的操作失败，对 Payload 或客户端的调用仍可能 reject。

## `translateSite` [#translate-site]

**输入** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **返回值** `Promise<SiteResult>`

列出所有包含可翻译本地化字段的集合文档和全局对象，然后作为一个批次统一翻译。若某文档既没有已翻译的区域设置，也没有错误，则不会出现在 `documents` 中。

```ts
import { translateSite } from 'gt-payload';

const result = await translateSite({
  payload,
  gt,
  locales: ['es', 'fr'],
  user,
});
```

## `saveTranslations` [#save-translations]

**输入** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **返回值** `Promise<SaveTranslationsResult>`

将单个目标当前的 Payload 区域设置值发送到 General Translation，但不会将新的翻译任务加入队列。如果 General Translation 中尚无该源文档，此函数会先将其上传。

```ts
import { saveTranslations } from 'gt-payload';

const result = await saveTranslations({
  payload,
  gt,
  target: { global: 'site-settings' },
  locales: ['es', 'fr'],
  user,
});
```

## `saveSiteTranslations` [#save-site-translations]

**输入** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **返回值** `Promise<{ documents: DocumentResult<SaveTranslationsResult>[] }>`

对 [`translateSite`](#translate-site) 所涵盖的每个目标调用保存本地编辑 工作流。

```ts
import { saveSiteTranslations } from 'gt-payload';

const result = await saveSiteTranslations({
  payload,
  gt,
  locales: ['es', 'fr'],
  user,
});
```

## `gtPlugin` [#plugin]

**类型** `(options?: GtPluginOptions) => Plugin`

返回一个 Payload 插件。有关所有选项及副作用的说明，请参阅 [Payload 插件配置](/docs/integrations/payload/reference/plugin-configuration)。

## 输入类型 [#input-types]

### `GtPluginOptions`

```ts
type GtPluginOptions = {
  projectId?: string;
  apiKey?: string;
  customMapping?: CustomMapping;
  client?: GtClient;
};
```

### `TranslateDocumentInput` 和 `TranslateSiteInput`

```ts
type TranslateDocumentInput = {
  payload: Payload;
  gt: GtClient;
  target: TranslateTarget;
  locales: string[];
  saveLocalEdits?: boolean;
  user?: TypedUser | null;
};

type TranslateSiteInput = Omit<TranslateDocumentInput, 'target'>;
```

| 属性               | 说明                                   | 类型                                    | 可选 | 默认值                      |
| ---------------- | ------------------------------------ | ------------------------------------- | -- | ------------------------ |
| `payload`        | 已初始化的 Payload 实例。                    | `Payload`                             | 否  | —                        |
| `gt`             | 用于上传、任务、下载以及较短重试的客户端。                | [`GtClient`](#gtclient)               | 否  | —                        |
| `target`         | 集合文档或全局对象。仅用于文档操作。                   | [`TranslateTarget`](#translatetarget) | 否  | —                        |
| `locales`        | 要处理的 Payload 区域设置代码。源语言区域和重复项会被自动移除。 | `string[]`                            | 否  | —                        |
| `saveLocalEdits` | 翻译前先保存已知的区域设置编辑，并保留无法发送的编辑。          | `boolean`                             | 是  | `false`                  |
| `user`           | Payload 用户，读取和写入时将应用该用户的访问规则。        | `TypedUser \| null`                   | 是  | Payload Local API 服务器端行为 |

### `TranslateTarget`

```ts
type TranslateTarget =
  | { collection: string; id: string | number }
  | { global: string };
```

集合 ID 仅在所属集合内唯一，因此由这两个值共同构成 General Translation 文件的标识。全局对象 (global) 则使用其 slug 作为标识。

## 结果类型 [#result-types]

### `TranslateResult` 和 `LocaleResult`

```ts
type TranslateResult = {
  error?: string;
  usageLimitReached?: true;
  locales: Record<string, LocaleResult>;
};

type LocaleResult =
  | {
      status: 'applied';
      applied: string[];
      skipped: SkippedString[];
    }
  | {
      status: 'failed';
      error: string;
    };
```

`error` 表示目标级别的失败。仅当 General Translation 以状态码 `402` 拒绝处理该任务时，才会返回 `usageLimitReached`。

`applied` 包含已写入 Payload 的稳定字段键。`skipped` 说明哪些待翻译字符串未被写入及其原因。

### `SkippedString` 和 `SkippedReason`

```ts
type SkippedString = {
  key: string;
  reason: SkippedReason;
};

type SkippedReason =
  | 'removed'
  | 'broken_markup'
  | 'missing'
  | 'unsaved_edit';
```

| 原因              | 含义                                          |
| --------------- | ------------------------------------------- |
| `removed`       | 源行、块或字段已不存在。                                |
| `broken_markup` | 返回的富文本或链接无法安全重建。                            |
| `missing`       | 源键没有返回任何翻译值。                                |
| `unsaved_edit`  | 某项 Payload 编辑未能发送，因此已由 `saveLocalEdits` 保留。 |

### `SiteResult` 和 `DocumentResult`

```ts
type DocumentResult<T> = {
  target: TranslateTarget;
  result: T;
};

type SiteResult = {
  error?: string;
  documents: DocumentResult<TranslateResult>[];
};
```

`DocumentResult` 会将部分成功和部分失败的结果分别关联到对应的集合文档或全局对象 (global) 上。

### `SaveTranslationsResult`

```ts
type SaveTranslationsResult = {
  error?: string;
  locales: Record<
    string,
    | { status: 'saved'; unsaved?: number }
    | { status: 'no_translations'; unsaved?: number }
    | { status: 'failed'; error: string }
  >;
};
```

`unsaved` 表示插件因链接与源文档不一致而无法发送的字符串数量。

### `GtClient`

`GtClient` 是插件所使用的 `generaltranslation` `GT` 类的子集：

```ts
type GtClient = Pick<
  GT,
  | 'uploadSourceFiles'
  | 'enqueueFiles'
  | 'awaitJobs'
  | 'downloadFileBatch'
  | 'uploadTranslations'
  | 'checkJobStatus'
  | 'translateMany'
  | 'customMapping'
>;
```

在生产环境中请使用 `GT` 实例。这一更窄的类型同样便于使用测试替身。

## 管理后台组件 [#admin-components]

该插件按 import map 路径注册以下导出：

| 组件                     | 入口                  | 作用                                  |
| ---------------------- | ------------------- | ----------------------------------- |
| `GtDocumentControls`   | `gt-payload/client` | 为文档或全局对象 添加 **Translate** 按钮和抽屉。 |
| `GtNavLink`            | `gt-payload/client` | 添加 **译文** 导航链接。           |
| `GtRunsProvider`       | `gt-payload/client` | 在管理面板打开期间，查找并推进尚未完成的运行。             |
| `GtTranslationsClient` | `gt-payload/client` | 渲染全站范围的控制项和覆盖率表格。                   |
| `GtTranslationsView`   | `gt-payload/rsc`    | 将客户端视图包裹在 Payload 的管理后台 template 中。 |

请直接添加 [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration)，无需单独注册这些组件。之所以导出这些组件，是为了让 Payload 生成的 import map 能够解析插件配置。

## Sitemap

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