在 BotBrowser 中使用 Google Translate 翻译网页

阅读其他语言的网页应当是普通的浏览器操作，也应当是一项明确的操作。网页翻译会把翻译所需的页面文本发送给外部服务，并消耗云项目配额。BotBrowser 支持这一流程，但凭据、账单、配额、网络和数据处理决定由你自己的 Google Cloud 项目管理。

这样做的结果很直接：打开网页，使用浏览器正常的翻译命令，然后查看翻译结果。更重要的控制也很明确：由你决定哪个项目承担请求和费用，哪个部署可以使用密钥，哪个 profile 承载会话，以及哪些内容允许发送到翻译服务。

网页翻译能做什么

当页面主要文本不是目标语言时，浏览器可以请求翻译并在当前会话中显示翻译后的文本。这适合支持工作、研究、内容运营、本地化检查以及获得授权的质量验证。

网页翻译是依赖外部服务的浏览器能力。页面可以暴露与翻译有关的浏览器行为，但完整服务仍可能不可用。这是两个不同的结果。能力检查只能说明浏览器理解该功能，不能证明云请求一定成功。真正可用还需要客户自己的有效密钥、已启用的服务、账单、可用配额、允许的网络路径，以及翻译服务能够处理的源页面。

因此应准确描述失败。若浏览器没有翻译命令，先检查页面语言和浏览器设置。若命令出现但结果没有返回，再检查项目、密钥限制、配额、代理和网络。不要把失败请求当成已翻译页面，也不要把可见的浏览器能力当成外部服务已连通的证明。

开始前的准备

• 与工作流匹配的 BotBrowser release 和 profile。
• 由组织拥有或管理的 Google Cloud 项目。
• 项目中已启用 Cloud Translation API。
• 按服务要求关联 billing 账户。
• 与预期页面和用户数量相符的 quota 策略。
• 仅允许 Cloud Translation API 和实际部署路径使用的 API key。
• 能够访问所需 Google 服务的网络路径。

测试时可以使用独立项目，以便分开管理支出和访问边界。独立项目也方便在测试密钥需要撤销时不影响其他工作负载。把 profile、user-data 策略、proxy 策略和启动方式视为一个部署单元，减少运行之间的隐含变化。

创建由客户管理的项目

在 Google Cloud Console 中创建或选择网页翻译项目，启用 Cloud Translation API，关联 billing，并查看当前的价格和 quota 说明。然后在 APIs & Services 和 Credentials 中创建 API key，将 API 限制设置为 Cloud Translation API，再添加与浏览器实际运行位置匹配的应用限制。稳定服务器出口可以使用 IP 限制，其他部署可能需要不同限制。选择能工作的最窄边界，并从真实浏览器路径测试。

不要把真实密钥粘贴到文章、源文件、profile、截图、终端录屏、提交的环境文件或共享日志中。本文只使用占位符。真实密钥应放在部署 secret store 中，或在受保护的交互式 shell 中提供给启动 BotBrowser 的进程。如果密钥泄露，应在 Google Cloud 中立即轮换或撤销。

BotBrowser 不提供共享翻译密钥。由客户管理项目可以自行控制费用、配额、访问审查、保留策略和事件响应，同时也意味着 Google Cloud 服务状态和账户配置属于部署方责任。

在浏览器进程中启动

环境变量必须在 BotBrowser 进程启动时存在，并且要与正常的 profile 和 user-data 参数一起设置：

GOOGLE_API_KEY='YOUR_API_KEY' \
chromium-browser \
  --bot-profile='/absolute/path/to/profile.enc' \
  --user-data-dir='/absolute/path/to/user-data' \
  about:blank

这里的值是不可用的占位符，只能在受保护的本地或部署环境中替换。更改变量后要重启 BotBrowser。仅更改外层 HTTP client、页面脚本或之后的子进程，不能建立浏览器进程所需的配置。

macOS 和 Linux 可以在启动浏览器的同一个 shell 中导出变量：

export GOOGLE_API_KEY='YOUR_API_KEY'
chromium-browser \
  --bot-profile='/absolute/path/to/profile.enc' \
  --user-data-dir='/absolute/path/to/user-data'

Windows PowerShell 应在启动前设置进程环境：

$env:GOOGLE_API_KEY = 'YOUR_API_KEY'
& 'C:\path\to\chromium.exe' `
  '--bot-profile=C:\path\to\profile.enc' `
  '--user-data-dir=C:\path\to\user-data'

使用 Playwright 或 Puppeteer 时，由启动浏览器的进程负责环境变量。让受保护的值通过启动边界传入，并把 profile 参数保留在浏览器启动处。不要把密钥放进页面 JavaScript，也不要让网站代码读取它。不要提交真实 .env 文件。

保持 profile 一致

翻译不是混用浏览器身份或状态策略的理由。导航前加载目标 profile，并明确 user-data 目录策略。需要延续正常会话历史时使用持久目录，需要全新站点关系时使用新目录。不要让无关身份或团队共用一个持久目录。

让 profile、浏览器 release、主机环境和网络路径描述同一个一致的会话。如果 profile 面向特定浏览器或平台上下文，就在翻译检查期间保持这些选择一致。启动输入不一致会让结果难以复现，也可能把意外状态暴露给页面。

在多 profile 工作流中，必须在会话开始前分配匹配的 profile，并在会话期间保持身份相关设置稳定。参考 Per-Context Fingerprint 文档 了解当前设置顺序。翻译应在已经定义好的会话中运行，而不是导航后再改变会话。

