# General Translation Platform: 将翻译加入队列
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/translation/queue.mdx
---

title: 将翻译加入队列
description: 将已上传的源文件加入队列，以便在 General Translation 项目中进行后台翻译。翻译入队的 API 参考。

method: POST
---

将已上传源文件的后台翻译任务加入队列。最多可指定 100 个文件，以及要翻译到的目标 locales。

## 概览 [#overview]

```http
POST https://api2.gtx.dev/v2/project/translations/enqueue
```

**权限** `project:translations:enqueue` · **速率限制** 高 (30/分钟) 

开始在后台翻译已上传的文件。请先使用[上传源文件](/docs/platform/openapi/reference/files/upload-source)上传文件，然后使用[获取翻译任务状态](/docs/platform/openapi/reference/translation/job-status)跟踪生成的任务状态。

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

* 每个引用到的源文件都必须已存在。缺失的源文件会在 `400` 响应中报告，其中包含一个 `missing` 列表和一个 `count`。
* 未提供 `branchId` 时，会使用默认分支。设置 `transformFormat` 可将文件翻译为不同的输出文件格式。
* 省略 `targetLocales` 时，将使用项目中配置的 locales。已翻译为某个区域设置的文件会被跳过，除非 `force` 为 `true`。
* 响应结构取决于通过 `gt-api-version` 请求头传递的 API 版本。`2025-11-03.v1` 及更高版本会返回以 job 为键的 `jobData`。请参阅[概览中的版本控制](/docs/platform/openapi/overview#api-basics)。

## 请求 [#request]

### 请求头

| 请求头               | 描述               | 必填 |
| ----------------- | ---------------- | -- |
| `x-gt-api-key`    | 项目或组织的 API 密钥。   | 是  |
| `x-gt-project-id` | 项目 ID。使用组织密钥时必填。 | 否  |

### 请求正文

**Content type** `application/json`

| 字段                | 描述                | 类型         | 可选 | 默认值        |
| ----------------- | ----------------- | ---------- | -- | ---------- |
| [`files`](#files) | 要翻译的源文件 (1–100) 。 | `object[]` | 否  | —          |
| `targetLocales`   | 要翻译到的 locales。        | `string[]` | 是  | 项目 locales |
| `sourceLocale`    | 文件的源区域设置。         | `string`   | 是  | 项目默认区域设置   |
| `force`           | 重新翻译已存在译文的文件。     | `boolean`  | 是  | `false`    |
| `modelProvider`   | 用于翻译的模型提供方。       | `string`   | 是  | —          |
| `publish`         | 将生成的译文发布到 CDN。    | `boolean`  | 是  | —          |

#### `files` [#files]

**类型** `object[]` · **必填**

每个元素都指向一个已上传的源文件：

| 字段                | 说明           | 类型       | 可选 | 默认值   |
| ----------------- | ------------ | -------- | -- | ----- |
| `fileId`          | 稳定的文件标识符；必填。 | `string` | 否  | —     |
| `versionId`       | 版本标识符；必填。    | `string` | 否  | —     |
| `branchId`        | 文件所属的分支。     | `string` | 是  | 默认分支  |
| `fileName`        | 文件名。         | `string` | 是  | —     |
| `transformFormat` | 要翻译成的输出文件格式。 | `string` | 是  | 源文件格式 |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "jobData": {
    "job_...": {
      "sourceFileId": "sf_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "branchId": "br_...",
      "targetLocale": "es",
      "projectId": "prj_...",
      "force": false
    }
  },
  "locales": ["es", "fr"],
  "message": "Enqueued 2 translation(s)."
}
```

## 错误 [#errors]

| 状态    | 原因                                                     |
| ----- | ------------------------------------------------------ |
| `400` | 请求体无效、区域设置无效，或找不到引用的源文件 (返回时会附带 `missing` 和 `count`) 。 |
| `401` | 缺少 API 密钥，或 API 密钥 无效。                               |
| `403` | API 密钥 不具备 `project:translations:enqueue` 权限。         |
| `429` | 超出速率限制。                                                |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/translations/enqueue \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "fileId": "file_...",
        "versionId": "ver_..."
      }
    ],
    "targetLocales": ["es", "fr"]
  }'
```