# General Translation Platform: Traducir en tiempo de ejecución
URL: https://generaltranslation.com/es/docs/platform/openapi/reference/translation/translate-runtime.mdx
---

title: Traducir en tiempo de ejecución
description: Traduce cadenas o contenido estructurado directamente desde una aplicación o servicio con General Translation. Referencia de la API para traducir contenido en tiempo de ejecución.

method: POST
---

Traduce un lote de solicitudes con clave a una única configuración regional de destino y devuelve las traducciones en la respuesta. General Translation usa una estrategia que prioriza la caché, por lo que las solicitudes repetidas son rápidas y económicas.

## Resumen general [#overview]

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

**Permiso** `project:translations:generate` · **Límite de solicitudes** Predeterminado (200/min)

Traduce contenido bajo demanda desde tu propia aplicación o servicio. Este endpoint usa la URL base de Runtime `https://runtime2.gtx.dev`. Si en cambio quieres traducir archivos completos en segundo plano, usa [Encolar traducciones](/docs/platform/openapi/reference/translation/queue).

## Cómo funciona [#how-it-works]

* Las solicitudes son un mapa de tus propias claves al contenido fuente. Cada solicitud se resuelve de forma independiente y los resultados se devuelven con esas mismas claves.
* El servicio primero consulta su caché memoizada, luego las traducciones en curso y, por último, completa cualquier traducción pendiente antes de responder. Las traducciones recién completadas se vuelven a guardar en la caché.
* El `dataFormat` de cada solicitud determina cómo se analiza su `source`: `STRING` (predeterminado), `JSX`, `ICU` o `I18NEXT`.
* Configurar `metadata.modelProvider` requiere un plan Enterprise; de lo contrario, la solicitud devuelve `403`.
* Las configuraciones regionales de destino se validan según las configuraciones regionales permitidas del proyecto.
* Una respuesta exitosa es `201` (o `200` cuando todas las solicitudes se atendieron desde la caché).

## Solicitud [#request]

### Cabeceras

| Cabecera          | Descripción                                                           | Obligatorio |
| ----------------- | --------------------------------------------------------------------- | ----------- |
| `x-gt-api-key`    | API key del proyecto o de la Organization.                            | Sí          |
| `x-gt-project-id` | ID del proyecto. Obligatorio cuando se usa una clave de Organization. | No          |

### Cuerpo

**Tipo de contenido** `application/json`

| Campo                   | Descripción                                                                              | Tipo     | Opcional | Predeterminado |
| ----------------------- | ---------------------------------------------------------------------------------------- | -------- | -------- | -------------- |
| [`requests`](#requests) | Mapa de claves de solicitud al contenido que se va a traducir; se requiere al menos una. | `object` | No       | —              |
| `targetLocale`          | Configuración regional a la que se traducirá; no puede estar vacía.                      | `string` | No       | —              |
| `sourceLocale`          | Configuración regional del contenido de origen; no puede estar vacía.                    | `string` | No       | —              |
| `metadata`              | Metadatos compartidos por todas las solicitudes.                                         | `object` | Sí       | —              |

El objeto `metadata` compartido acepta `modelProvider` (un identificador de proveedor de modelos permitido; solo para Enterprise).

#### `requests` [#requests]

**Tipo** `object` · **Obligatorio**

Cada valor es una solicitud de traducción individual:

| Campo      | Descripción                                                                               | Tipo      | Opcional | Predeterminado |
| ---------- | ----------------------------------------------------------------------------------------- | --------- | -------- | -------------- |
| `source`   | Contenido de origen que se va a traducir. La estructura depende de `metadata.dataFormat`. | `unknown` | No       | —              |
| `metadata` | Metadatos por solicitud.                                                                  | `object`  | Sí       | Ver abajo      |

Campos de `metadata` por solicitud:

| Campo        | Descripción                                                                    | Tipo     | Opcional | Predeterminado |
| ------------ | ------------------------------------------------------------------------------ | -------- | -------- | -------------- |
| `dataFormat` | Formato del contenido: `STRING`, `JSX`, `ICU` o `I18NEXT`.                     | `string` | Sí       | `STRING`       |
| `context`    | Contexto adicional para orientar la traducción.                                | `string` | Sí       | —              |
| `id`         | Identificador de la entrada proporcionado por quien realiza la llamada.        | `string` | Sí       | —              |
| `hash`       | Hash del contenido; se calcula en el servidor cuando se omite.                 | `string` | Sí       | —              |
| `maxChars`   | Longitud máxima en caracteres de la traducción.                                | `number` | Sí       | —              |
| `actionType` | Tipo de acción de traducción.                                                  | `string` | Sí       | `fast`         |
| `sourceCode` | Fragmentos del código fuente circundante para proporcionar contexto adicional. | `object` | Sí       | —              |

## Respuesta [#response]

**Estado** `201 Created`

Cada entrada se identifica por su clave de solicitud. Las entradas correctas incluyen la traducción; las entradas fallidas incluyen un error y un código.

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

## Errores [#errors]

| Estado | Causa                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------- |
| `400`  | Cuerpo de la solicitud no válido o configuración regional de origen/destino no válida.                               |
| `401`  | Falta la API key o no es válida.                                                                                     |
| `402`  | Se agotó la cuota de tokens o la solicitud no se puede facturar.                                                     |
| `403`  | La API key no tiene `project:translations:generate`, o un `modelProvider` personalizado requiere un plan Enterprise. |
| `429`  | Se superó el límite de solicitudes.                                                                                  |

## Ejemplo [#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"
  }'
```