一致性不仅帮助翻译成功，也让页面可见的浏览器系列、语言偏好、存储状态和网络策略更容易解释。profile 是浏览器行为和连续性的控制，不是访问许可，也不会覆盖网站访问规则。

验证完整的用户可见流程

使用部署相同的 release、profile、proxy、启动方式和目标语言：

1. 确认配置密钥后已重启浏览器进程。
2. 打开主要文本不是目标语言的页面。
3. 从浏览器菜单或右键菜单使用正常的页面翻译命令。
4. 确认页面文本发生可见变化且结果可读。
5. 在 Google Cloud 项目中查看预期请求用量。
6. 记录 profile、网络路径、源语言、目标语言和结果，不记录页面内容或密钥。

同时测试应该翻译和应该保持原样的页面。对表单、账户信息、客户记录或用户生成文本，例行验证应使用安全的代表性页面，除非数据策略明确批准发送这些内容。

仅通过浏览器能力检查不能证明外部服务可用。一个环境中成功也不能证明另一个 proxy、quota、profile 或 billing 账户相同。验收记录必须对应真正重要的部署环境。

按顺序排查问题

无法翻译。 确认密钥在进程启动前已设置，浏览器已重启，Cloud Translation API 已启用，并且项目具备所需 billing 配置。再确认页面语言和目标语言确实适用。

权限被拒绝。 检查 API 限制和应用限制，确认请求从允许的网络路径发出，并确认使用的项目就是承担密钥和 billing 的项目。

出现 quota 或速率限制。 查看当前使用量、每日限制和每分钟限制。设置能够防止意外支出的边界，同时为计划工作流保留容量。不要从其他项目复制密钥来绕开限制。

通过 proxy 请求失败。 确认 proxy 在浏览器层配置，并允许翻译所需的 Google 服务。对比受控测试路径与部署路径，让网络策略和 profile 身份各自有清晰负责人。

密钥可能泄露。 在 Google Cloud 中撤销或轮换，更新受保护的启动环境，并清理出现过密钥的分发渠道。访问边界不确定时不要继续测试。

多次运行结果不一致。 对比浏览器 release、profile、user-data 目录、目标语言、proxy、主机、billing 项目、quota 和启动时机，一次只改变一个变量。简短的运行记录比包含私人文本的大量截图更有用。

隐私是翻译决定的一部分

网页翻译会把外部服务所需的文本发送到 Google 服务。这可能包括标题、段落、标签和浏览器翻译流程选中的其他文本，也可能包含个人、机密、受监管或商业敏感信息。使用前应检查组织的数据处理要求。

例行检查应使用获批准的测试页面。除非策略和合同审查明确允许，不要发送密钥、账户恢复资料、支付信息、健康信息、客户记录或机密业务文本。翻译可以改善信息访问，但不应在用户不知情时扩大接收这些信息的系统范围。

让操作人员知道这个决定：哪个项目接收请求，谁能修改密钥，如何处理 quota 告警，密钥暴露时如何轮换。云项目使用最小权限，日志只保留运行所需的元数据。若一句“翻译成功”或“quota 拒绝”已经足够，就不要复制页面文本到工单。

隐私与一致性相互加强。稳定的 profile 和网络路径让数据离开会话的位置及失败点更清楚，明确的数据策略让团队更容易判断何时适合翻译。二者不能互相替代。profile 控制不会自动使敏感文本安全，私密网络也不会让所有外部翻译请求都合适。

管理成本和可用性

Google Cloud 控制价格和 quota。设置预算告警，定期查看用量，并为每个工作流定义最大请求量。较长页面消耗的字符可能远多于短页面，失败时重试也可能增加使用量。

多个团队需要不同预算时，可以使用独立项目或服务边界，并为每个负责人提供 quota 和升级路径。生产可用不只是第一次请求成功，还包括已知成本上限、可用的网络路径、可轮换的密钥，以及账单或 quota 失败时的处理方式。

把可用性视为有条件的结果。Google Cloud、网络路径、profile、源页面和浏览器会话共同决定结果。任一依赖不可用时，保留原页面并报告翻译不可用，不要仅因翻译命令可见就标记为已翻译。

实用清单

启用前：

• 选择数据处理策略和安全的验证页面。
• 选择客户管理的 Google Cloud 项目。
• 启用 Cloud Translation API、billing、quota 限制和告警。
• 将 key 限制到所需 API 和应用路径。
• 把 key 放在源码、profile、截图和共享日志之外。
• 选择匹配的 BotBrowser profile、release、user-data 策略和 proxy。

运行中：

• 在环境变量已存在时启动 BotBrowser。
• 使用浏览器正常翻译命令。
• 确认可见结果，服务不可用时保留原页面。
• 留意权限、quota、billing 和网络错误。
• 记录运行元数据，不复制私人文本或凭据。

运行后：

• 在 Google Cloud 项目中检查预期用量。
• 检查语言和页面状态是否符合预期。
• 怀疑泄露或负责人变化时轮换 key。
• 工作流、profile 或用户范围变化时重新审查 quota 和隐私决定。

相关文档

• Google Translate Page Translation 查看设置参考。
• Profile Management 选择和启动匹配 profile。
• Proxy Configuration 配置浏览器级网络路径。
• First Verification 进行受控启动检查。
• Per-Context Fingerprint 在 context 工作流中分配 profile。

把网页翻译视为具有明确外部边界的浏览器能力。密钥、云项目、profile、网络路径、quota 和数据策略都应对负责会话的人可见。这样既提供实用的语言工具，也保留隐私、一致性和操作控制。