# General Translation Platform: 上传翻译
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/upload-translations.mdx
---

title: 上传翻译
description: 将翻译后的文件上传到 General Translation 项目，这些文件需与之前上传的源文件相对应。上传翻译的 API 参考。

method: POST
---

上传已翻译的文件，适用于之前已上传的源文件。每个条目都会将一个源文件引用与一个或多个译文配对，每次请求最多支持 100 个条目。

## 概览 [#overview]

```http
POST https://api2.gtx.dev/v2/project/files/upload-translations
```

**权限** `project:files:write` · **速率限制** 中等 (120/分钟) 

将现有译文关联到项目，以便与其源文件一同存储。若要先上传源文件，请使用[上传源文件](/docs/platform/openapi/reference/files/upload-source)。若要改为使用 General Translation 翻译源文件，请参阅[加入翻译队列](/docs/platform/openapi/reference/translation/queue)。

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

* 每个条目的 `source` 都指向一个必须已存在的源文件。源文件通过 `branchId`、`versionId` 和 `fileId` 匹配；如果缺少 `branchId`，则会解析为默认分支。如果找不到所引用的源文件，请求会以 `400` 失败。
* `source` 对象会按与上传相同的方式进行验证，因此省略时，`fileId` 默认取 `fileName` 的哈希值，`versionId` 默认取内容的哈希值。
* 每个翻译的 `content` 都会以 base64 编码，并在服务器端解码；无效的 base64 或过大的文件都会被拒绝。
* 翻译会继承其源文件的 `fileId`、`versionId`、`branchId` 和 `fileName`。设置 `transformFormat` 可将翻译存储为不同的输出文件格式。
* 已上传的翻译会被标记为已完成。如果项目启用了自动批准，它们也会被标记为已批准。`GTJSON` 翻译会获得根据 `source` 对象派生的组件级审校元数据。
* 每个源文件的区域设置列表都会更新，包含已上传翻译的区域设置。如果项目启用了 CDN，文件会发布到 CDN。
* 如果发送了 `sourceLocale`，且它与项目当前的默认区域设置不同，则会更新项目的默认区域设置。

## 请求 [#request]

### 请求头

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

### 请求体

**内容类型** `application/json`

| 字段              | 说明                     | 类型         | 可选 | 默认值      |
| --------------- | ---------------------- | ---------- | -- | -------- |
| [`data`](#data) | 源条目/翻译条目数组 (1–100 项) 。 | `object[]` | 否  | —        |
| `sourceLocale`  | 上传文件的源区域设置。            | `string`   | 是  | 项目默认区域设置 |

#### `data` [#data]

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

每个元素均为 `{ "source": { ... }, "translations": [ ... ] }`。

`source` 对象用于标识先前上传的源文件：

| Field            | Description                 | Type     | Optional | Default         |
| ---------------- | --------------------------- | -------- | -------- | --------------- |
| `content`        | Base64 编码的源内容。受最大文件大小限制。    | `string` | No       | —               |
| `fileName`       | 文件名；不能为空。                   | `string` | No       | —               |
| `fileFormat`     | 文件格式标识符 (例如 `JSON`、`MDX`) 。 | `string` | No       | —               |
| `locale`         | 源内容的区域设置；不能为空。              | `string` | No       | —               |
| `dataFormat`     | 结构化内容的数据格式。                 | `string` | Yes      | —               |
| `fileId`         | 稳定的文件标识符。                   | `string` | Yes      | `fileName` 的哈希值 |
| `versionId`      | 此内容的版本标识符。                  | `string` | Yes      | 内容的哈希值          |
| `branchId`       | 源文件关联的分支。                   | `string` | Yes      | 默认分支            |
| `formatMetadata` | 额外的格式专用元数据。                 | `object` | Yes      | —               |

`translations` 中的每个元素都是一个翻译后的文件。每个条目至少需要提供一个翻译：

| Field             | Description               | Type     | Optional | Default |
| ----------------- | ------------------------- | -------- | -------- | ------- |
| `content`         | Base64 编码的翻译内容。受最大文件大小限制。 | `string` | No       | —       |
| `fileName`        | 文件名；不能为空。                 | `string` | No       | —       |
| `fileFormat`      | 文件格式标识符。                  | `string` | No       | —       |
| `locale`          | 翻译的目标区域设置；不能为空。           | `string` | No       | —       |
| `dataFormat`      | 结构化内容的数据格式。               | `string` | Yes      | —       |
| `transformFormat` | 用于存储该翻译的输出文件格式。           | `string` | Yes      | 源文件格式   |

## 响应 [#response]

**状态** `201 Created`

```json title="Response"
{
  "uploadedFiles": [
    {
      "branchId": "br_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "fileName": "en/common.json",
      "locale": "es",
      "fileFormat": "JSON",
      "dataFormat": "JSON"
    }
  ],
  "count": 1,
  "message": "Successfully uploaded 1 translation file(s)"
}
```

## 错误 [#errors]

| 状态    | 原因                                    |
| ----- | ------------------------------------- |
| `400` | 请求体无效、区域设置/格式无效、解码失败、文件过大，或找不到引用的源文件。 |
| `401` | 缺少 API 密钥或 API 密钥无效。                  |
| `403` | API 密钥没有 `project:files:write` 权限。    |
| `429` | 超出速率限制。                               |
| `503` | 服务器繁忙；请采用退避策略重试。                      |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/upload-translations \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLocale": "en",
    "data": [
      {
        "source": {
          "content": "eyJoZWxsbyI6ICJIZWxsbyJ9",
          "fileName": "en/common.json",
          "fileFormat": "JSON",
          "locale": "en"
        },
        "translations": [
          {
            "content": "eyJoZWxsbyI6ICJIb2xhIn0=",
            "fileName": "en/common.json",
            "fileFormat": "JSON",
            "locale": "es"
          }
        ]
      }
    ]
  }'
```