# General Translation Platform: Cliente de API URL: https://generaltranslation.com/es/docs/platform/core/reference/api-client.mdx Docs index: https://generaltranslation.com/llms.txt Description: Crea un cliente tipado para la General Translation API y llama a los helpers de endpoints generados. Referencia de API para createApiClient. Importa el cliente de TypeScript desde `generaltranslation/api` cuando necesites control a nivel de endpoint sin tener que construir tú mismo las solicitudes HTTP. El módulo combina un transporte autenticado, versionado y con reintentos con helpers de endpoints generados y utilidades opt-in para batching y sondeo de trabajos de traducción. `generaltranslation/api` está disponible a partir de `generaltranslation` 9.2.0. Los ejemplos siguientes apuntan a `generaltranslation` 9.4.0 y al package standalone equivalente `@generaltranslation/api` 0.3.0. Los helpers generados siguen el snapshot de OpenAPI incluido en el package instalado. Ese snapshot puede diferir del [contrato público de OpenAPI](/docs/platform/openapi/overview) alojado actualmente, así que consulta la referencia pública para comprobar qué endpoints y formatos de archivo están activos. ## Descripción general [#overview] | Export | Descripción | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | [`createApiClient`](#create-client) | Crea un cliente autenticado con gestión de versión, reintentos y tiempo de espera. | | [`ApiClientConfig`](#client-config) | Configura el transporte del cliente y las cabeceras de solicitud compartidas. | | [`API_VERSION`](#api-version) | Versión actual del contrato de la API que se envía de forma predeterminada. | | [Helpers de endpoints](#endpoint-helpers) | Funciones tipadas generadas para cada operación del snapshot de OpenAPI incluido. | | [`awaitJobs`](#job-polling) y [`pollJobs`](#job-polling) | Sondean los trabajos de traducción hasta que finalizan o se agota el tiempo de espera. | | [`processBatches`](#batch-processing) y [`DEFAULT_BATCH_SIZE`](#batch-processing) | Procesan una lista de entrada en lotes configurables. | | [Tipos generados](#types-errors) | Describen los datos de los endpoints, las respuestas, los errores y los contratos del cliente. | | [Especificación OpenAPI incluida](#openapi-spec) | Snapshot en JSON usado para generar el package instalado. | ## `createApiClient` [#create-client] ```ts function createApiClient(config: ApiClientConfig): Client; ``` El cliente añade la versión de API configurada, el token Bearer y el ID del proyecto a cada solicitud. Pásalo a un helper de endpoint generado: ```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); ``` Los siguientes ejemplos reutilizan este `client` ya configurado. ## `ApiClientConfig` [#client-config] | Option | Descripción | tipo | Opcional | Predeterminado | | ----------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------- | -------- | ------------------ | | [`apiKey`](#apikey) | Clave de API o token de acceso de usuario OAuth enviado en la cabecera `Authorization`. | `string` | Sí | — | | [`apiVersion`](#apiversion) | Versión del contrato enviada como `gt-api-version`. | `ApiVersion` | Sí | `API_VERSION` | | [`baseUrl`](#baseurl) | Origen de la API. | `string` | No | — | | [`fetch`](#fetch) | Implementación personalizada de la Fetch API. | `typeof fetch` | Sí | `globalThis.fetch` | | [`projectId`](#projectid) | ID del Project enviado como `gt-project-id`. | `string` | Sí | — | | [`retryPolicy`](#retrypolicy) | Estrategia de retardo entre reintentos. | `'exponential' \| 'linear' \| 'none'` | Sí | `'exponential'` | | [`timeoutMs`](#timeoutms) | Tiempo de espera por intento, o `false` para desactivar el tiempo de espera integrado. | `number \| false` | Sí | `60000` | ### `apiKey` **Tipo** `string` · **Opcional** clave de API o token de acceso de usuario OAuth 2.1 que se envía como `Authorization: Bearer `. El cliente no lee las variables de entorno automáticamente. ### `apiVersion` **Type** `ApiVersion` · **Optional** · **Default** `API_VERSION` Versión del contrato de la API que se envía en la cabecera `gt-api-version`. ### `baseUrl` **Tipo** `string` · **Obligatorio** Origen de la API. Usa `https://api.gtx.dev` para la General Translation API alojada. ### `fetch` **Type** `typeof fetch` · **Opcional** · **Predeterminado** `globalThis.fetch` Implementación personalizada de la Fetch API. Úsala para instrumentación, pruebas o en un runtime que no cuente con una implementación global de fetch. ### `projectId` **tipo** `string` · **Opcional** ID del Project que se envía en la cabecera `gt-project-id`. Las Organization keys y los tokens de acceso de usuario OAuth requieren esta cabecera para los endpoints con alcance de Project que no incluyen el project ID en el path. ### `retryPolicy` **Tipo** `'exponential' | 'linear' | 'none'` · **Opcional** · **Predeterminado** `'exponential'` Las solicitudes idempotentes reintentan los errores de red, las respuestas `429` y las respuestas `5xx` hasta tres veces. Las solicitudes no idempotentes reintentan las respuestas `429`, pero no los errores de red ni las respuestas `5xx`. Establece este valor en `'none'` cuando quien realiza la llamada se encargue de los reintentos. ### `timeoutMs` **Type** `number | false` · **Opcional** · **Predeterminado** `60000` Tiempo de espera en milisegundos para cada intento de solicitud. Establécelo en `false` cuando una implementación personalizada de `fetch` gestione los tiempos de espera de las solicitudes. ## `API_VERSION` [#api-version] **Type** `ApiVersion` La versión de contrato predeterminada actual es `2026-03-06.v1`. Pasa otra versión compatible mediante `apiVersion` cuando mantengas una integration basada en un contrato de respuesta anterior. ## Helpers de endpoint [#endpoint-helpers] Los helpers generados aceptan un objeto con el `client` compartido más los campos `body`, `headers`, `path` y `query` del endpoint, según corresponda. De forma predeterminada, devuelven `{ 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); ``` Entre las opciones generadas más comunes se incluyen: | Option | Description | Type | Optional | Default | | --------------- | ---------------------------------------------------------------------------- | ------------------------- | -------- | ---------- | | `client` | Cliente devuelto por `createApiClient`. | `Client` | No | — | | `body` | Cuerpo tipado de la solicitud JSON. | Específico del endpoint | Varía | — | | `path` | Parámetros de ruta tipados. | Específico del endpoint | Varía | — | | `query` | Parámetros de consulta tipados. | Específico del endpoint | Varía | — | | `headers` | Cabeceras por llamada que reemplazan las cabeceras compartidas del cliente. | Específico del endpoint | Sí | — | | `throwOnError` | Lanza una excepción ante una respuesta fallida en lugar de devolver `error`. | `boolean` | Sí | `false` | | `responseStyle` | Devuelve todos los campos de la respuesta o solo los datos analizados. | `'fields' \| 'data'` | Sí | `'fields'` | | `signal` | Cancela la solicitud con una señal de la Fetch API. | `AbortSignal` | Sí | — | | `meta` | Valores expuestos a integraciones de cliente personalizadas. | `Record` | Sí | — | El SDK 0.3.0 instalado proporciona helpers generados para estas operaciones públicas: | Function | Operation | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | [`createProject`](/docs/platform/openapi/reference/project/create-project) | Crear un proyecto en una Organization seleccionada. | | [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) | Crear una clave de API de proyecto con los permisos delegados por quien llama. | | [`uploadSourceFiles`](/docs/platform/openapi/reference/files/upload-source) | Subir archivos fuente. | | [`uploadTranslations`](/docs/platform/openapi/reference/files/upload-translations) | Subir archivos traducidos vinculados a archivos fuente existentes. | | `uploadAssets` | Subir recursos del proyecto. | | `submitUserEditDiffs` | Enviar cambios de traducción locales. | | `generateProjectContext` | Generar el contexto del proyecto. | | `enqueueFileTranslations` | Poner en cola archivos subidos para su traducción. | | `publishFiles` | Publicar o dejar de publicar archivos. | | [`downloadFile`](/docs/platform/openapi/reference/files/download) | Descargar un archivo. | | `downloadFiles` | Descargar varios archivos. | | `getBranchInfo` | Leer la información de la rama. | | `createBranch` | Crear una rama. | | [`createTag`](/docs/platform/openapi/reference/project/upsert-tag) | Crear o actualizar una etiqueta. | | `getProjectInfo` | Leer la información del proyecto. | | `updateProjectInfo` | Actualizar la información del proyecto. | | `getTranslationJobInfo` | Leer el estado de un trabajo de traducción. | | [`translate`](/docs/platform/openapi/reference/translation/translate-runtime) | Traducir contenido en tiempo de ejecución. | | `getFileInfo` | Leer los metadatos de un archivo. | | `getTranslationStatus` | Leer el estado de traducción de un archivo. | | `processFileMoves` | Mover o renombrar archivos. | | `getOrphanedFiles` | Buscar archivos huérfanos. | **Cambios en la v0.3.0:** `encodeBase64`, `decodeBase64`, `encodeFileContent` y `decodeFileContent` ya no se exportan. Codifica el contenido del archivo antes de pasarlo a un helper de subida generado. **Cambios en la v0.2.1:** [`createProject`](/docs/platform/openapi/reference/project/create-project) ahora requiere `path.orgId` y llama a `POST /v2/orgs/{orgId}/projects`. Esta versión también añadió [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) y eliminó `shouldGenerateProjectContext` y `getProjectContextGenerationStatus`. Usa `generateProjectContext` junto con `getTranslationJobInfo` para los trabajos de contexto. El helper [`downloadFile`](/docs/platform/openapi/reference/files/download) sigue estando obsoleto; usa `downloadFiles` para descargas por lotes y de un solo archivo. Consulta la [referencia pública de OpenAPI](/docs/platform/openapi/overview) para conocer los permisos, límites de solicitudes, esquemas y códigos de estado vigentes de cada endpoint. ## Sondeo de trabajos [#job-polling] [`awaitJobs`](#job-polling) utiliza un cliente configurado para llamar a `getTranslationJobInfo` hasta que todos los trabajos solicitados se hayan completado, hayan fallado, sean desconocidos o no existan, o hasta que expire el tiempo de espera global. ```ts function awaitJobs( client: Client, jobIds: readonly string[], options?: AwaitJobsOptions ): Promise; ``` | Opción | Descripción | Tipo | Opcional | Predeterminado | | ------------------------ | -------------------------------------- | -------- | -------- | -------------- | | `pollingIntervalSeconds` | Intervalo entre solicitudes de estado. | `number` | Sí | `5` | | `timeoutSeconds` | Límite de tiempo total del sondeo. | `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`, que es `false` únicamente cuando el sondeo agota el tiempo de espera, y `jobs`, que contiene el último resultado de cada ID solicitado. Un trabajo que no exista recibe el estado `unknown`. Pasar una lista vacía se resuelve de inmediato con `{ complete: true, jobs: [] }`. Un error de la API o del cargador de estado antes del plazo límite general rechaza la promesa del sondeo. Si la solicitud falla una vez vencido el plazo, el sondeo devuelve los últimos resultados con `complete: false`. `pollJobs` expone el mismo bucle de sondeo con un cargador de estado inyectado: ```ts function pollJobs( jobIds: readonly string[], getJobStatuses: GetJobStatuses, options?: AwaitJobsOptions ): Promise; type GetJobStatuses = ( jobIds: string[], signal: AbortSignal ) => Promise; ``` Úsalo cuando necesites una normalización personalizada de solicitudes o errores. El loader recibe una señal de cancelación limitada por el tiempo restante del plazo global y por un límite de 60 segundos por sondeo. ## Procesamiento por lotes [#batch-processing] `processBatches` divide una lista de entrada en fragmentos, invoca tu procesador para cada fragmento y aplana las listas devueltas en el orden de los lotes. ```ts function processBatches( items: readonly TInput[], processBatch: (batch: TInput[]) => Promise, options?: BatchOptions ): Promise; ``` | Option | Description | Type | Optional | Default | | ----------- | -------------------------------------------------------------------------------- | --------- | -------- | -------------------- | | `batchSize` | Número de valores de entrada en cada batch. Proporciona un valor mayor que cero. | `number` | Sí | `DEFAULT_BATCH_SIZE` | | `parallel` | Procesa todos los batches de forma concurrente en lugar de secuencial. | `boolean` | Sí | `true` | `DEFAULT_BATCH_SIZE` es `100`. Si un procesador de batch es rechazado, `processBatches` también lo es. Con el procesamiento en paralelo, los demás batches que ya se habían iniciado continúan de forma independiente. ```ts import { Buffer } from 'node:buffer'; import { processBatches, uploadSourceFiles, } from 'generaltranslation/api'; // Los helpers de endpoint generados esperan que el contenido del archivo esté codificado para su transporte. 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; }); ``` ## Tipos y errores [#types-errors] El módulo exporta `Client`, `Options`, `ApiClientConfig`, `ApiVersion`, `RetryPolicy`, `AwaitJobsOptions`, `AwaitJobsResult`, `GetJobStatuses`, `JobResult`, `BatchOptions`, `RuntimeFileFormat` y los tipos de OpenAPI generados para las operaciones públicas indicadas arriba. Para cada operación pública indicada arriba, el paquete exporta: * `Data` para la entrada tipada de `body`, `headers`, `path` y `query`. * `Errors` para el mapa de códigos de estado de los errores documentados. * `Error` para la unión de los errores documentados. * `Responses` para el mapa de códigos de estado de las respuestas correctas documentadas. * `Response` para la unión de las respuestas correctas documentadas. Con el valor predeterminado `throwOnError: false`, una operación generada devuelve `data` o `error`, además del `request` de la Fetch API. Una respuesta HTTP incluye `response`; si se produce un fallo antes de recibir una respuesta, este queda como `undefined`. Con `throwOnError: true`, los fallos de la API, de red, de cancelación y de tiempo de espera lanzan una excepción. ## Especificación OpenAPI [#openapi-spec] Importa el snapshot que se usó para generar el cliente instalado: ```ts import openApiSpec from 'generaltranslation/api/openapi.json' with { type: 'json', }; ``` El package standalone `@generaltranslation/api` expone el mismo SDK y publica su snapshot en `@generaltranslation/api/spec/openapi.json`. El comando [`gt api --spec`](/docs/cli/reference/commands/api) imprime el snapshot incluido con la dependencia Core instalada de ese CLI. Para el contrato alojado actual, usa [`/openapi.json`](/openapi.json). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.