# 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 Sheets 和 Google Slides。Google Drive MCP 工具的 API 参考。

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

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

* **OAuth：** 这些工具可以使用你已关联的个人 Google 账户，或项目的组织共享云端硬盘连接。仅具有 `drive.file` 权限的旧版个人连接只能访问在仪表板中选定的文件；若要让工具翻译其他文件，必须以完整的 Drive 访问权限重新连接。
* **项目 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、Sheets 或 Slides URL 中 `/d/` 之后的部分。 | `string`                         | 是  | —   |
| `hostApp` | 拥有该文件的 Google 编辑器。                                            | `'DOCS' \| 'SLIDES' \| 'SHEETS'` | 是  | —   |

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

### 返回值

结果包含：

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

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

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

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

同步单个 Google Docs、Google Sheets 或 Google Slides 文件，从已有的翻译后副本中导入修改内容，将翻译任务加入队列，并将已完成的翻译应用到受管副本。

### 输入

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

### 返回值

每个区域设置的结果包含其区域设置详情、可为空的 `translationProgress` 和 `layoutProgress` 值，以及一个 `done` 布尔值。只有 Google Slides 会进行布局处理，因此对于 Google Docs 和 Google Sheets，`layoutProgress` 始终为 `null`。托管副本一旦可用，`targetCopy` 中会包含其 Google Drive 文件 ID，以及一个可在 `hostApp` 所指定的编辑器中打开的 URL。

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

## Sitemap

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