# General Translation Platform: 获取翻译状态
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/translation-status.mdx
---

title: 获取翻译状态
description: 按文件和区域设置查看 General Translation 项目中的翻译进度和可用性。获取翻译状态的 API 参考。

method: GET
---

返回单个源文件在各区域设置下的翻译状态，以及该源文件的元数据。可用它轮询检查翻译是否已完成、已批准或已发布。

## 概览 [#overview]

```http
GET https://api2.gtx.dev/v2/project/translations/files/status/:fileId
```

**权限** `project:files:read` · **速率限制** 默认 (200/分钟) 

查看单个文件的翻译进度。若要一次查询多个文件的元数据，请使用 [获取文件信息](/docs/platform/openapi/reference/files/file-info)。

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

* 系统会在指定分支上通过 `fileId` 解析源文件。若未提供 `branchId`，则默认解析到默认分支；若未提供 `versionId`，则使用该分支的头部版本。
* 响应会为源文件中的每个区域设置列出一个条目。对于尚未有翻译的区域设置，时间戳字段为 `null`。
* 如果未找到源文件，请求将返回 `404`。

## 请求 [#request]

### 请求头

| 请求头               | 描述                                 | 必填 |
| ----------------- | ---------------------------------- | -- |
| `x-gt-api-key`    | 项目或 Organization API Key。          | 是  |
| `x-gt-project-id` | 项目 ID。使用 Organization API Key 时必填。 | 否  |

### 路径参数

| 参数       | 描述            | 类型       | 必填 |
| -------- | ------------- | -------- | -- |
| `fileId` | 用于检查的稳定文件标识符。 | `string` | 是  |

### 查询参数

| 参数          | 描述           | 类型       | 可选 | 默认值       |
| ----------- | ------------ | -------- | -- | --------- |
| `versionId` | 要检查的指定版本。    | `string` | 是  | 分支头版本     |
| `branchId`  | 要读取的 分支。 | `string` | 是  | 默认 分支 |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "translations": [
    {
      "locale": "es",
      "completedAt": "2026-01-01T00:00:00.000Z",
      "approvedAt": null,
      "publishedAt": null,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "sourceFile": {
    "id": "sf_...",
    "branchId": "br_...",
    "fileId": "file_...",
    "versionId": "ver_...",
    "fileName": "en/common.json",
    "sourceLocale": "en",
    "fileFormat": "JSON",
    "dataFormat": "JSON",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "locales": ["es"]
  }
}
```

## 错误 [#errors]

| 状态    | 原因                                   |
| ----- | ------------------------------------ |
| `400` | 缺少 `fileId`。                         |
| `401` | 缺少 API Key，或 API Key 无效。             |
| `403` | API Key 不具备 `project:files:read` 权限。 |
| `404` | 未找到源文件，或未找到翻译内容。                     |
| `429` | 超出速率限制。                              |

## 示例 [#example]

```bash
curl -X GET "https://api2.gtx.dev/v2/project/translations/files/status/file_...?branchId=br_..." \
  -H "x-gt-api-key: gtx-api-..."
```