# General Translation Platform: Перевод во время выполнения
URL: https://generaltranslation.com/ru/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 Runtime `https://runtime2.gtx.dev`. Если вместо этого нужно переводить файлы целиком в фоновом режиме, используйте [Поставить переводы в очередь](/docs/platform/openapi/reference/translation/queue).

## Как это работает [#how-it-works]

* Requests — это сопоставление ваших собственных ключей с исходным содержимым. Каждый запрос обрабатывается независимо, а результаты возвращаются под теми же ключами.
* Сервис сначала проверяет свой мемоизированный кэш, затем переводы, которые ещё выполняются, и, наконец, завершает все оставшиеся переводы перед возвратом ответа. Вновь завершённые переводы записываются обратно в кэш.
* `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`

| Поле                    | Описание                                                                                    | Тип      | Необязательное | По умолчанию |
| ----------------------- | ------------------------------------------------------------------------------------------- | -------- | -------------- | ------------ |
| [`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`  | Квота токенов исчерпана или запрос невозможно тарифицировать.                                                                |
| `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"
  }'
```