# General Translation Integrations: API programmatique
URL: https://generaltranslation.com/fr/docs/integrations/payload/reference/api.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Appelez gt-payload depuis du code serveur et consultez ses types de résultats exportés ainsi que ses composants d’administration. Référence de l’API pour les exports de gt-payload.

Le paquet racine exporte les fonctions de traduction côté serveur ainsi que leurs types. Les sous-chemins `gt-payload/client` et `gt-payload/rsc` exposent les composants que [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) enregistre dans le panneau d’administration de Payload.

## Exports [#exports]

| Export                                                                     | Point d’entrée      | Description                                                                      |
| -------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------- |
| [`translateDocument`](#translate-document)                                 | `gt-payload`        | Traduit un document de collection ou un global.                                  |
| [`translateSite`](#translate-site)                                         | `gt-payload`        | Traduit tous les documents et globals pris en charge.                            |
| [`saveTranslations`](#save-translations)                                   | `gt-payload`        | Enregistre les valeurs des paramètres régionaux actuels pour une cible.          |
| [`saveSiteTranslations`](#save-site-translations)                          | `gt-payload`        | Enregistre les valeurs des paramètres régionaux actuels pour l’ensemble du site. |
| [`gtPlugin`](#plugin)                                                      | `gt-payload`        | Ajoute le flux de travail d’administration à une configuration Payload.          |
| [`GtDocumentControls`](#admin-components)                                  | `gt-payload/client` | Commande de traduction document-level.                                           |
| [`GtNavLink`](#admin-components)                                           | `gt-payload/client` | Lien vers la vue Traductions site-wide.                                          |
| [`GtRunsProvider`](#admin-components)                                      | `gt-payload/client` | Reprend les exécutions de traduction en cours.                                   |
| [`GtTranslationsClient`](#admin-components)                                | `gt-payload/client` | Contenu client de la vue Traductions.                                            |
| [`GtTranslationsView`](#admin-components)                                  | `gt-payload/rsc`    | Vue serveur enregistrée sur `/translations`.                                     |
| [`GtPluginOptions`](#gtpluginoptions)                                      | `gt-payload`        | Options acceptées par `gtPlugin`.                                                |
| [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload`        | Entrée des opérations portant sur un seul document.                              |
| [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput)     | `gt-payload`        | Entrée des opérations site-wide.                                                 |
| [`TranslateTarget`](#translatetarget)                                      | `gt-payload`        | Identité d’un document de collection ou d’un global.                             |
| [`TranslateResult`](#translateresult-and-localeresult)                     | `gt-payload`        | Résultat de traduction pour une cible.                                           |
| [`LocaleResult`](#translateresult-and-localeresult)                        | `gt-payload`        | Résultat pour une locale cible.                                                  |
| [`SkippedReason`](#skippedstring-and-skippedreason)                        | `gt-payload`        | Raison pour laquelle une chaîne de caractères n’a pas été écrite.                |
| [`SkippedString`](#skippedstring-and-skippedreason)                        | `gt-payload`        | Clé ignorée et motif.                                                            |
| [`SiteResult`](#siteresult-and-documentresult)                             | `gt-payload`        | Résultat de traduction site-wide.                                                |
| [`DocumentResult`](#siteresult-and-documentresult)                         | `gt-payload`        | Cible associée à son résultat.                                                   |
| [`SaveTranslationsResult`](#savetranslationsresult)                        | `gt-payload`        | Résultat de l’enregistrement des modifications locales.                          |
| [`GtClient`](#gtclient)                                                    | `gt-payload`        | Méthodes General Translation requises par le plugin.                             |

## `translateDocument` [#translate-document]

**Entrée** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Valeurs de retour** `Promise<TranslateResult>`

Importe un document de collection ou un global, attend jusqu&#39;à une heure que ses tâches se terminent, puis écrit les traductions terminées dans Payload.

```ts
import { GT } from 'generaltranslation';
import { translateDocument } from 'gt-payload';

const result = await translateDocument({
  payload,
  gt: new GT({
    projectId: process.env.GT_PROJECT_ID,
    apiKey: process.env.GT_API_KEY,
    sourceLocale: payload.config.localization
      ? payload.config.localization.defaultLocale
      : undefined,
  }),
  target: { collection: 'pages', id: pageId },
  locales: ['es', 'fr'],
});
```

Le résultat signale les échecs au lieu de lever une exception pour les erreurs attendues liées au document, aux permissions, aux tâches et à la traduction. Les appels à Payload ou au client peuvent toutefois être rejetés en cas d&#39;échec d&#39;une opération inattendue.

## `translateSite` [#translate-site]

**Entrée** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Valeurs de retour** `Promise<SiteResult>`

Répertorie tous les documents de collection et tous les globals comportant des champs localisés traduisibles, puis les traduit en un seul lot. Les documents sans aucun paramètre régional traduit et sans erreur sont exclus de `documents`.

```ts
import { translateSite } from 'gt-payload';

const result = await translateSite({
  payload,
  gt,
  locales: ['es', 'fr'],
  user,
});
```

## `saveTranslations` [#save-translations]

**Entrée** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Valeurs de retour** `Promise<SaveTranslationsResult>`

Envoie à General Translation les valeurs actuelles des paramètres régionaux Payload pour une cible donnée, sans mettre en file d’attente de nouvelles tâches de traduction. Si General Translation ne connaît pas encore le document source, cette fonction l’importe au préalable.

```ts
import { saveTranslations } from 'gt-payload';

const result = await saveTranslations({
  payload,
  gt,
  target: { global: 'site-settings' },
  locales: ['es', 'fr'],
  user,
});
```

## `saveSiteTranslations` [#save-site-translations]

**Entrée** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Valeurs de retour** `Promise<{ documents: DocumentResult<SaveTranslationsResult>[] }>`

Appelle le flux de travail d’enregistrement des modifications locales pour chaque cible prise en charge par [`translateSite`](#translate-site).

```ts
import { saveSiteTranslations } from 'gt-payload';

const result = await saveSiteTranslations({
  payload,
  gt,
  locales: ['es', 'fr'],
  user,
});
```

## `gtPlugin` [#plugin]

**Type** `(options?: GtPluginOptions) => Plugin`

Renvoie un plugin Payload. Consultez [Configuration du plugin Payload](/docs/integrations/payload/reference/plugin-configuration) pour le détail de toutes les options et de leurs effets de bord.

## Types d&#39;entrée [#input-types]

### `GtPluginOptions`

```ts
type GtPluginOptions = {
  projectId?: string;
  apiKey?: string;
  customMapping?: CustomMapping;
  client?: GtClient;
};
```

### `TranslateDocumentInput` et `TranslateSiteInput`

```ts
type TranslateDocumentInput = {
  payload: Payload;
  gt: GtClient;
  target: TranslateTarget;
  locales: string[];
  saveLocalEdits?: boolean;
  user?: TypedUser | null;
};

type TranslateSiteInput = Omit<TranslateDocumentInput, 'target'>;
```

| Propriété        | Description                                                                                                                            | Type                                  | Facultatif | Valeur par défaut                                    |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------- | ---------------------------------------------------- |
| `payload`        | Instance Payload initialisée.                                                                                                          | `Payload`                             | Non        | —                                                    |
| `gt`             | Client utilisé pour les imports, les tâches, les téléchargements et les nouvelles tentatives à délai plus court.                       | [`GtClient`](#gtclient)               | Non        | —                                                    |
| `target`         | Document de collection ou global. Uniquement pour les opérations sur les documents.                                                    | [`TranslateTarget`](#translatetarget) | Non        | —                                                    |
| `locales`        | Codes de paramètres régionaux Payload à traiter. Les paramètres régionaux sources et les doublons sont ignorés.                        | `string[]`                            | Non        | —                                                    |
| `saveLocalEdits` | Enregistre les modifications connues des paramètres régionaux avant la traduction et préserve celles qui ne peuvent pas être envoyées. | `boolean`                             | Oui        | `false`                                              |
| `user`           | Utilisateur Payload dont les règles d’accès s’appliquent aux lectures et aux écritures.                                                | `TypedUser \| null`                   | Oui        | Comportement côté serveur de la Local API de Payload |

### `TranslateTarget`

```ts
type TranslateTarget =
  | { collection: string; id: string | number }
  | { global: string };
```

Les ID de collection ne sont uniques qu’au sein d’une collection ; ces deux valeurs constituent donc ensemble l’identité du fichier General Translation. Un global est identifié par son slug.

## Types de résultats [#result-types]

### `TranslateResult` et `LocaleResult`

```ts
type TranslateResult = {
  error?: string;
  usageLimitReached?: true;
  locales: Record<string, LocaleResult>;
};

type LocaleResult =
  | {
      status: 'applied';
      applied: string[];
      skipped: SkippedString[];
    }
  | {
      status: 'failed';
      error: string;
    };
```

`error` décrit un échec au niveau de la cible. `usageLimitReached` n&#39;est présent que lorsque General Translation refuse la tâche avec le code de statut `402`.

`applied` contient les clés de champ stables écrites dans Payload. `skipped` indique pourquoi certaines chaînes à traduire n&#39;ont pas été écrites.

### `SkippedString` et `SkippedReason`

```ts
type SkippedString = {
  key: string;
  reason: SkippedReason;
};

type SkippedReason =
  | 'removed'
  | 'broken_markup'
  | 'missing'
  | 'unsaved_edit';
```

| Raison          | Signification                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------- |
| `removed`       | La ligne, le bloc ou le champ source n&#39;existe plus.                                         |
| `broken_markup` | Le texte enrichi ou les liens renvoyés n&#39;ont pas pu être reconstruits sans risque.          |
| `missing`       | Aucune valeur traduite n&#39;a été renvoyée pour la clé source.                                 |
| `unsaved_edit`  | Une modification Payload n&#39;a pas pu être envoyée ; `saveLocalEdits` l&#39;a donc conservée. |

### `SiteResult` et `DocumentResult`

```ts
type DocumentResult<T> = {
  target: TranslateTarget;
  result: T;
};

type SiteResult = {
  error?: string;
  documents: DocumentResult<TranslateResult>[];
};
```

`DocumentResult` conserve les succès partiels et les échecs en les rattachant au document de collection ou au global auquel ils se rapportent.

### `SaveTranslationsResult`

```ts
type SaveTranslationsResult = {
  error?: string;
  locales: Record<
    string,
    | { status: 'saved'; unsaved?: number }
    | { status: 'no_translations'; unsaved?: number }
    | { status: 'failed'; error: string }
  >;
};
```

`unsaved` indique le nombre de chaînes que le plugin n&#39;a pas pu envoyer, car leurs liens diffèrent de ceux de la source.

### `GtClient`

`GtClient` est le sous-ensemble de la classe `GT` de `generaltranslation` utilisé par le plugin :

```ts
type GtClient = Pick<
  GT,
  | 'uploadSourceFiles'
  | 'enqueueFiles'
  | 'awaitJobs'
  | 'downloadFileBatch'
  | 'uploadTranslations'
  | 'checkJobStatus'
  | 'translateMany'
  | 'customMapping'
>;
```

Utilisez une instance `GT` en production. Le type plus restreint permet aussi d&#39;utiliser des doublures de test.

## Composants d’administration [#admin-components]

Le plugin enregistre ces exports selon leur chemin dans l’import map :

| Composant              | Point d’entrée      | Rôle                                                                                               |
| ---------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| `GtDocumentControls`   | `gt-payload/client` | Ajoute le bouton **Translate** et le tiroir associé à un document ou à un global.                  |
| `GtNavLink`            | `gt-payload/client` | Ajoute le lien de navigation **Traductions**.                                                     |
| `GtRunsProvider`       | `gt-payload/client` | Détecte et fait avancer les exécutions en attente tant que le panneau d’administration est ouvert. |
| `GtTranslationsClient` | `gt-payload/client` | Affiche les commandes site-wide et le tableau de couverture.                                       |
| `GtTranslationsView`   | `gt-payload/rsc`    | Encapsule la vue client dans le modèle d’administration de Payload.                                |

Ajoutez [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) plutôt que d’enregistrer ces composants un par un. S’ils sont exportés, c’est pour que l’import map générée par Payload puisse résoudre la configuration du plugin.

## Sitemap

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