# General Translation Platform: ランタイムで翻訳
URL: https://generaltranslation.com/ja/docs/platform/openapi/reference/translation/translate-runtime.mdx
---

title: ランタイムで翻訳
description: General Translation を使って、アプリケーションやサービスから文字列や構造化コンテンツを直接翻訳します。ランタイムでコンテンツを翻訳するための API リファレンスです。

method: POST
---

key 付きリクエストのバッチを 1 つのターゲットロケールに翻訳し、その翻訳結果をレスポンスで返します。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。組織のキーを使用する場合は必須です。 | いいえ |

### 本文

**コンテンツタイプ** `application/json`

| Field                   | Description                             | Type     | Optional | Default |
| ----------------------- | --------------------------------------- | -------- | -------- | ------- |
| [`requests`](#requests) | リクエストキーから翻訳対象のコンテンツへのマップ。少なくとも 1 つ必要です。 | `object` | いいえ      | —       |
| `targetLocale`          | 翻訳先のロケール。空にできません。                       | `string` | いいえ      | —       |
| `sourceLocale`          | ソースコンテンツのロケール。空にできません。              | `string` | いいえ      | —       |
| `metadata`              | すべてのリクエストで共有されるメタデータ。                   | `object` | はい       | —       |

共有の `metadata` オブジェクトでは、`modelProvider` (許可されているモデルプロバイダー識別子。Enterprise のみ) を受け付けます。

#### `requests` [#requests]

**Type** `object` · **必須**

各値は 1 件の翻訳リクエストです。

| Field      | Description                                        | Type      | Optional | Default |
| ---------- | -------------------------------------------------- | --------- | -------- | ------- |
| `source`   | 翻訳対象のソースコンテンツ。構造は `metadata.dataFormat` によって異なります。 | `unknown` | いいえ      | —       |
| `metadata` | リクエストごとのメタデータ。                                     | `object`  | はい       | 以下を参照   |

リクエストごとの `metadata` フィールド:

| Field        | Description                                  | Type     | Optional | Default  |
| ------------ | -------------------------------------------- | -------- | -------- | -------- |
| `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 キーが見つからないか、無効です。                                                                        |
| `402` | トークンの上限に達したか、リクエストを課金できません。                                                                 |
| `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"
  }'
```