# General Translation Integrations: API programática
URL: https://generaltranslation.com/es/docs/integrations/payload/reference/api.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Llama a gt-payload desde código de servidor e inspecciona los tipos de resultado y los componentes de administración que exporta. Referencia de la API para las exportaciones de gt-payload.

El paquete raíz exporta funciones de traducción del lado del servidor y sus tipos. Las subrutas `gt-payload/client` y `gt-payload/rsc` exponen los componentes que [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) registra en el panel de administración de Payload.

## Exportaciones [#exports]

| Exportación                                                                | Punto de entrada    | Descripción                                                                  |
| -------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------- |
| [`translateDocument`](#translate-document)                                 | `gt-payload`        | Traduce un documento de colección o un global.                               |
| [`translateSite`](#translate-site)                                         | `gt-payload`        | Traduce todos los documentos y globales admitidos.                           |
| [`saveTranslations`](#save-translations)                                   | `gt-payload`        | Guarda los valores de la configuración regional actual para un destino.      |
| [`saveSiteTranslations`](#save-site-translations)                          | `gt-payload`        | Guarda los valores de la configuración regional actual para todo el sitio.   |
| [`gtPlugin`](#plugin)                                                      | `gt-payload`        | Agrega el flujo de trabajo de administración a una configuración de Payload. |
| [`GtDocumentControls`](#admin-components)                                  | `gt-payload/client` | Control de traducción document-level.                                        |
| [`GtNavLink`](#admin-components)                                           | `gt-payload/client` | Enlace a la vista Traducciones de todo el sitio.                             |
| [`GtRunsProvider`](#admin-components)                                      | `gt-payload/client` | Reanuda las ejecuciones de traducción pendientes.                            |
| [`GtTranslationsClient`](#admin-components)                                | `gt-payload/client` | Contenido de cliente para la vista Traducciones.                             |
| [`GtTranslationsView`](#admin-components)                                  | `gt-payload/rsc`    | Vista de servidor registrada en `/translations`.                             |
| [`GtPluginOptions`](#gtpluginoptions)                                      | `gt-payload`        | Opciones que acepta `gtPlugin`.                                              |
| [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload`        | Entrada para operaciones sobre un solo documento.                            |
| [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput)     | `gt-payload`        | Entrada para operaciones en todo el sitio.                                   |
| [`TranslateTarget`](#translatetarget)                                      | `gt-payload`        | Identidad de un documento de colección o de un global.                       |
| [`TranslateResult`](#translateresult-and-localeresult)                     | `gt-payload`        | Resultado de traducción para un destino.                                     |
| [`LocaleResult`](#translateresult-and-localeresult)                        | `gt-payload`        | Resultado para una configuración regional de destino.                        |
| [`SkippedReason`](#skippedstring-and-skippedreason)                        | `gt-payload`        | Motivo por el que no se escribió una cadena.                                 |
| [`SkippedString`](#skippedstring-and-skippedreason)                        | `gt-payload`        | Clave omitida y su motivo.                                                   |
| [`SiteResult`](#siteresult-and-documentresult)                             | `gt-payload`        | Resultado de traducción de todo el sitio.                                    |
| [`DocumentResult`](#siteresult-and-documentresult)                         | `gt-payload`        | Destino junto con su resultado.                                              |
| [`SaveTranslationsResult`](#savetranslationsresult)                        | `gt-payload`        | Resultado de guardar cambios locales.                                  |
| [`GtClient`](#gtclient)                                                    | `gt-payload`        | Métodos de General Translation que requiere el plugin.                       |

## `translateDocument` [#translate-document]

**Entrada** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Devuelve** `Promise<TranslateResult>`

Carga un documento de colección o un global, espera hasta una hora a que finalicen sus trabajos y escribe las traducciones completadas en 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'],
});
```

El resultado informa de los fallos en lugar de lanzar excepciones ante errores esperados de documentos, permisos, trabajos y traducción. Las llamadas a Payload o al cliente aún pueden rechazar la promesa si falla una operación de forma inesperada.

## `translateSite` [#translate-site]

**Entrada** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Devuelve** `Promise<SiteResult>`

Enumera todos los documentos de colección y globales que tienen campos localizados traducibles y luego los traduce en un único lote. Los documentos sin configuraciones regionales traducidas y sin errores se omiten de `documents`.

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

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

## `saveTranslations` [#save-translations]

**Entrada** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Devuelve** `Promise<SaveTranslationsResult>`

Envía a General Translation los valores actuales de configuración regional de Payload para un destino, sin poner en cola nuevos trabajos de traducción. Si General Translation aún no conoce el documento de origen, esta función lo carga primero.

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

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

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

**Entrada** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Devuelve** `Promise<{ documents: DocumentResult<SaveTranslationsResult>[] }>`

Invoca el flujo de trabajo Guardar cambios locales para cada destino que abarca [`translateSite`](#translate-site).

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

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

## `gtPlugin` [#plugin]

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

Devuelve un plugin de Payload. Consulta la [configuración del plugin de Payload](/docs/integrations/payload/reference/plugin-configuration) para ver todas las opciones y sus efectos secundarios.

## Tipos de entrada [#input-types]

### `GtPluginOptions`

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

### `TranslateDocumentInput` y `TranslateSiteInput`

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

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

| Propiedad        | Descripción                                                                                                                            | Tipo                                  | Opcional | Predeterminado                                         |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------- | ------------------------------------------------------ |
| `payload`        | Instancia de Payload inicializada.                                                                                                     | `Payload`                             | No       | —                                                      |
| `gt`             | Cliente que se usa para cargas, trabajos, descargas y reintentos más cortos.                                                           | [`GtClient`](#gtclient)               | No       | —                                                      |
| `target`         | Documento de una colección o global. Solo para operaciones de documento.                                                               | [`TranslateTarget`](#translatetarget) | No       | —                                                      |
| `locales`        | Códigos de configuración regional de Payload que se van a procesar. Se descartan la configuración regional de origen y los duplicados. | `string[]`                            | No       | —                                                      |
| `saveLocalEdits` | Guarda las ediciones conocidas de cada configuración regional antes de traducir y conserva las ediciones que no se pueden enviar.      | `boolean`                             | Sí       | `false`                                                |
| `user`           | Usuario de Payload cuyas reglas de acceso se aplican a las lecturas y escrituras.                                                      | `TypedUser \| null`                   | Sí       | Comportamiento del servidor de la Local API de Payload |

### `TranslateTarget`

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

Los IDs de colección solo son únicos dentro de una colección, por lo que ambos valores forman la identidad del archivo en General Translation. Un global usa su slug.

## Tipos de resultado [#result-types]

### `TranslateResult` y `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` describe un fallo a nivel de destino. `usageLimitReached` solo aparece cuando General Translation rechaza el trabajo con el estado `402`.

`applied` contiene las claves de campo estables que se escribieron en Payload. `skipped` explica qué cadenas traducibles no se escribieron.

### `SkippedString` y `SkippedReason`

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

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

| Motivo          | Significado                                                                              |
| --------------- | ---------------------------------------------------------------------------------------- |
| `removed`       | La fila, el bloque o el campo de origen ya no existe.                                    |
| `broken_markup` | No se pudieron reconstruir de forma segura el texto enriquecido o los enlaces devueltos. |
| `missing`       | No se devolvió ningún valor traducido para la clave de origen.                           |
| `unsaved_edit`  | No se pudo enviar una edición de Payload, por lo que `saveLocalEdits` la conservó.       |

### `SiteResult` y `DocumentResult`

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

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

`DocumentResult` conserva los éxitos parciales y los errores asociados a su documento de colección o global.

### `SaveTranslationsResult`

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

`unsaved` cuenta las cadenas que el plugin no pudo enviar porque sus enlaces no coinciden con los del código fuente.

### `GtClient`

`GtClient` es el subconjunto de la clase `GT` de `generaltranslation` que utiliza el plugin:

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

Usa una instancia de `GT` en producción. El tipo más acotado también admite dobles de prueba.

## Componentes de administración [#admin-components]

El plugin registra estas exportaciones según su ruta en el import map:

| Componente             | Punto de entrada    | Función                                                                                                 |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------- |
| `GtDocumentControls`   | `gt-payload/client` | Añade el botón **Translate** y el panel lateral a un documento o global.                                |
| `GtNavLink`            | `gt-payload/client` | Añade el enlace de navegación **Traducciones**.                                                         |
| `GtRunsProvider`       | `gt-payload/client` | Detecta las ejecuciones pendientes y las hace avanzar mientras el panel de administración está abierto. |
| `GtTranslationsClient` | `gt-payload/client` | Renderiza los controles que se aplican en todo el sitio y la tabla de cobertura.                        |
| `GtTranslationsView`   | `gt-payload/rsc`    | Envuelve la vista de cliente en la plantilla de administración de Payload.                              |

Añade [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) en lugar de registrar estos componentes uno por uno. Se exportan para que el import map que genera Payload pueda resolver la configuración del plugin.

## Sitemap

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