# General Translation Platform: translate
URL: https://generaltranslation.com/fr/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Traduisez une chaîne ou une entrée de contenu structuré vers un paramètre régional cible avec General Translation. Référence de l’API pour translate.

`translate` est la principale méthode de traduction d’une instance [GT](/docs/platform/core/reference/gt-class/constructor), pour traduire une chaîne ou une entrée de contenu structuré à la fois.

## Vue d’ensemble [#overview]

Appelez `translate` sur une instance [`GT`](/docs/platform/core/reference/gt-class/constructor) configurée pour traduire une entrée. Passez le contenu à traduire ainsi qu’une chaîne de caractères correspondant au paramètre régional cible (forme abrégée) ou un objet d’options. Cette méthode renvoie une promesse qui se résout en 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');
```

Signature :

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

*Remarque : `translate` nécessite une clé API (y compris l’alias déprécié `devApiKey`), ainsi qu’un `projectId` sur l’instance GT. En interne, il appelle [`translateMany`](/docs/platform/core/reference/gt-class-methods/translation/translate-many) avec une seule entrée.*

## Fonctionnement [#how-it-works]

* **Détection du contenu.** La valeur `source` est interprétée comme du texte brut, un message ICU, un message au format i18next ou un contenu JSX structuré, selon sa structure et les métadonnées `dataFormat` que vous fournissez.
* **Documents complets.** Définissez [`metadata.fileFormat`](/docs/platform/core/reference/types/entry-metadata#file-format) sur `'MD'` ou `'MDX'` pour analyser et traduire un document complet en préservant sa structure. Le document doit être une chaîne avec `dataFormat: 'STRING'`, la valeur par défaut, et ne peut pas utiliser `maxChars`. Une entrée de type document échoue au lieu de renvoyer une sortie partielle lorsqu’un fragment échoue ou que le document traduit est invalide.
* **Résolution du paramètre régional.** Le paramètre régional cible est validé par rapport à BCP 47. Tout [`customMapping`](/docs/platform/core/reference/types/custom-mapping) défini sur l’instance est appliqué, puis le code de langue canonique est envoyé à l’API.
* **Syntaxe abrégée des options.** Passer une chaîne à `options` est une syntaxe abrégée pour `{ targetLocale: string }` ; ainsi, `gt.translate('Hello', 'es')` et `gt.translate('Hello', { targetLocale: 'es' })` sont équivalents.

## Paramètres [#parameters]

| Paramètre             | Description                                                                                               | Type                                                                             | Facultatif | Par défaut |
| --------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------- | ---------- |
| [`source`](#source)   | Contenu à traduire : une chaîne de caractères, ou un objet avec `source` et des métadonnées facultatives. | [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) | Non        | —          |
| [`options`](#options) | Chaîne de paramètre régional cible, ou objet d’options.                                                   | `string \| TranslateOptions`                                                     | Non        | —          |
| [`timeout`](#timeout) | Délai d’expiration de la requête en millisecondes.                                                        | `number`                                                                         | Oui        | —          |

### `source` [#source]

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

Le contenu à traduire. Passez une chaîne de caractères simple, ou un objet avec `source` (le [`Content`](/docs/platform/core/reference/types/content)) et `metadata` en option (un [`EntryMetadata`](/docs/platform/core/reference/types/entry-metadata) qui ajoute du contexte, `dataFormat` et d’autres indications de traduction).

### `options` [#options]

**Type** `string | TranslateOptions` · **Obligatoire**

Une chaîne de caractères représentant le paramètre régional cible, comme `'es'`, ou un objet d’options :

```typescript
type TranslateOptions = {
  targetLocale: string; // paramètre régional cible
  sourceLocale?: string; // remplace le sourceLocale de l'instance
  modelProvider?: string; // validé avant l'appel fetch
  [key: string]: unknown; // métadonnées d'extension, et non des options de transport
};
```

Importez [`TranslateOptions`](/docs/platform/core/reference/types/translation-config#translate-options) depuis `generaltranslation/types`. Les valeurs de `modelProvider` non prises en charge sont rejetées avant l’appel à `fetch`. (Voir [fournisseurs acceptés et droits d’accès](/docs/platform/core/reference/types/enqueue-files-options#modelprovider).)

### `timeout` [#timeout]

**Type** `number` · **Facultatif**

Délai d’expiration de la requête en millisecondes ; s’il n’est pas renseigné ou vaut `0`, la valeur de 60 000 ms est utilisée. Seuls les nombres sont acceptés, pas `false`. Ce paramètre est distinct de la [configuration du transport des requêtes](/docs/platform/core/reference/types/translation-config).

## Retourne [#returns]

**Type** `Promise<TranslationResult>`

Se résout en un [`TranslationResult`](/docs/platform/core/reference/types/translation-result) — une union discriminée composée d’un résultat de succès (avec `translation` et `locale`) et d’un résultat d’erreur (avec `error` et `code`). Vérifiez toujours `success` avant de lire la traduction.

La traduction à l’exécution ne relance pas les requêtes après un échec de transport, y compris en cas de `429`. Les échecs liés à la configuration, à l’authentification, à HTTP, au réseau, à l’annulation ou au délai d’expiration peuvent rejeter l’appel dans son ensemble au lieu d’être résolus comme un échec d’élément. Les résultats conservent le paramètre régional du service et ne rétablissent pas les alias configurés. (Voir [Erreurs](/docs/platform/core/reference/api-client#types-errors).)

## Exemples [#examples]

```typescript
// Traduction de chaîne simple (paramètre régional abrégé)
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
// Avec un objet d’options et un paramètre régional source explicite
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```

```typescript
// Avec métadonnées source (pluriel ICU + contexte)
const result = await gt.translate(
  {
    source: '{count, plural, other {{count} items}}',
    metadata: { dataFormat: 'ICU', context: 'Item count display' },
  },
  { targetLocale: 'es' }
);
```

```typescript
// Traduire un document Markdown complet.
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.