# 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 un `apiKey` (ou `devApiKey`) et 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 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; // indication facultative du fournisseur de modèle
};
```

### `timeout` [#timeout]

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

Délai d’expiration de la requête en millisecondes. S’il n’est pas renseigné, la valeur par défaut de l’instance est utilisée.

## 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.

## 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.