# General Translation Platform: Client API URL: https://generaltranslation.com/it/docs/platform/core/reference/api-client.mdx Docs index: https://generaltranslation.com/llms.txt Description: Crea un client tipizzato per la General Translation API e richiama gli helper degli endpoint generati. Riferimento API per createApiClient. Importa il client TypeScript da `generaltranslation/api` quando ti serve un controllo a livello di endpoint senza dover costruire manualmente le richieste HTTP. Il modulo combina un livello di trasporto autenticato, versionato e con ritentativi automatici con gli helper degli endpoint generati e con utilità opt-in per il batch e il polling dei job di traduzione. `generaltranslation/api` è disponibile in `generaltranslation` 9.2.0 e versioni successive. Gli esempi seguenti fanno riferimento a `generaltranslation` 9.4.0 e all'equivalente package autonomo `@generaltranslation/api` 0.3.0. Gli helper generati seguono lo snapshot OpenAPI incluso nel package installato. Tale snapshot può differire dall'attuale [contratto OpenAPI pubblico](/docs/platform/openapi/overview) ospitato, quindi consulta il riferimento pubblico per verificare quali endpoint e formati di file sono attivi. ## Overview [#overview] | Export | Description | | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [`createApiClient`](#create-client) | Crea un client autenticato con gestione di versione, retry e timeout. | | [`ApiClientConfig`](#client-config) | Configura il trasporto del client e gli header di richiesta condivisi. | | [`API_VERSION`](#api-version) | Versione corrente del contratto API inviata per impostazione predefinita. | | [helper degli endpoint](#endpoint-helpers) | Funzioni tipizzate generate per ogni operazione dello snapshot OpenAPI incluso. | | [`awaitJobs`](#job-polling) e [`pollJobs`](#job-polling) | Eseguono il polling dei translation job fino al completamento o allo scadere del timeout. | | [`processBatches`](#batch-processing) e [`DEFAULT_BATCH_SIZE`](#batch-processing) | Elaborano un array di input in batch configurabili. | | [Generated types](#types-errors) | Descrivono dati degli endpoint, risposte, errori e contratti del client. | | [Bundled specifica OpenAPI](#openapi-spec) | Snapshot JSON utilizzato per generare il package installato. | ## `createApiClient` [#create-client] ```ts function createApiClient(config: ApiClientConfig): Client; ``` Il client aggiunge la versione dell'API configurata, il bearer token e l'ID progetto a ogni richiesta. Passalo a un helper degli endpoint generato: ```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); ``` Gli esempi che seguono riutilizzano questo `client` configurato. ## `ApiClientConfig` [#client-config] | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------- | ----------- | ------------------ | | [`apiKey`](#apikey) | Chiave API o token di accesso utente OAuth inviato nell'header `Authorization`. | `string` | Sì | — | | [`apiVersion`](#apiversion) | Versione del contratto inviata come `gt-api-version`. | `ApiVersion` | Sì | `API_VERSION` | | [`baseUrl`](#baseurl) | Origine dell'API. | `string` | No | — | | [`fetch`](#fetch) | Implementazione personalizzata della Fetch API. | `typeof fetch` | Sì | `globalThis.fetch` | | [`projectId`](#projectid) | ID progetto inviato come `gt-project-id`. | `string` | Sì | — | | [`retryPolicy`](#retrypolicy) | Strategia di ritardo tra i tentativi. | `'exponential' \| 'linear' \| 'none'` | Sì | `'exponential'` | | [`timeoutMs`](#timeoutms) | Timeout per singolo tentativo, oppure `false` per disattivare il timeout integrato. | `number \| false` | Sì | `60000` | ### `apiKey` **Type** `string` · **Facoltativo** Chiave API o token di accesso utente OAuth 2.1 inviato come `Authorization: Bearer `. Il client non legge automaticamente le variabili d'ambiente. ### `apiVersion` **Type** `ApiVersion` · **Facoltativo** · **Default** `API_VERSION` Versione del contratto API inviata nell'header `gt-api-version`. ### `baseUrl` **Type** `string` · **Required** Origine dell'API. Usa `https://api.gtx.dev` per la General Translation API in hosting. ### `fetch` **Type** `typeof fetch` · **Facoltativo** · **Default** `globalThis.fetch` Implementazione personalizzata della Fetch API. Utilizzala per strumentazione, test o per un runtime privo di un'implementazione globale di fetch. ### `projectId` **Type** `string` · **Facoltativo** ID progetto inviato nell'header `gt-project-id`. Le chiavi di organizzazione e i token di accesso utente OAuth richiedono questo header per gli endpoint con scope di progetto che non includono l'ID progetto nel percorso. ### `retryPolicy` **Type** `'exponential' | 'linear' | 'none'` · **Facoltativo** · **Default** `'exponential'` Le request idempotenti vengono ritentate in caso di errori di rete, risposte `429` e risposte `5xx`, fino a tre volte. Le request non idempotenti vengono ritentate in caso di risposte `429`, ma non per errori di rete o risposte `5xx`. Imposta questo valore su `'none'` quando i tentativi sono gestiti dal chiamante. ### `timeoutMs` **Type** `number | false` · **Optional** · **Default** `60000` Timeout in millisecondi per ogni tentativo di request. Impostalo su `false` quando la gestione dei timeout delle request è affidata a un'implementazione personalizzata di `fetch`. ## `API_VERSION` [#api-version] **Type** `ApiVersion` L'attuale versione predefinita del contratto è `2026-03-06.v1`. Specifica una diversa versione supportata tramite `apiVersion` se mantieni un'integrazione basata su un contratto di risposta precedente. ## Helper degli endpoint [#endpoint-helpers] Gli helper generati accettano un oggetto contenente il `client` condiviso e, ove applicabili, i field `body`, `headers`, `path` e `query` dell'endpoint. Per impostazione predefinita restituiscono `{ 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); ``` Le opzioni generate più comuni includono: | Option | Description | Type | facoltativo | Default | | --------------- | --------------------------------------------------------------------------------------- | --------------------------- | ----------- | ---------- | | `client` | Client restituito da `createApiClient`. | `Client` | No | — | | `body` | Corpo della richiesta JSON tipizzato. | Specifico dell'endpoint | Variabile | — | | `path` | Parametri di percorso tipizzati. | Specifico dell'endpoint | Variabile | — | | `query` | Parametri di query tipizzati. | Specifico dell'endpoint | Variabile | — | | `headers` | Header per singola riuscita che sovrascrivono gli header condivisi del client. | Specifico dell'endpoint | Sì | — | | `throwOnError` | Solleva un'eccezione in caso di risposta non riuscita invece di restituire `error`. | `boolean` | Sì | `false` | | `responseStyle` | Restituisce tutti i campi della risposta oppure solo i dati analizzati. | `'fields' \| 'data'` | Sì | `'fields'` | | `signal` | Annulla la richiesta con un segnale della Fetch API. | `AbortSignal` | Sì | — | | `meta` | Valori esposti alle integrazioni client personalizzate. | `Record` | Sì | — | L'SDK 0.3.0 installato fornisce helper generati per queste operazioni pubbliche: | Function | Operation | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | [`createProject`](/docs/platform/openapi/reference/project/create-project) | Crea un progetto in un'Organization selezionata. | | [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) | Crea una chiave API del progetto con le autorizzazioni delegate dal chiamante. | | [`uploadSourceFiles`](/docs/platform/openapi/reference/files/upload-source) | Carica i file sorgente. | | [`uploadTranslations`](/docs/platform/openapi/reference/files/upload-translations) | Carica i file tradotti collegati ai file sorgente esistenti. | | `uploadAssets` | Carica le risorse del progetto. | | `submitUserEditDiffs` | Invia le modifiche di traduzione locali. | | `generateProjectContext` | Genera il contesto del progetto. | | `enqueueFileTranslations` | Accoda i file caricati per la traduzione. | | `publishFiles` | Pubblica o annulla la pubblicazione dei file. | | [`downloadFile`](/docs/platform/openapi/reference/files/download) | Scarica un singolo file. | | `downloadFiles` | Scarica più file. | | `getBranchInfo` | Legge le informazioni sul branch. | | `createBranch` | Crea un branch. | | [`createTag`](/docs/platform/openapi/reference/project/upsert-tag) | Crea o aggiorna un tag. | | `getProjectInfo` | Legge le informazioni sul progetto. | | `updateProjectInfo` | Aggiorna le informazioni sul progetto. | | `getTranslationJobInfo` | Legge lo stato di un job di traduzione. | | [`translate`](/docs/platform/openapi/reference/translation/translate-runtime) | Traduce contenuti a runtime. | | `getFileInfo` | Legge i metadati del file. | | `getTranslationStatus` | Legge lo stato di traduzione di un file. | | `processFileMoves` | Sposta o rinomina i file. | | `getOrphanedFiles` | Trova i file orfani. | **Modificato nella v0.3.0:** `encodeBase64`, `decodeBase64`, `encodeFileContent` e `decodeFileContent` non vengono più esportati. Codifica il contenuto del file prima di passarlo a un helper di caricamento generato. **Modificato nella v0.2.1:** [`createProject`](/docs/platform/openapi/reference/project/create-project) ora richiede `path.orgId` e chiama `POST /v2/orgs/{orgId}/projects`. Questa versione ha inoltre aggiunto [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) e rimosso `shouldGenerateProjectContext` e `getProjectContextGenerationStatus`. Usa `generateProjectContext` insieme a `getTranslationJobInfo` per i job di contesto. L'helper [`downloadFile`](/docs/platform/openapi/reference/files/download) resta deprecato; usa `downloadFiles` per i download in batch e di singoli file. Consulta il [riferimento OpenAPI pubblico](/docs/platform/openapi/overview) per autorizzazioni degli endpoint, rate limit, schemi e codici di stato aggiornati. ## Polling dei job [#job-polling] [`awaitJobs`](#job-polling) utilizza un client configurato per chiamare `getTranslationJobInfo` finché tutti i job richiesti non risultano completati, falliti, sconosciuti o mancanti, oppure finché non scade il timeout complessivo. ```ts function awaitJobs( client: Client, jobIds: readonly string[], options?: AwaitJobsOptions ): Promise; ``` | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ------------------------ | ---------------------------------------- | -------- | ----------- | ----------- | | `pollingIntervalSeconds` | Intervallo tra le richieste di stato. | `number` | Sì | `5` | | `timeoutSeconds` | Limite di tempo complessivo del polling. | `number` | Sì | `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` contiene `complete`, che è `false` solo quando il polling va in timeout, e `jobs`, che contiene il risultato più recente per ogni ID richiesto. A un job mancante viene assegnato lo status `unknown`. Passando un array vuoto, la promise si risolve immediatamente con `{ complete: true, jobs: [] }`. Un errore dell'API o dello status loader prima della scadenza complessiva provoca il rifiuto della promise di polling. Se la request fallisce dopo che la scadenza è trascorsa, il polling restituisce i risultati più recenti con `complete: false`. `pollJobs` espone lo stesso ciclo di polling con uno status loader iniettato: ```ts function pollJobs( jobIds: readonly string[], getJobStatuses: GetJobStatuses, options?: AwaitJobsOptions ): Promise; type GetJobStatuses = ( jobIds: string[], signal: AbortSignal ) => Promise; ``` Usalo quando hai bisogno di una normalizzazione personalizzata delle richieste o degli errori. Il loader riceve un segnale di interruzione limitato dalla scadenza complessiva rimanente e da un limite di 60 secondi per ogni polling. ## Elaborazione in batch [#batch-processing] `processBatches` suddivide un array di input in blocchi, richiama il processor per ogni blocco e appiattisce gli array restituiti nell'ordine dei batch. ```ts function processBatches( items: readonly TInput[], processBatch: (batch: TInput[]) => Promise, options?: BatchOptions ): Promise; ``` | Option | Description | Type | facoltativo | Default | | ----------- | ---------------------------------------------------------------------------- | --------- | ----------- | -------------------- | | `batchSize` | Numero di valori di input in ogni batch. Fornire un valore maggiore di zero. | `number` | Sì | `DEFAULT_BATCH_SIZE` | | `parallel` | Elabora tutti i batch in parallelo anziché in sequenza. | `boolean` | Sì | `true` | `DEFAULT_BATCH_SIZE` è `100`. Se un processore di batch va in reject, anche `processBatches` va in reject. Con l'elaborazione parallela, gli altri batch già avviati proseguono in modo indipendente. ```ts import { Buffer } from 'node:buffer'; import { processBatches, uploadSourceFiles, } from 'generaltranslation/api'; // Gli helper degli endpoint generati si aspettano il contenuto del file codificato per il trasporto. 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; }); ``` ## Tipi ed errori [#types-errors] Il modulo esporta `Client`, `Options`, `ApiClientConfig`, `ApiVersion`, `RetryPolicy`, `AwaitJobsOptions`, `AwaitJobsResult`, `GetJobStatuses`, `JobResult`, `BatchOptions`, `RuntimeFileFormat` e i tipi OpenAPI generati per le operazioni pubbliche elencate sopra. Per ogni operazione pubblica elencata sopra, il package esporta: * `Data` per l'input tipizzato di body, header, path e query. * `Errors` per la mappa per codice di stato degli errori documentati. * `Error` per l'unione degli errori documentati. * `Responses` per la mappa per codice di stato delle risposte di successo documentate. * `Response` per l'unione delle risposte di successo documentate. Con il valore predefinito `throwOnError: false`, un'operazione generata restituisce `data` oppure `error`, insieme alla `request` della Fetch API. Una risposta HTTP include `response`; se l'operazione fallisce prima di ricevere una risposta, tale valore resta undefined. Con `throwOnError: true`, gli errori di API, rete, annullamento e timeout vengono lanciati come eccezioni. ## Specifica OpenAPI [#openapi-spec] Importa lo snapshot utilizzato per generare il client installato: ```ts import openApiSpec from 'generaltranslation/api/openapi.json' with { type: 'json', }; ``` Il package autonomo `@generaltranslation/api` espone lo stesso SDK e pubblica il proprio snapshot in `@generaltranslation/api/spec/openapi.json`. Il comando [`gt api --spec`](/docs/cli/reference/commands/api) stampa lo snapshot incluso nella dipendenza Core installata di quella CLI. Per il contratto attualmente ospitato, usa [`/openapi.json`](/openapi.json). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.