# General Translation Platform: Client API URL: https://generaltranslation.com/fr/docs/platform/core/reference/api-client.mdx Docs index: https://generaltranslation.com/llms.txt Description: Créez un client typé pour l'API de General Translation et appelez les utilitaires d'endpoint générés. Référence API de createApiClient. Importez le client TypeScript depuis `generaltranslation/api` lorsque vous avez besoin d'un contrôle au niveau des endpoints sans construire vous-même les requêtes HTTP. Le module associe un transport authentifié, versionné et doté de relances automatiques à des utilitaires d'endpoint générés, ainsi qu'à des outils opt-in pour le traitement par lots et l'interrogation des tâches de traduction. `generaltranslation/api` est disponible dans `generaltranslation` 9.2.0 et versions ultérieures. Les exemples ci-dessous ciblent `generaltranslation` 9.4.0 et le paquet standalone équivalent `@generaltranslation/api` 0.3.0. Les utilitaires générés suivent l'instantané OpenAPI fourni avec le paquet installé. Cet instantané peut différer du [contrat OpenAPI public](/docs/platform/openapi/overview) actuellement hébergé : consultez donc la référence publique pour vérifier quels endpoints et formats de fichiers sont actifs. ## Aperçu [#overview] | Export | Description | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | [`createApiClient`](#create-client) | Crée un client authentifié avec gestion de la version, des nouvelles tentatives et du délai d’expiration. | | [`ApiClientConfig`](#client-config) | Configure le transport du client et les en-têtes de requête partagés. | | [`API_VERSION`](#api-version) | Version actuelle du contrat d’API envoyée par défaut. | | [Utilitaires d’endpoint](#endpoint-helpers) | Fonctions typées générées pour chaque opération de l’instantané OpenAPI intégré. | | [`awaitJobs`](#job-polling) et [`pollJobs`](#job-polling) | Interrogent les tâches de traduction jusqu’à leur achèvement ou l’expiration du délai. | | [`processBatches`](#batch-processing) et [`DEFAULT_BATCH_SIZE`](#batch-processing) | Traitent un tableau d’entrée par lots configurables. | | [Types générés](#types-errors) | Décrivent les données des endpoints, les réponses, les erreurs et les contrats du client. | | [Spécification OpenAPI intégrée](#openapi-spec) | Instantané JSON utilisé pour générer le paquet installé. | ## `createApiClient` [#create-client] ```ts function createApiClient(config: ApiClientConfig): Client; ``` Le client ajoute la version d'API configurée, le token bearer et l'ID du projet à chaque requête. Transmettez-le à un utilitaire d'endpoint généré : ```ts title="project-info.ts" import { createApiClient, getProjectInfo } from 'generaltranslation/api'; const projectId = process.env.GT_PROJECT_ID!; const client = createApiClient({ apiKey: process.env.GT_API_KEY, baseUrl: 'https://api.gtx.dev', projectId, }); const result = await getProjectInfo({ client, path: { projectId }, }); if (result.error) { throw new Error('Could not load Project information'); } console.log(result.data); ``` Les exemples ci-dessous réutilisent ce `client` configuré. ## `ApiClientConfig` [#client-config] | Option | Description | Type | Facultatif | Valeur par défaut | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------- | ---------- | ------------------ | | [`apiKey`](#apikey) | Clé API ou jeton d’accès personnel OAuth envoyé dans l’en-tête `Authorization`. | `string` | Oui | — | | [`apiVersion`](#apiversion) | Version du contrat envoyée via `gt-api-version`. | `ApiVersion` | Oui | `API_VERSION` | | [`baseUrl`](#baseurl) | Origine de l’API. | `string` | Non | — | | [`fetch`](#fetch) | Implémentation personnalisée de l’API Fetch. | `typeof fetch` | Oui | `globalThis.fetch` | | [`projectId`](#projectid) | ID du projet envoyé via `gt-project-id`. | `string` | Oui | — | | [`retryPolicy`](#retrypolicy) | Stratégie de délai entre les tentatives. | `'exponential' \| 'linear' \| 'none'` | Oui | `'exponential'` | | [`timeoutMs`](#timeoutms) | Délai d’expiration par tentative, ou `false` pour désactiver le délai d’expiration intégré. | `number \| false` | Oui | `60000` | ### `apiKey` **Type** `string` · **facultatif** Clé API ou jeton d'accès personnel utilisateur OAuth 2.1 envoyé sous la forme `Authorization: Bearer `. Le client ne lit pas automatiquement les variables d'environnement. ### `apiVersion` **Type** `ApiVersion` · **Facultatif** · **Default** `API_VERSION` Version du contrat d'API envoyée dans le header `gt-api-version`. ### `baseUrl` **Type** `string` · **Requis** Origine de l'API. Utilisez `https://api.gtx.dev` pour l'API de General Translation hébergée. ### `fetch` **Type** `typeof fetch` · **Facultatif** · **Default** `globalThis.fetch` Implémentation personnalisée de l'API Fetch. À utiliser pour l'instrumentation, les tests ou un environnement d'exécution dépourvu d'implémentation globale de fetch. ### `projectId` **Type** `string` · **Facultatif** ID du projet envoyé dans le en-tête `gt-project-id`. Les clés d'organisation et les jetons d'accès personnel utilisateur OAuth nécessitent ce en-tête pour les endpoints au niveau projet qui ne contiennent pas l'ID du projet dans le chemin. ### `retryPolicy` **Type** `'exponential' | 'linear' | 'none'` · **Facultatif** · **Default** `'exponential'` Les requêtes idempotentes sont réessayées jusqu'à trois fois en cas d'erreur réseau, de réponse `429` ou de réponse `5xx`. Les requêtes non idempotentes ne sont réessayées que pour les réponses `429`, mais pas en cas d'erreur réseau ni de réponse `5xx`. Définissez cette valeur sur `'none'` lorsque l'appelant gère lui-même les nouvelles tentatives. ### `timeoutMs` **Type** `number | false` · **Facultatif** · **Default** `60000` Délai d'expiration en millisecondes pour chaque tentative de requête. Définissez-le sur `false` lorsqu'une implémentation `fetch` personnalisée gère elle-même les délais d'expiration des requêtes. ## `API_VERSION` [#api-version] **Type** `ApiVersion` La version de contrat par défaut actuelle est `2026-03-06.v1`. Indiquez une autre version prise en charge via `apiVersion` si vous maintenez une integration basée sur un contrat de réponse plus ancien. ## Utilitaires d'endpoint [#endpoint-helpers] Les utilitaires générés acceptent un seul objet contenant le `client` partagé ainsi que les champs `body`, `headers`, `path` et `query` de l'endpoint, le cas échéant. Par défaut, ils renvoient `{ data, error, request, response }`. ```ts title="project-info.ts" import { getProjectInfo } from 'generaltranslation/api'; const result = await getProjectInfo({ client, path: { projectId: 'your-project-id' }, throwOnError: true, }); console.log(result.data.name); ``` Les options générées les plus courantes sont : | Option | Description | Type | Facultatif | Valeur par défaut | | --------------- | --------------------------------------------------------------------------- | --------------------------- | ---------- | ----------------- | | `client` | Client renvoyé par `createApiClient`. | `Client` | Non | — | | `body` | Corps de requête JSON typé. | Spécifique à l'endpoint | Variable | — | | `path` | Paramètres de chemin typés. | Spécifique à l'endpoint | Variable | — | | `query` | Paramètres de requête typés. | Spécifique à l'endpoint | Variable | — | | `headers` | En-têtes propres à l'appel, qui remplacent ceux du client partagé. | Spécifique à l'endpoint | Oui | — | | `throwOnError` | Lever une exception en cas de réponse en échec au lieu de renvoyer `error`. | `boolean` | Oui | `false` | | `responseStyle` | Renvoyer tous les champs de la réponse ou uniquement les données analysées. | `'fields' \| 'data'` | Oui | `'fields'` | | `signal` | Annuler la requête à l'aide d'un signal de l'API Fetch. | `AbortSignal` | Oui | — | | `meta` | Valeurs exposées aux intégrations client personnalisées. | `Record` | Oui | — | Le SDK 0.3.0 installé fournit des utilitaires générés pour les opérations publiques suivantes : | Fonction | Opération | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | [`createProject`](/docs/platform/openapi/reference/project/create-project) | Créer un projet dans une organisation sélectionnée. | | [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) | Créer une clé API de projet dont les permissions sont déléguées par l'appelant. | | [`uploadSourceFiles`](/docs/platform/openapi/reference/files/upload-source) | Téléverser des fichiers sources. | | [`uploadTranslations`](/docs/platform/openapi/reference/files/upload-translations) | Téléverser des fichiers traduits liés à des fichiers sources existants. | | `uploadAssets` | Téléverser les assets du projet. | | `submitUserEditDiffs` | Soumettre les modifications locales de traduction. | | `generateProjectContext` | Générer le contexte du projet. | | `enqueueFileTranslations` | Mettre en file d'attente des fichiers téléversés pour traduction. | | `publishFiles` | Publier ou dépublier des fichiers. | | [`downloadFile`](/docs/platform/openapi/reference/files/download) | Télécharger un fichier. | | `downloadFiles` | Télécharger plusieurs fichiers. | | `getBranchInfo` | Lire les informations d'une branche. | | `createBranch` | Créer une branche. | | [`createTag`](/docs/platform/openapi/reference/project/upsert-tag) | Créer ou mettre à jour un tag. | | `getProjectInfo` | Lire les informations du projet. | | `updateProjectInfo` | Mettre à jour les informations du projet. | | `getTranslationJobInfo` | Lire l'état d'une tâche de traduction. | | [`translate`](/docs/platform/openapi/reference/translation/translate-runtime) | Traduire du contenu à l'exécution. | | `getFileInfo` | Lire les métadonnées d'un fichier. | | `getTranslationStatus` | Lire l'état de traduction d'un fichier. | | `processFileMoves` | Déplacer ou renommer des fichiers. | | `getOrphanedFiles` | Repérer les fichiers orphelins. | **Modifié en v0.3.0 :** `encodeBase64`, `decodeBase64`, `encodeFileContent` et `decodeFileContent` ne sont plus exportés. Encodez le contenu du fichier avant de le transmettre à un utilitaire de téléversement généré. **Modifié en v0.2.1 :** [`createProject`](/docs/platform/openapi/reference/project/create-project) requiert désormais `path.orgId` et appelle `POST /v2/orgs/{orgId}/projects`. Cette version ajoute également [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) et supprime `shouldGenerateProjectContext` et `getProjectContextGenerationStatus`. Utilisez `generateProjectContext` avec `getTranslationJobInfo` pour les tâches de contexte. L'utilitaire [`downloadFile`](/docs/platform/openapi/reference/files/download) reste déprécié ; utilisez `downloadFiles` pour les téléchargements par lot comme pour les fichiers uniques. Consultez la [référence OpenAPI publique](/docs/platform/openapi/overview) pour connaître en temps réel les permissions, limites de débit, schémas et codes d'état des endpoints. ## Interrogation des tâches [#job-polling] [`awaitJobs`](#job-polling) utilise un client configuré pour appeler `getTranslationJobInfo` jusqu'à ce que chaque tâche demandée soit terminée, en échec, inconnue ou manquante, ou jusqu'à l'expiration du délai global. ```ts function awaitJobs( client: Client, jobIds: readonly string[], options?: AwaitJobsOptions ): Promise; ``` | Option | Description | Type | Facultatif | Valeur par défaut | | ------------------------ | -------------------------------------------------- | -------- | ---------- | ----------------- | | `pollingIntervalSeconds` | Délai entre les requêtes d'état. | `number` | Oui | `5` | | `timeoutSeconds` | Délai d'expiration global d'interrogation. | `number` | Oui | `600` | ```ts import { awaitJobs, enqueueFileTranslations, } from 'generaltranslation/api'; const result = await enqueueFileTranslations({ client, body: { files: [{ fileId: 'homepage', versionId: 'version-1' }], sourceLocale: 'en', targetLocales: ['es'], }, throwOnError: true, }); if (!('jobData' in result.data)) { throw new Error('Expected the current enqueue response'); } const jobs = await awaitJobs(client, Object.keys(result.data.jobData)); if (!jobs.complete) { console.warn('Translation jobs did not finish before the timeout'); } ``` `AwaitJobsResult` contient `complete`, qui vaut `false` uniquement lorsque l'interrogation expire, et `jobs`, qui contient le dernier résultat pour chaque ID demandé. Une tâche manquante reçoit l'état `unknown`. Passer un tableau vide résout immédiatement avec `{ complete: true, jobs: [] }`. Une erreur de l'API ou du status loader survenant avant l'échéance globale rejette la promesse d'interrogation. Si la requête échoue une fois l'échéance dépassée, l'interrogation renvoie les derniers résultats avec `complete: false`. `pollJobs` expose la même boucle d'interrogation avec un status loader injecté : ```ts function pollJobs( jobIds: readonly string[], getJobStatuses: GetJobStatuses, options?: AwaitJobsOptions ): Promise; type GetJobStatuses = ( jobIds: string[], signal: AbortSignal ) => Promise; ``` Utilisez-le lorsque vous avez besoin d'une normalisation personnalisée des requêtes ou des erreurs. Le loader reçoit un signal d'abandon plafonné par le délai global restant et par une limite de 60 secondes par interrogation. ## Traitement par lots [#batch-processing] `processBatches` découpe un tableau d'entrée en blocs, appelle votre processeur pour chaque bloc, puis aplatit les tableaux renvoyés en respectant l'ordre des lots. ```ts function processBatches( items: readonly TInput[], processBatch: (batch: TInput[]) => Promise, options?: BatchOptions ): Promise; ``` | Option | Description | Type | Facultatif | Valeur par défaut | | ----------- | ---------------------------------------------------------------------------------------- | --------- | ---------- | -------------------- | | `batchSize` | Nombre de valeurs d'entrée dans chaque lot. Fournissez une valeur supérieure à zéro. | `number` | Oui | `DEFAULT_BATCH_SIZE` | | `parallel` | Traite tous les lots simultanément plutôt que séquentiellement. | `boolean` | Oui | `true` | `DEFAULT_BATCH_SIZE` vaut `100`. Si un processeur de lot échoue, `processBatches` échoue également. En traitement parallèle, les autres lots déjà démarrés se poursuivent indépendamment. ```ts import { Buffer } from 'node:buffer'; import { processBatches, uploadSourceFiles, } from 'generaltranslation/api'; // Les utilitaires d'endpoint générés attendent un contenu de fichier encodé pour le transport. const content = Buffer.from('{"greeting":"Hello"}', 'utf8').toString('base64'); const files = [{ source: { content, fileName: 'en.json', fileFormat: 'JSON' as const, locale: 'en', }, }]; const results = await processBatches(files, async (batch) => { const result = await uploadSourceFiles({ client, body: { data: batch }, throwOnError: true, }); return result.data.uploadedFiles; }); ``` ## Types et erreurs [#types-errors] Le module exporte `Client`, `Options`, `ApiClientConfig`, `ApiVersion`, `RetryPolicy`, `AwaitJobsOptions`, `AwaitJobsResult`, `GetJobStatuses`, `JobResult`, `BatchOptions`, `RuntimeFileFormat`, ainsi que les types OpenAPI générés pour les opérations publiques listées ci-dessus. Pour chaque opération publique listée ci-dessus, le paquet exporte : * `Data` pour les entrées typées de body, headers, path et query. * `Errors` pour la table des erreurs documentées par code d’état. * `Error` pour l’union des erreurs documentées. * `Responses` pour la table des réponses réussies documentées par code d’état. * `Response` pour l’union des réponses réussies documentées. Avec la valeur par défaut `throwOnError: false`, une opération générée renvoie soit `data`, soit `error`, accompagné de la `request` de l’API Fetch. Une réponse HTTP inclut `response` ; si l’échec survient avant la réception d’une réponse, cette valeur reste indéfinie. Avec `throwOnError: true`, les échecs d’API, de réseau, d’annulation et de délai d’expiration lèvent une exception. ## Spécification OpenAPI [#openapi-spec] Importez l'instantané utilisé pour générer le client installé : ```ts import openApiSpec from 'generaltranslation/api/openapi.json' with { type: 'json', }; ``` Le paquet standalone `@generaltranslation/api` expose le même SDK et publie son instantané à l'adresse `@generaltranslation/api/spec/openapi.json`. La commande [`gt api --spec`](/docs/cli/reference/commands/api) affiche l'instantané fourni avec la dépendance Core installée de ce CLI. Pour le contrat hébergé actuel, utilisez [`/openapi.json`](/openapi.json). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.