# General Translation Integrations: MCP-инструменты Google Drive
URL: https://generaltranslation.com/ru/docs/integrations/google-drive/reference/mcp-tools.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Переводите Google Docs, Google Sheets и Google Slides через размещённый MCP-сервер с аутентификацией. Справочник по MCP-инструментам Google Drive.

Размещённый сервер по адресу `https://api.gtx.dev/mcp` предоставляет три инструмента: для поиска подключённых проектов, запуска переводов и отслеживания их выполнения. Эти инструменты используют те же подключения к Google Drive и те же переведённые копии, что и интеграция в Dashboard, и поддерживают Google Docs, Google Sheets и Google Slides.

## Обзор [#overview]

| Инструмент                                             | Описание                                                                                  | Разрешение                                             |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [Аутентификация и доступ](#access)                     | Выбор учётных данных и режима подключения к Google Drive.                                 | —                                                      |
| [`get_google_drive_context`](#drive-context)           | Выводит список доступных подключённых проектов и разрешает необязательный контекст файла. | `project:files:read`                                   |
| [`translate_google_drive_file`](#translate-drive-file) | Синхронизирует и переводит один файл Google Docs, Google Sheets или Google Slides.        | `project:files:write` и `project:translations:enqueue` |
| [`get_google_drive_translation_status`](#drive-status) | Возвращает ход перевода, ход компоновки и URL переведённых копий.                            | `project:files:read`                                   |

## Аутентификация и доступ [#access]

Подключитесь к [размещённому MCP-серверу](/docs/overview/for-coding-agents#mcp) через OAuth или с помощью поддерживаемого API-ключа:

* **OAuth:** инструменты могут использовать привязанный личный Google account или подключение проекта к Organization shared drive. Устаревшее личное подключение с доступом только `drive.file` позволяет обращаться к файлам, выбранным в Dashboard, но прежде чем инструмент сможет перевести другой файл, такое подключение нужно создать заново с полным доступом к Drive.
* **API-ключ проекта:** ключ должен включать разрешения, необходимые инструменту, а проект — использовать подключение к Organization shared drive.
* **Organization API-ключ:** ключ должен включать разрешения, необходимые инструменту, и быть привязан к проекту, который использует подключение к Organization shared drive.
* **Locadex:** проект должен использовать подключение к Organization shared drive.

При вызове с API-ключом использовать личный Google account для доступа к Drive нельзя. Организации требуется функция интеграций с проектами, а для доступа к Organization shared drive нужна ещё и отдельная функция уровня Enterprise. Оба режима подключения настраиваются согласно [справочнику по подключениям](/docs/integrations/google-drive/reference/connection).

Вызовы MCP и API проверяют разрешение, указанное для каждого инструмента. Действия с файлами в Dashboard требуют `project:files:write` и `project:translations:enqueue`, при этом страница дополнительно проверяет `translations:content:write`, прежде чем показать элементы управления для личной учётной записи.

## `get_google_drive_context` [#drive-context]

**Только чтение** · **Разрешение** `project:files:read`

Вызывайте этот инструмент первым: он возвращает список проектов, доступных текущим учётным данным, вместе с их ID проекта и настройками локалей. С его помощью также можно определить source и контекст локали для файла в Google Drive.

### Входные параметры

| Название  | Описание                                                                    | Тип                              | Необязательный | По умолчанию |
| --------- | --------------------------------------------------------------------------- | -------------------------------- | -------------- | ------------ |
| `fileId`  | ID файла Google Drive из URL документа Docs, Sheets или Slides после `/d/`. | `string`                         | Да             | —            |
| `hostApp` | Редактор Google, которому принадлежит файл.                                 | `'DOCS' \| 'SLIDES' \| 'SHEETS'` | Да             | —            |

Не указывайте ни один из параметров, чтобы получить список подключённых проектов. Укажите оба, чтобы просмотреть исходный файл или его переведённую копию, управляемую интеграцией.

### Возвращаемое значение

Результат включает:

* `user.email` — может быть `null` и не указывает, подключён ли личный аккаунт Google.
* Поддерживаемые локали.
* Доступные проекты с их идентификаторами, названиями, исходными локалями по умолчанию, текущими локалями, списками разрешённых локалей и статусом интеграции.
* Контекст исходной и целевой локали, если запрошенный файл связан или является управляемой переведённой копией.

Проекты, режим подключения которых недоступен вызывающей стороне, не включаются.

## `translate_google_drive_file` [#translate-drive-file]

**Изменяющий** · **Разрешения** `project:files:write` и `project:translations:enqueue`

Синхронизирует один файл Google Docs, Google Sheets или Google Slides, импортирует правки из существующих переведённых копий, ставит задачи на перевод в очередь и применяет готовые переводы к управляемым копиям.

### Входные параметры

| Название        | Описание                                                                                                                     | Тип                              | Необязательный | По умолчанию                                       |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------- | -------------------------------------------------- |
| `projectId`     | ID проекта, возвращаемый `get_google_drive_context`.                                                                         | `string`                         | Нет            | —                                                  |
| `fileId`        | ID файла Google Drive из URL документа Docs, Sheets или Slides после `/d/`.                                                  | `string`                         | Нет            | —                                                  |
| `hostApp`       | Редактор Google, которому принадлежит файл.                                                                                  | `'DOCS' \| 'SLIDES' \| 'SHEETS'` | Нет            | —                                                  |
| `targetLocales` | От 1 до 100 поддерживаемых кодов локалей. Если в проекте задан список разрешённых локалей, каждый код должен входить в него. | `string[]`                       | Нет            | —                                                  |
| `sourceLocale`  | Исходная локаль. Если не указана, используется сохранённая локаль файла, а затем локаль проекта по умолчанию.                | `string`                         | Да             | Сохранённая локаль или локаль проекта по умолчанию |
| `force`         | Переводит существующее содержимое заново, а не использует его повторно.                                                      | `boolean`                        | Да             | `false`                                            |

Если `fileId` указывает на управляемую переведённую копию, инструмент разрешает её исходный оригинал и использует только целевую локаль этой копии. Исходная локаль оригинала также переопределяет `sourceLocale`.

Инструмент отбрасывает целевой код, который в точности совпадает с разрешённым источником. Запрос завершается ошибкой ещё до постановки в очередь, если не осталось ни одного целевого кода или если какой-либо целевой код является более общим или более частным кодом языка-источника, например `en` и `en-GB`. Чтобы переводить между вариантами языка, используйте два кода, различающихся регионом или письменностью, например `en-US` и `en-GB`.

### Возвращаемое значение

Результат содержит `accepted`, разрешённые `sourceLocale` и `targetLocales`, счётчики в `enqueued` и `failed`, а также массив `errors`. Проверяйте все три поля с результатами, поскольку одна целевая локаль может завершиться ошибкой, тогда как остальные будут поставлены в очередь.

Ошибка валидации локали приводит к сбою всего запроса — вместо этого результата.

Этот инструмент может расходовать кредиты на перевод и обновлять существующие переведённые копии. Принудительный перевод может перезаписать переведённый текст и внесённые изменения в компоновке.

## `get_google_drive_translation_status` [#drive-status]

**Только чтение** · **Разрешение** `project:files:read`

Опрашивайте этот инструмент после `translate_google_drive_file`, чтобы отслеживать ход перевода и вёрстки для каждой запрошенной локали.

### Входные параметры

| Название    | Описание                                                                    | Тип                              | Необязательный | По умолчанию |
| ----------- | --------------------------------------------------------------------------- | -------------------------------- | -------------- | ------------ |
| `projectId` | ID проекта, возвращаемый `get_google_drive_context`.                        | `string`                         | Нет            | —            |
| `fileId`    | ID файла Google Drive из URL документа Docs, Sheets или Slides после `/d/`. | `string`                         | Нет            | —            |
| `hostApp`   | Редактор Google, которому принадлежит файл.                                 | `'DOCS' \| 'SLIDES' \| 'SHEETS'` | Нет            | —            |

### Возвращаемое значение

Каждый результат по локали содержит сведения о локали, допускающие `null` значения `translationProgress` и `layoutProgress`, а также логическое значение `done`. Этап компоновки есть только у Google Slides, поэтому для Google Docs и Google Sheets `layoutProgress` остаётся равным `null`. Как только управляемая копия становится доступна, в `targetCopy` появляются её идентификатор файла в Google Drive и URL, по которому она открывается в редакторе, указанном в `hostApp`.

Если `fileId` указывает на управляемую переведённую копию, инструмент разрешает её исходный файл и возвращает статус для целевой локали этой копии.

## Sitemap

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