# General Translation Integrations: Программный API
URL: https://generaltranslation.com/ru/docs/integrations/payload/reference/api.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Вызывайте gt-payload из серверного кода и изучайте экспортируемые типы результатов и компоненты админ-панели. Справочник API по экспортам gt-payload.

Корневой пакет экспортирует функции перевода на стороне сервера и их типы. Подпути `gt-payload/client` и `gt-payload/rsc` предоставляют компоненты, которые [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) регистрирует в админ-панели Payload.

## Экспорты [#exports]

| Экспорт                                                                    | Точка входа         | Описание                                                             |
| -------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------- |
| [`translateDocument`](#translate-document)                                 | `gt-payload`        | Переводит один документ коллекции или глобальный объект.             |
| [`translateSite`](#translate-site)                                         | `gt-payload`        | Переводит все поддерживаемые документы и глобальные объекты.         |
| [`saveTranslations`](#save-translations)                                   | `gt-payload`        | Сохраняет значения текущей локали для одного объекта.                |
| [`saveSiteTranslations`](#save-site-translations)                          | `gt-payload`        | Сохраняет значения текущей локали для всего сайта.                   |
| [`gtPlugin`](#plugin)                                                      | `gt-payload`        | Добавляет рабочий процесс в админку через конфигурацию Payload.      |
| [`GtDocumentControls`](#admin-components)                                  | `gt-payload/client` | Элемент управления переводом на уровне документа.                    |
| [`GtNavLink`](#admin-components)                                           | `gt-payload/client` | Ссылка на общее для всего сайта представление «Переводы».            |
| [`GtRunsProvider`](#admin-components)                                      | `gt-payload/client` | Возобновляет незавершённые запуски перевода.                         |
| [`GtTranslationsClient`](#admin-components)                                | `gt-payload/client` | Клиентское содержимое представления «Переводы».                      |
| [`GtTranslationsView`](#admin-components)                                  | `gt-payload/rsc`    | Серверное представление, зарегистрированное по пути `/translations`. |
| [`GtPluginOptions`](#gtpluginoptions)                                      | `gt-payload`        | Параметры, принимаемые `gtPlugin`.                                   |
| [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload`        | Вход для операций с одним документом.                      |
| [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput)     | `gt-payload`        | Вход для операций на уровне всего сайта.                   |
| [`TranslateTarget`](#translatetarget)                                      | `gt-payload`        | Идентификатор документа коллекции или глобального объекта.           |
| [`TranslateResult`](#translateresult-and-localeresult)                     | `gt-payload`        | Результат перевода для одного объекта.                               |
| [`LocaleResult`](#translateresult-and-localeresult)                        | `gt-payload`        | Результат для одной целевой локали.                                  |
| [`SkippedReason`](#skippedstring-and-skippedreason)                        | `gt-payload`        | Причина, по которой строка не была записана.                         |
| [`SkippedString`](#skippedstring-and-skippedreason)                        | `gt-payload`        | Пропущенный key и причина пропуска.                                  |
| [`SiteResult`](#siteresult-and-documentresult)                             | `gt-payload`        | Результат перевода на уровне всего сайта.                            |
| [`DocumentResult`](#siteresult-and-documentresult)                         | `gt-payload`        | Объект перевода вместе с его результатом.                            |
| [`SaveTranslationsResult`](#savetranslationsresult)                        | `gt-payload`        | Результат сохранения локальных правок.                               |
| [`GtClient`](#gtclient)                                                    | `gt-payload`        | Методы General Translation, необходимые плагину.                     |

## `translateDocument` [#translate-document]

**Вход** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Возвращаемое значение** `Promise<TranslateResult>`

Загружает один документ коллекции или глобальный объект (global), ожидает завершения его заданий до одного часа и записывает завершённые переводы в 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'],
});
```

При ожидаемых ошибках, связанных с документом, разрешениями, заданием или переводом, результат сообщает о сбое, а не выбрасывает исключение. Однако вызовы Payload или клиента всё равно могут вернуть отклонённый промис, если сбой произойдёт в непредвиденной операции.

## `translateSite` [#translate-site]

**Вход** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Возвращаемое значение** `Promise<SiteResult>`

Получает список всех документов коллекций и глобальных объектов с переводимыми локализованными полями, а затем переводит их одним пакетом. Документы без переведённых локалей и без ошибок не включаются в `documents`.

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

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

## `saveTranslations` [#save-translations]

**Вход** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Возвращаемое значение** `Promise<SaveTranslationsResult>`

Отправляет в General Translation текущие значения локалей Payload для одного целевого объекта, не добавляя в очередь новые задачи перевода. Если исходный документ ещё неизвестен General Translation, функция сначала загружает его на сервер.

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

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

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

**Вход** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Возвращаемое значение** `Promise<{ documents: DocumentResult<SaveTranslationsResult>[] }>`

Вызывает рабочий процесс сохранения локальных правок для каждой цели, которую охватывает [`translateSite`](#translate-site).

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

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

## `gtPlugin` [#plugin]

**Тип** `(options?: GtPluginOptions) => Plugin`

Возвращает плагин Payload. Все параметры и побочные эффекты описаны в разделе [Конфигурация плагина Payload](/docs/integrations/payload/reference/plugin-configuration).

## Типы входа [#input-types]

### `GtPluginOptions`

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

### `TranslateDocumentInput` и `TranslateSiteInput`

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

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

| Свойство         | Описание                                                                                                             | Тип                                   | Необязательно | По умолчанию                           |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------- | -------------------------------------- |
| `payload`        | Инициализированный экземпляр Payload.                                                                                | `Payload`                             | Нет           | —                                      |
| `gt`             | Клиент для загрузки на сервер, заданий, скачивания и более коротких повторных попыток.                               | [`GtClient`](#gtclient)               | Нет           | —                                      |
| `target`         | Документ коллекции или глобальный объект. Только для операций с документами.                                         | [`TranslateTarget`](#translatetarget) | Нет           | —                                      |
| `locales`        | Коды локалей Payload для обработки. Исходная локаль и дубликаты исключаются.                                         | `string[]`                            | Нет           | —                                      |
| `saveLocalEdits` | Сохранять известные правки локалей перед переводом, а правки, которые невозможно отправить, оставлять без изменений. | `boolean`                             | Да            | `false`                                |
| `user`           | Пользователь Payload, к операциям чтения и записи которого применяются правила доступа.                              | `TypedUser \| null`                   | Да            | Поведение серверного Local API Payload |

### `TranslateTarget`

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

ID в коллекции уникальны только в её пределах, поэтому идентификатор файла General Translation образуют оба значения вместе. Для глобального объекта используется его слаг.

## Типы результатов [#result-types]

### `TranslateResult` и `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` описывает сбой на уровне целевого объекта. `usageLimitReached` присутствует, только если General Translation отклоняет задачу со статусом `402`.

`applied` содержит стабильные ключи полей, записанные в Payload. `skipped` поясняет, почему переводимые строки не были записаны.

### `SkippedString` и `SkippedReason`

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

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

| Причина         | Значение                                                                              |
| --------------- | ------------------------------------------------------------------------------------- |
| `removed`       | Исходная строка, блок или поле больше не существует.                                  |
| `broken_markup` | Не удалось безопасно восстановить полученный форматированный текст или ссылки.        |
| `missing`       | Для исходного key не вернулось переведённое значение.                                 |
| `unsaved_edit`  | Не удалось отправить правку в Payload, поэтому `saveLocalEdits` сохранил её локально. |

### `SiteResult` и `DocumentResult`

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

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

`DocumentResult` хранит частично успешные и неудачные результаты, привязывая их к соответствующему документу коллекции или глобальному объекту.

### `SaveTranslationsResult`

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

`unsaved` — количество строк, которые плагину не удалось отправить, так как их ссылки отличаются от ссылок в исходном документе.

### `GtClient`

`GtClient` — это подмножество класса `GT` из `generaltranslation`, которое использует плагин:

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

В production используйте экземпляр `GT`. Более узкий тип также позволяет подставлять тестовые дублёры.

## Компоненты админ-панели [#admin-components]

Плагин регистрирует следующие экспорты по путям в import map:

| Компонент              | Точка входа         | Назначение                                                                           |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------ |
| `GtDocumentControls`   | `gt-payload/client` | Добавляет кнопку **Translate** и выдвижную панель в документ или глобальный объект.  |
| `GtNavLink`            | `gt-payload/client` | Добавляет навигационную ссылку **Переводы**.                                     |
| `GtRunsProvider`       | `gt-payload/client` | Находит незавершённые запуски и продвигает их выполнение, пока открыта админ-панель. |
| `GtTranslationsClient` | `gt-payload/client` | Отображает элементы управления на уровне всего сайта и таблицу покрытия.             |
| `GtTranslationsView`   | `gt-payload/rsc`    | Оборачивает клиентское представление в шаблон админ-панели Payload.                  |

Не регистрируйте эти компоненты по отдельности — вместо этого добавьте [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration). Они экспортируются только для того, чтобы сгенерированная Payload import map могла разрешить конфигурацию плагина.

## Sitemap

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