# General Translation Platform: 在运行时翻译
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/translation/translate-runtime.mdx
---

title: 在运行时翻译
description: 使用 General Translation 直接在应用程序或服务中翻译字符串或结构化内容。运行时翻译内容的 API 参考。

method: POST
---

将一批带键的请求翻译为同一个目标区域设置，并在响应中返回译文。General Translation 采用缓存优先策略，因此重复请求速度快且成本低。

## 概览 [#overview]

```http
POST https://runtime2.gtx.dev/v2/translate
```

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

通过您自己的应用程序或服务按需翻译内容。此端点使用运行时基础 URL `https://runtime2.gtx.dev`。如果您想改为在后台翻译整个文件，请使用[将翻译加入队列](/docs/platform/openapi/reference/translation/queue)。

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

* 请求是一个将你自己的键映射到源内容的映射。每个请求都会独立处理，结果也会使用相同的键返回。
* 服务会先检查其记忆化缓存，然后检查进行中的翻译，最后在返回前完成所有剩余翻译。新完成的翻译会写回缓存。
* 每个请求的 `dataFormat` 用于指定如何解析其 `source`：`STRING` (默认) 、`JSX`、`ICU` 或 `I18NEXT`。
* 设置 `metadata.modelProvider` 需要 Enterprise 方案；否则请求会返回 `403`。
* 目标区域设置会根据项目允许的区域设置进行校验。
* 成功响应为 `201` (如果所有请求都直接由缓存提供，则为 `200`) 。

## 请求 [#request]

### 请求头

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

### 正文

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

| 字段                      | 描述                      | 类型       | 可选 | 默认值 |
| ----------------------- | ----------------------- | -------- | -- | --- |
| [`requests`](#requests) | 从请求键到待翻译内容的映射；至少需要提供一个。 | `object` | 否  | —   |
| `targetLocale`          | 要翻译到的区域设置；不能为空。         | `string` | 否  | —   |
| `sourceLocale`          | 源内容的区域设置；不能为空。          | `string` | 否  | —   |
| `metadata`              | 所有请求共享的元数据。             | `object` | 是  | —   |

共享的 `metadata` 对象支持 `modelProvider` (允许的模型提供方标识符；仅 Enterprise 可用) 。

#### `requests` [#requests]

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

每个值都表示一次单独的翻译请求：

| 字段         | 说明                                    | 类型        | 可选 | 默认值 |
| ---------- | ------------------------------------- | --------- | -- | --- |
| `source`   | 要翻译的源内容。其结构取决于 `metadata.dataFormat`。 | `unknown` | 否  | —   |
| `metadata` | 每个请求的元数据。                             | `object`  | 是  | 见下文 |

每个请求的 `metadata` 字段：

| 字段           | 说明                                     | 类型       | 可选 | 默认值      |
| ------------ | -------------------------------------- | -------- | -- | -------- |
| `dataFormat` | 内容格式：`STRING`、`JSX`、`ICU` 或 `I18NEXT`。 | `string` | 是  | `STRING` |
| `context`    | 用于指导翻译的额外上下文。                          | `string` | 是  | —        |
| `id`         | 调用方为该条目提供的标识符。                         | `string` | 是  | —        |
| `hash`       | 内容哈希；省略时由服务端计算。                        | `string` | 是  | —        |
| `maxChars`   | 翻译的最大字符长度。                             | `number` | 是  | —        |
| `actionType` | 翻译操作类型。                                | `string` | 是  | `fast`   |
| `sourceCode` | 周围的源代码片段，用于提供更多上下文。                    | `object` | 是  | —        |

## 响应 [#response]

**状态** `201 Created`

每个条目都按其请求键进行索引。成功的条目包含译文；失败的条目包含错误信息和错误代码。

```json title="Response"
{
  "key1": {
    "success": true,
    "translation": "Hola, mundo",
    "dataFormat": "STRING",
    "locale": "es"
  }
}
```

## 错误 [#errors]

| 状态    | 原因                                                                              |
| ----- | ------------------------------------------------------------------------------- |
| `400` | 请求体无效，或源/目标区域设置无效。                                                              |
| `401` | 缺少 API 密钥，或 API 密钥无效。                                                           |
| `402` | Token 配额已耗尽，或请求无法计费。                                                            |
| `403` | API 密钥缺少 `project:translations:generate`，或自定义 `modelProvider` 需要 Enterprise 方案。 |
| `429` | 超出速率限制。                                                                         |

## 示例 [#example]

```bash
curl -X POST https://runtime2.gtx.dev/v2/translate \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "requests": {
      "key1": { "source": "Hello, world" }
    },
    "sourceLocale": "en",
    "targetLocale": "es"
  }'
```