# General Translation Platform: translate
URL: https://generaltranslation.com/it/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Traduce una stringa o una voce di contenuto strutturato in un'impostazione regionale di destinazione con General Translation. Riferimento API per translate.

`translate` è il metodo di traduzione principale di un'[istanza GT](/docs/platform/core/reference/gt-class/constructor) e consente di tradurre una stringa o una voce di contenuto strutturato alla volta.

## Panoramica [#overview]

Chiama `translate` su un'istanza [`GT`](/docs/platform/core/reference/gt-class/constructor) configurata per tradurre una voce. Passa il contenuto da tradurre e una stringa dell'impostazione regionale di destinazione (forma abbreviata) oppure un oggetto options. Restituisce una Promise che si risolve con un [`TranslationResult`](/docs/platform/core/reference/types/translation-result).

```typescript
const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id' });

const result = await gt.translate('Hello, world!', 'es');
```

Firma:

```typescript
translate(
  source: TranslateManyEntry,
  options: string | TranslateOptions,
  timeout?: number
): Promise<TranslationResult>
```

*Nota: `translate` richiede un `apiKey` (o `devApiKey`) e `projectId` sull&#39;istanza GT. Internamente richiama [`translateMany`](/docs/platform/core/reference/gt-class-methods/translation/translate-many) con una singola voce.*

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

* **Rilevamento del contenuto.** Il `source` viene interpretato come testo semplice, messaggio ICU, messaggio in stile i18next oppure contenuto JSX strutturato, in base alla sua forma e ai metadati `dataFormat` forniti.
* **Documenti interi.** Imposta [`metadata.fileFormat`](/docs/platform/core/reference/types/entry-metadata#file-format) su `'MD'` o `'MDX'` per analizzare e tradurre un documento completo preservandone la struttura. Il documento deve essere una stringa con `dataFormat: 'STRING'`, che è il valore predefinito, e non può usare `maxChars`. Una entry di tipo documento fallisce anziché restituire un output parziale quando un blocco fallisce o il documento tradotto non è valido.
* **Risoluzione dell&#39;impostazione regionale.** L&#39;impostazione regionale di destinazione viene validata rispetto a BCP 47. Viene applicato qualsiasi [`customMapping`](/docs/platform/core/reference/types/custom-mapping) presente nell&#39;istanza e il codice locale canonico viene inviato all&#39;API.
* **Sintassi abbreviata delle opzioni.** Passare una stringa come `options` è una sintassi abbreviata per `{ targetLocale: string }`, quindi `gt.translate('Hello', 'es')` e `gt.translate('Hello', { targetLocale: 'es' })` sono equivalenti.

## Parametri [#parameters]

| Parametro             | Descrizione                                                                            | Type                                                                             | Facoltativo | Predefinito |
| --------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- | ----------- |
| [`source`](#source)   | Contenuto da tradurre: una stringa o un oggetto con `source` e `metadata` facoltativo. | [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) | No          | —           |
| [`options`](#options) | Stringa dell&#39;impostazione regionale di destinazione oppure un oggetto options.     | `string \| TranslateOptions`                                                     | No          | —           |
| [`timeout`](#timeout) | Timeout della richiesta in millisecondi.                                               | `number`                                                                         | Sì          | —           |

### `source` [#source]

**Tipo** [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) · **Obbligatorio**

Il contenuto da tradurre. Passa una stringa semplice oppure un oggetto con `source` (il [`Content`](/docs/platform/core/reference/types/content)) e `metadata` facoltativo (un [`EntryMetadata`](/docs/platform/core/reference/types/entry-metadata) che aggiunge contesto, `dataFormat` e altri suggerimenti per la traduzione).

### `options` [#options]

**Tipo** `string | TranslateOptions` · **Obbligatorio**

Una stringa dell&#39;impostazione regionale di destinazione, ad esempio `'es'`, oppure un oggetto options:

```typescript
type TranslateOptions = {
  targetLocale: string; // impostazione regionale in cui tradurre
  sourceLocale?: string; // sovrascrive il sourceLocale dell'istanza
  modelProvider?: string; // suggerimento facoltativo sul provider del modello
};
```

### `timeout` [#timeout]

**Tipo** `number` · **Facoltativo**

Timeout della richiesta in millisecondi. Se omesso, viene utilizzato il valore predefinito dell&#39;istanza.

## Restituisce [#returns]

**Tipo** `Promise<TranslationResult>`

Restituisce un [`TranslationResult`](/docs/platform/core/reference/types/translation-result): un&#39;unione discriminata tra un risultato di successo (con `translation` e `locale`) e un risultato di errore (con `error` e `code`). Verifica sempre `success` prima di leggere la traduzione.

## Esempi [#examples]

```typescript
// Traduzione semplice di una stringa (impostazione regionale abbreviata)
const result = await gt.translate('Welcome to our application', 'fr');

if (result.success) {
  console.log(result.translation); // "Bienvenue dans notre application"
} else {
  console.error(`Translation failed: ${result.error}`);
}
```

```typescript
// Con un oggetto options e impostazione regionale sorgente esplicita
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```

```typescript
// Con metadati sorgente (plurale ICU + contesto)
const result = await gt.translate(
  {
    source: '{count, plural, other {{count} items}}',
    metadata: { dataFormat: 'ICU', context: 'Item count display' },
  },
  { targetLocale: 'es' }
);
```

```typescript
// Traduci un documento Markdown completo.
const result = await gt.translate(
  {
    source: '# Welcome\n\nRead the [guide](/guide).',
    metadata: { fileFormat: 'MD' },
  },
  { sourceLocale: 'en', targetLocale: 'es' }
);
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.