# generaltranslation: General Translation Core SDK: translate
URL: https://generaltranslation.com/fr/docs/core/class/methods/translation/translate.mdx
---
title: translate
description: Référence API de la méthode translate de GT
---

## Vue d’ensemble

La méthode `translate` est la principale fonction de traduction de la bibliothèque GT.
Elle traduit le contenu du paramètre régional source vers un paramètre régional cible spécifié, à l’aide de services de traduction s’appuyant sur l’IA.

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

const result = await gt.translate('Hello, world!', 'es');
console.log(result); // "¡Hola, mundo!"
```

La méthode prend en charge plusieurs types de contenu, notamment le texte brut, le format de message ICU et les messages de type i18next, avec des métadonnées facultatives pour améliorer la qualité de la traduction.

<Callout>
  **Authentification requise :**
  La méthode `translate` exige que `apiKey` (ou `devApiKey`) ainsi que `projectId` soient configurés dans l’instance GT.
</Callout>

***


## Référence

### Paramètres

<TypeTable
  type={{
  "source": {
    type: 'TranslateManyEntry',
    description: 'Le contenu à traduire. Peut être une simple chaîne de caractères ou un objet contenant la source et des métadonnées.',
    optional: false,
  },
  "options": {
    type: 'string | TranslateOptions',
    description: "Chaîne de caractères du paramètre régional cible (forme abrégée) ou objet d'options avec targetLocale et d'autres réglages.",
    optional: false,
  },
  "timeout?": {
    type: 'number',
    description: 'Délai d’expiration facultatif de la requête, en millisecondes.',
    optional: true,
  }
}}
/>

### TranslateManyEntry

Le paramètre `source` accepte soit une chaîne de caractères, soit un objet :

```typescript
type TranslateManyEntry = string | { source: Content; metadata?: EntryMetadata };
```


### TranslateOptions

Le paramètre `options` peut être une chaîne de caractères représentant un paramètre régional (forme abrégée de `targetLocale`) ou un objet :

```typescript
type TranslateOptions = {
  targetLocale: string;
  sourceLocale?: string;
  modelProvider?: string;
};
```


### Description des paramètres

| Paramètre | Description                                                                                                                                                                  |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`  | Le contenu à traduire. Une simple chaîne de caractères ou un objet avec `source` (Content) et, éventuellement, `metadata` (EntryMetadata).                                   |
| `options` | Une chaîne de caractères indiquant le paramètre régional cible (par exemple, `'es'`) ou un objet d’options avec `targetLocale`, `sourceLocale` en option et `modelProvider`. |
| `timeout` | Délai d’expiration facultatif de la requête, en millisecondes.                                                                                                               |

### Valeur de retour

```typescript
Promise<TranslationResult | TranslationError>
```

* **TranslationResult** : Contient le contenu traduit et ses métadonnées
* **TranslationError** : Contient les informations sur l’erreur en cas d’échec de la traduction

***


## Fonctionnement

### Détection du type de contenu

La méthode détecte automatiquement le type de contenu à partir du paramètre `source` :

* **String** : considéré comme du texte brut ou comme un message au format ICU
* **JSX Elements** : traités comme du contenu JSX de type React
* **Objects** : traités comme des formats de message structurés

### Détermination du paramètre régional

* Le paramètre régional cible est validé conformément à la norme BCP-47
* Les correspondances de paramètres régionaux personnalisées sont appliquées si elles sont configurées
* Les codes de langue des paramètres régionaux standard sont utilisés pour les requêtes API

### Forme abrégée des options

Vous pouvez passer une chaîne de caractères au paramètre `options` comme forme abrégée de `{ targetLocale: string }` :

```typescript
// Ces deux formes sont équivalentes :
await gt.translate('Hello', 'es');
await gt.translate('Hello', { targetLocale: 'es' });
```

***


## Exemples

### Traduction simple d’une chaîne de caractères

```typescript
const result = await gt.translate('Welcome to our application', 'fr');
```


### Avec un objet d’options

```typescript
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```


### Avec les métadonnées de la source

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


### Avec délai d’attente

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

***


## Remarques

* Traduit une chaîne de caractères donnée vers un paramètre régional cible et renvoie une promesse
* Utilise `translateMany` en interne avec une seule entrée

## Étapes suivantes

* **[Traduire plusieurs éléments avec translateMany](/docs/core/class/methods/translation/translate-many)**
* **[Découvrir les options de EntryMetadata](/docs/core/types/entry-metadata)**
* **[Explorer le type TranslationResult](/docs/core/types/translation-result)**