# General Translation Integrations: Google Drive MCP 工具
URL: https://generaltranslation.com/zh/docs/integrations/google-drive/reference/mcp-tools.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 通过已认证的托管 MCP 服务器翻译 Google Docs 和 Google Slides。Google Drive MCP 工具的 API 参考。

位于 `https://api.gtx.dev/mcp` 的托管服务器提供三个工具，分别用于查找已连接的项目、启动翻译以及轮询翻译进度。这些工具与仪表板集成使用相同的 Google Drive 连接和翻译后副本。

## 概览 [#overview]

| 工具                                                     | 说明                                       | 权限                                                     |
| ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------ |
| [身份验证与访问](#access)                                     | 选择凭据和 Google Drive 连接模式。                 | —                                                      |
| [`get_google_drive_context`](#drive-context)           | 列出可访问的已连接项目，并解析可选的文件上下文。                 | `project:files:read`                                   |
| [`translate_google_drive_file`](#translate-drive-file) | 同步并翻译单个 Google Doc 或 Google Slides 演示文稿。 | `project:files:write` 和 `project:translations:enqueue` |
| [`get_google_drive_translation_status`](#drive-status) | 返回翻译进度、排版进度以及译文副本的 URL。                  | `project:files:read`                                   |

## 身份验证与访问 [#access]

使用 OAuth 或受支持的 API 密钥连接到[托管 MCP 服务器](/docs/overview/for-coding-agents#mcp)：

* **OAuth：** 这些工具可以使用你已关联的个人 Google 账户，或项目的组织共享云端硬盘连接。仅具有 `drive.file` 权限的旧版个人连接只能访问在仪表板中选定的文件；若要让工具翻译其他文件，必须以完整的 Drive 访问权限重新连接。
* **Production 或 development 项目 API 密钥：** 该密钥必须包含工具所需的权限，且项目必须使用组织共享云端硬盘连接。
* **组织 API 密钥：** 该密钥必须包含工具所需的权限，且所指向的项目使用组织共享云端硬盘连接。
* **Locadex：** 项目必须使用组织共享云端硬盘连接。

使用 API 密钥的调用方无法通过个人 Google 账户访问 Drive。组织需要启用项目集成功能，而组织共享云端硬盘访问还需单独启用其企业版功能。这两种连接模式均可在[连接参考](/docs/integrations/google-drive/reference/connection)中配置。

MCP 和 API 调用会强制校验各工具所列出的权限。仪表板中的文件操作需要 `project:files:write` 和 `project:translations:enqueue`，而该页面在显示个人账户相关控件前会单独检查 `translations:content:write`。

## `get_google_drive_context` [#drive-context]

**只读** · **权限** `project:files:read`

请先调用此工具，列出当前凭据可访问的项目，并获取其项目 ID 和区域设置。你还可以借此解析 Google Drive 文件的源语言与区域设置上下文。

### 输入

| 名称        | 说明                                                     | 类型                   | 可选 | 默认值 |
| --------- | ------------------------------------------------------ | -------------------- | -- | --- |
| `fileId`  | Google Drive 文件 ID，取自 Docs 或 Slides URL 中 `/d/` 之后的部分。 | `string`             | 是  | —   |
| `hostApp` | 拥有该文件的 Google 编辑器。                                     | `'DOCS' \| 'SLIDES'` | 是  | —   |

两个输入均省略时，将列出已连接的项目；两个输入均提供时，可查看该集成管理的源文件或翻译后的副本。

### Returns

结果包含：

* `linked` 与 `user.email`；成功响应目前返回 `linked: true`，`user.email` 则可能为 `null`。这两个字段都不表示是否已连接个人 Google 账户。
* 支持的区域设置。
* 可访问的项目及其 ID、名称、默认源区域设置、当前区域设置、区域设置允许列表和集成状态。
* 当请求的文件已关联，或为受管理的翻译后的副本时，还包含源区域设置与目标区域设置的上下文。

若调用方无法使用某个项目的连接模式，该项目将被省略。

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

**变更操作** · **权限** `project:files:write` 和 `project:translations:enqueue`

同步 Google Doc 文档或 Google Slides 演示文稿，从已有的翻译后副本中导入修改内容，将翻译任务加入队列，并将已完成的翻译应用到受管副本。

### Inputs

| 名称              | Description                                            | Type                 | Optional | Default        |
| --------------- | ------------------------------------------------------ | -------------------- | -------- | -------------- |
| `projectId`     | 由 `get_google_drive_context` 返回的项目 ID。                 | `string`             | 否        | —              |
| `fileId`        | Google Drive 文件 ID，取自 Docs 或 Slides URL 中 `/d/` 之后的部分。 | `string`             | 否        | —              |
| `hostApp`       | 该文件所属的 Google 编辑器。                                     | `'DOCS' \| 'SLIDES'` | 否        | —              |
| `targetLocales` | 1 至 100 个项目区域设置代码。                                     | `string[]`           | 否        | —              |
| `sourceLocale`  | 源区域设置。未指定时回退到已存储的文件区域设置，再回退到项目默认值。                     | `string`             | 是        | 已存储的区域设置或项目默认值 |
| `force`         | 重新翻译现有内容，而非复用。                                         | `boolean`            | 是        | `false`        |

当 `fileId` 指向受管理的翻译后的副本时，该工具会解析出其原始源文件，并仅使用该副本的目标区域设置；其原始源区域设置也会覆盖 `sourceLocale`。

### 返回值

结果包含 `accepted`、解析后的 `sourceLocale` 和 `targetLocales`、`enqueued` 与 `failed` 中的计数，以及一个 `errors` 数组。请检查全部三个结果字段，因为可能出现某个目标区域设置失败、而其他区域设置已进入队列的情况。

此工具可能会消耗翻译额度，并更新已有的翻译后副本。强制翻译可能会覆盖已翻译的文本以及版式改动。

## `get_google_drive_translation_status` [#drive-status]

**只读** · **权限** `project:files:read`

调用 `translate_google_drive_file` 之后轮询此工具，即可查看每个所请求区域设置的翻译与排版进度。

### 输入

| 名称          | 说明                                                     | 类型                   | 可选 | 默认值 |
| ----------- | ------------------------------------------------------ | -------------------- | -- | --- |
| `projectId` | 由 `get_google_drive_context` 返回的项目 ID。                 | `string`             | 否  | —   |
| `fileId`    | Google Drive 文件 ID，取自 Docs 或 Slides URL 中 `/d/` 之后的部分。 | `string`             | 否  | —   |
| `hostApp`   | 该文件所属的 Google 编辑器。                                     | `'DOCS' \| 'SLIDES'` | 否  | —   |

### 返回值

每个区域设置的结果包含其区域设置详情、可为空的 `translationProgress` 和 `layoutProgress` 值，以及一个 `done` 布尔值。托管副本一旦可用，`targetCopy` 中会包含其 Google Drive 文件 ID 和 URL。

当 `fileId` 指向某个受管理的翻译后的副本时，该工具会解析出其源文件，并返回该副本所对应目标区域设置的状态。

## Sitemap

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