# General Translation Platform: Tradurre a Runtime
URL: https://generaltranslation.com/it/docs/platform/openapi/reference/translation/translate-runtime.mdx
---

title: Tradurre a Runtime
description: Traduci stringhe o contenuti strutturati direttamente da un'applicazione o un servizio con General Translation. Riferimento API per la traduzione di contenuti a Runtime.

method: POST
---

Traduce in batch richieste con key in un'unica impostazione regionale di destinazione e restituisce le traduzioni nella risposta. General Translation usa un approccio cache-first, quindi le richieste ripetute sono rapide ed economiche.

## Panoramica [#overview]

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

**Permesso** `project:translations:generate` · **Limite di richieste** Predefinito (200/min)

Traduci i contenuti on demand dalla tua applicazione o dal tuo servizio. Questo endpoint usa l'URL di base del runtime `https://runtime2.gtx.dev`. Per tradurre invece interi file in background, usa [Metti in coda le traduzioni](/docs/platform/openapi/reference/translation/queue).

## Come funziona [#how-it-works]

* Le richieste sono una mappatura tra le tue chiavi e il contenuto sorgente. Ogni richiesta viene risolta in modo indipendente e i risultati sono associati alle stesse chiavi.
* Il servizio controlla prima la cache memoizzata, poi le traduzioni in corso e infine completa eventuali traduzioni rimanenti prima di restituire la risposta. Le nuove traduzioni completate vengono quindi salvate nella cache.
* Il `dataFormat` di ogni richiesta determina come viene analizzato il `source`: `STRING` (predefinito), `JSX`, `ICU` o `I18NEXT`.
* L'impostazione di `metadata.modelProvider` richiede un piano Enterprise; in caso contrario, la richiesta restituisce `403`.
* Le impostazioni regionali di destinazione vengono verificate rispetto a quelle consentite nel progetto.
* In caso di successo, la risposta è `201` (oppure `200` quando ogni richiesta è stata servita dalla cache).

## Richiesta [#request]

### Header

| Header            | Descrizione                                                                      | Obbligatorio |
| ----------------- | -------------------------------------------------------------------------------- | ------------ |
| `x-gt-api-key`    | Chiave API del progetto o dell'Organizzazione.                               | Sì           |
| `x-gt-project-id` | ID progetto. Obbligatorio quando si utilizza una chiave dell'Organizzazione. | No           |

### Body

**Tipo di contenuto** `application/json`

| Campo                   | Descrizione                                                                             | Tipo     | Facoltativo | Predefinito |
| ----------------------- | --------------------------------------------------------------------------------------- | -------- | ----------- | ----------- |
| [`requests`](#requests) | Mappa dalla chiave della richiesta al contenuto da tradurre; ne è richiesto almeno uno. | `object` | No          | —           |
| `targetLocale`          | Impostazione regionale in cui tradurre; non può essere vuota.                           | `string` | No          | —           |
| `sourceLocale`          | Impostazione regionale del contenuto sorgente; non può essere vuota.                    | `string` | No          | —           |
| `metadata`              | Metadati condivisi tra tutte le richieste.                                              | `object` | Sì          | —           |

L'oggetto `metadata` condiviso accetta `modelProvider` (un identificatore consentito del provider del modello; solo per Enterprise).

#### `requests` [#requests]

**Tipo** `object` · **Obbligatorio**

Ogni valore corrisponde a una singola richiesta di traduzione:

| Campo      | Descrizione                                                                    | Tipo      | Facoltativo | Predefinito |
| ---------- | ------------------------------------------------------------------------------ | --------- | ----------- | ----------- |
| `source`   | Contenuto sorgente da tradurre. La struttura dipende da `metadata.dataFormat`. | `unknown` | No          | —           |
| `metadata` | Metadati per singola richiesta.                                                | `object`  | Sì          | Vedi sotto  |

Campi di `metadata` per singola richiesta:

| Campo        | Descrizione                                                        | Tipo     | Facoltativo | Predefinito |
| ------------ | ------------------------------------------------------------------ | -------- | ----------- | ----------- |
| `dataFormat` | Formato del contenuto: `STRING`, `JSX`, `ICU` o `I18NEXT`.         | `string` | Sì          | `STRING`    |
| `context`    | Contesto aggiuntivo per guidare la traduzione.                     | `string` | Sì          | —           |
| `id`         | Identificatore della voce fornito dal chiamante.                   | `string` | Sì          | —           |
| `hash`       | Hash del contenuto; calcolato lato server se omesso.               | `string` | Sì          | —           |
| `maxChars`   | Numero massimo di caratteri per la traduzione.                     | `number` | Sì          | —           |
| `actionType` | Tipo di azione di traduzione.                                      | `string` | Sì          | `fast`      |
| `sourceCode` | Frammenti di codice sorgente circostante come contesto aggiuntivo. | `object` | Sì          | —           |

## Risposta [#response]

**Stato** `201 Created`

Ogni voce è associata alla rispettiva chiave della richiesta. Le voci elaborate correttamente includono la traduzione; quelle non riuscite includono un errore e un codice.

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

## Errori [#errors]

| Stato | Causa                                                                                                                                |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Corpo della richiesta non valido oppure impostazione regionale sorgente o di destinazione non valida.                                |
| `401` | Chiave API mancante o non valida.                                                                                                    |
| `402` | Quota di token esaurita oppure impossibile fatturare la richiesta.                                                                   |
| `403` | La chiave API non dispone di `project:translations:generate`, oppure un `modelProvider` personalizzato richiede un piano Enterprise. |
| `429` | Superato il limite di richieste.                                                                                                     |

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