# General Translation Platform: 提交文件差异
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/submit-diffs.mdx
---

title: 提交文件差异
description: 将已更改源内容或已翻译内容的差异提交到 General Translation 项目，而不是上传完整文件。提交文件差异的 API 参考。

method: POST
---

对于已更改的文件，用本地编辑的内容覆盖已存储的翻译。为每个已更改的文件和区域设置发送一个条目，这样你就可以同步本地编辑，而无需重新上传每个文件。

## 概览 [#overview]

```http
POST https://api2.gtx.dev/v2/project/files/diffs
```

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

将本地翻译的修改推送回项目。若要直接替换整个文件，请改用[上传翻译](/docs/platform/openapi/reference/files/upload-translations)。

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

* 条目按 `branchId`、`fileId`、`versionId` 和 `locale` 分组。每组仅应用第一个条目，因此单次请求中的重复分组会被去重。
* `localContent` 为空的条目会被跳过。
* 对于其余每个组，已存储的译文都会被 `localContent` 覆盖。若缺少 `branchId`，则会解析为默认分支。
* 响应会说明处理了多少条译文，以及接收了多少个条目。

## 请求 [#request]

### 请求头

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

### 请求体

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

| 字段                | 描述               | 类型         | 可选 | 默认值 |
| ----------------- | ---------------- | ---------- | -- | --- |
| [`diffs`](#diffs) | 由差异条目组成的数组；不能为空。 | `object[]` | 否  | —   |

#### `diffs` [#diffs]

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

每个元素描述一个已更改的文件及其区域设置：

| 字段             | 描述                     | 类型       | 可选 | 默认值  |
| -------------- | ---------------------- | -------- | -- | ---- |
| `localContent` | 要为该翻译存储的完整本地 (已编辑) 内容。 | `string` | 否  | —    |
| `locale`       | 已编辑内容的区域设置；不能为空。       | `string` | 否  | —    |
| `fileId`       | 稳定的文件标识符。              | `string` | 否  | —    |
| `versionId`    | 此内容的版本标识符。             | `string` | 否  | —    |
| `diff`         | 已更改内容的差异。              | `string` | 否  | —    |
| `branchId`     | 文件所属的分支。               | `string` | 是  | 默认分支 |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "filesProcessed": 1,
  "entriesReceived": 1,
  "message": "Processed 1 translation(s)"
}
```

## 错误 [#errors]

| 状态    | 原因                                 |
| ----- | ---------------------------------- |
| `400` | 请求体无效，或 `diffs` 数组为空。              |
| `401` | 缺少 API 密钥，或 API 密钥无效。              |
| `403` | API 密钥缺少 `project:files:write` 权限。 |
| `429` | 已超出速率限制。                           |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/diffs \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "diffs": [
      {
        "fileId": "file_...",
        "versionId": "ver_...",
        "locale": "es",
        "diff": "@@ -1 +1 @@\n-Hola\n+Hola, mundo",
        "localContent": "{\"hello\": \"Hola, mundo\"}"
      }
    ]
  }'
```