在 BotBrowser 中使用 Google Translate 翻译网页
使用自己的 Google Cloud 密钥启用网页翻译，并明确管理隐私、配置一致性与成本。
BotBrowser Team
BotBrowser 可以将客户管理的 GOOGLE_API_KEY 传给浏览器进程以翻译网页，但不提供计费、配额、访问许可或将页面内容发送到 Google Cloud 的授权。
TL;DR
- 使用自己管理的 Google Cloud 项目、受限密钥和获批准的网络路径。
- 在启动浏览器前设置
GOOGLE_API_KEY，并保留选定的配置文件和数据策略。 - 用安全页面验证，并只记录版本、配置文件、语言、路径和结果，不记录页面内容。
Contents
阅读其他语言的网页应当是普通的浏览器操作，也应当是一项明确的操作。网页翻译会把翻译所需的页面文本发送给外部服务，并消耗云项目配额。BotBrowser 支持这一流程，但凭据、账单、配额、网络和数据处理决定由你自己的 Google Cloud 项目管理。
这样做的结果很直接：打开网页，使用浏览器正常的翻译命令，然后查看翻译结果。更重要的控制也很明确：由你决定哪个项目承担请求和费用，哪个部署可以使用密钥，哪个配置文件承载会话，以及哪些内容允许发送到翻译服务。
网页翻译能做什么
记录中应包含 GOOGLE_API_KEY、sourceLanguage 和 targetLanguage 的标识，但不保留密钥值。
当页面主要文本不是目标语言时，浏览器可以请求翻译并在当前会话中显示翻译后的文本。这适合支持工作、研究、内容运营、本地化检查以及获得授权的质量验证。应用如何读取浏览器的语言设置，可参阅浏览器语言与应用本地化。
网页翻译是依赖外部服务的浏览器能力。页面可以暴露与翻译有关的浏览器行为，但完整服务仍可能不可用。这是两个不同的结果。能力检查只能说明浏览器理解该功能，不能证明云请求一定成功。真正可用还需要客户自己的有效密钥、已启用的服务、账单、可用配额、允许的网络路径，以及翻译服务能够处理的源页面。
因此应准确描述失败。若浏览器没有翻译命令，先检查页面语言和浏览器设置。若命令出现但结果没有返回，再检查项目、密钥限制、配额、代理和网络。不要把失败请求当成已翻译页面，也不要把可见的浏览器能力当成外部服务已连通的证明。
准备由你管理的 Google Cloud 项目
在第一次正式使用前准备好以下内容：
- 与工作流匹配的 BotBrowser 版本和配置文件。
- 由组织拥有或管理的 Google Cloud 项目。
- 项目中已启用 Cloud Translation API。
- 按服务要求关联计费账户。
- 与预期页面和用户数量相符的配额策略。
- 仅允许 Cloud Translation API 和实际部署路径使用的 API 密钥。
- 能够访问所需 Google 服务的网络路径。
测试时可以使用独立项目，以便分开管理支出和访问边界。独立项目也方便在测试密钥需要撤销时不影响其他工作负载。把配置文件、用户数据策略、代理策略和启动方式视为一个部署单元，减少运行之间的隐含变化。
在 Google Cloud Console 中创建或选择网页翻译项目，启用 Cloud Translation API，关联计费，并查看当前的价格和配额说明。然后在 API 和服务 下的 凭据 中创建 API 密钥，将 API 限制设置为 Cloud Translation API，再添加与浏览器实际运行位置匹配的应用限制。稳定服务器出口可以使用 IP 限制，其他部署可能需要不同限制。选择能工作的最窄边界，并从真实浏览器路径测试。
不要把真实密钥粘贴到文章、源文件、配置文件、截图、终端录屏、提交的环境文件或共享日志中。示例只使用占位符。真实密钥应放在部署密钥管理服务中，或在受保护的交互式命令行中提供给启动 BotBrowser 的进程。如果密钥泄露，应在 Google Cloud 中立即轮换或撤销。
BotBrowser 不提供共享翻译密钥。由客户管理项目可以自行控制费用、配额、访问审查、保留策略和事件响应，同时也意味着 Google Cloud 服务状态和账户配置属于部署方责任。
在浏览器进程中带密钥启动 BotBrowser
环境变量必须在 BotBrowser 进程启动时存在，并且要与正常的配置文件和用户数据参数一起设置：
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 客户端、页面脚本或之后的子进程，不能建立浏览器进程所需的配置。
macOS 和 Linux 可以在启动浏览器的同一个命令行中导出变量：
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 时，由启动浏览器的进程负责环境变量。让受保护的值通过启动边界传入，并把配置文件参数保留在浏览器启动处。不要把密钥放进页面 JavaScript，也不要让网站代码读取它。不要提交真实 .env 文件。有关其他启动方式，请参阅 BotBrowser Launcher：配置、代理与启动。通过 Selenium 使用配置文件时，参见 Selenium 浏览器 Profile 集成与会话归属。
保持配置文件一致
在一次翻译审查中固定 profilePackage、userDataPolicy 和 routePolicy。
翻译不是混用浏览器身份或状态策略的理由。导航前加载目标配置文件，并明确用户数据目录策略。Profile Management 介绍了如何选择并启动匹配的配置文件。需要延续正常会话历史时使用持久目录，需要全新站点关系时使用新目录。不要让无关身份或团队共用一个持久目录。
让配置文件、浏览器版本、主机环境和网络路径描述同一个一致的会话。如果配置文件面向特定浏览器或平台上下文，就在翻译检查期间保持这些选择一致。启动输入不一致会让结果难以复现，也可能把意外状态暴露给页面。要让网络路径保持一致，可参阅 代理、DNS 与 WebRTC 的浏览器身份一致性。
在多配置文件工作流中，必须在会话开始前分配匹配的配置文件，并在会话期间保持身份相关设置稳定。参考 Per-Context Fingerprint 文档 了解当前设置顺序。翻译应在已经定义好的会话中运行，而不是导航后再改变会话。配置文件的责任归属与受控变更，参见浏览器配置文件管理：从责任归属到受控变更。
一致性不仅帮助翻译成功，也让页面可见的浏览器系列、语言偏好、存储状态和网络策略更容易解释。配置文件是浏览器行为和连续性的控制，不是访问许可，也不会覆盖网站访问规则。
验证结果并按顺序排查问题
为获批准的运行记录 browserVersion、profilePackage、sourceLanguage、targetLanguage 和 translationOutcome。
使用部署相同的版本、配置文件、代理、启动方式和目标语言：
- 确认配置密钥后已重启浏览器进程。
- 打开主要文本不是目标语言的页面。
- 从浏览器菜单或右键菜单使用正常的页面翻译命令。
- 确认页面文本发生可见变化且结果可读。
- 在 Google Cloud 项目中查看预期请求用量。
- 记录配置文件、网络路径、源语言、目标语言和结果，不记录页面内容或密钥。
同时测试应该翻译和应该保持原样的页面。对表单、账户信息、客户记录或用户生成文本，例行验证应使用安全的代表性页面，除非数据策略明确批准发送这些内容。
仅通过浏览器能力检查不能证明外部服务可用。一个环境中成功也不能证明另一个代理、配额、配置文件或计费账户相同。验收记录必须对应真正重要的部署环境。
无法翻译。 确认密钥在进程启动前已设置，浏览器已重启，Cloud Translation API 已启用，并且项目具备所需计费配置。再确认页面语言和目标语言确实适用。
权限被拒绝。 检查 API 限制和应用限制，确认请求从允许的网络路径发出，并确认使用的项目就是承担密钥和计费的项目。
出现配额或速率限制。 查看当前使用量、每日限制和每分钟限制。设置能够防止意外支出的边界，同时为计划工作流保留容量。不要从其他项目复制密钥来绕开限制。
通过代理请求失败。 确认代理在浏览器层配置，并允许翻译所需的 Google 服务。浏览器层路由的设置见 Proxy Configuration。对比受控测试路径与部署路径，让网络策略和配置文件身份各自有清晰负责人。
密钥可能泄露。 在 Google Cloud 中撤销或轮换，更新受保护的启动环境，并清理出现过密钥的分发渠道。访问边界不确定时不要继续测试。
多次运行结果不一致。 对比浏览器版本、配置文件、用户数据目录、目标语言、代理、主机、计费项目、配额和启动时机，一次只改变一个变量。简短的运行记录比包含私人文本的大量截图更有用。
保护数据、控制成本并明确负责人
网页翻译会把外部服务所需的文本发送到 Google 服务。这可能包括标题、段落、标签和浏览器翻译流程选中的其他文本，也可能包含个人、机密、受监管或商业敏感信息。使用前应检查组织的数据处理要求。
例行检查应使用获批准的测试页面。除非策略和合同审查明确允许，不要发送密钥、账户恢复资料、支付信息、健康信息、客户记录或机密业务文本。翻译可以改善信息访问，但不应在用户不知情时扩大接收这些信息的系统范围。
让操作人员知道这个决定：哪个项目接收请求，谁能修改密钥，如何处理配额告警，密钥暴露时如何轮换。云项目使用最小权限，日志只保留运行所需的元数据。若一句“翻译成功”或“配额拒绝”已经足够，就不要复制页面文本到工单。
隐私与一致性相互加强。稳定的配置文件和网络路径让数据离开会话的位置及失败点更清楚，明确的数据策略让团队更容易判断何时适合翻译。二者不能互相替代。配置文件控制不会自动使敏感文本安全，私密网络也不会让所有外部翻译请求都合适。更宽的视角见 浏览器工作流中的隐私设计。
Google Cloud 控制价格和配额。设置预算告警，定期查看用量，并为每个工作流定义最大请求量。较长页面消耗的字符可能远多于短页面，失败时重试也可能增加使用量。
多个团队需要不同预算时，可以使用独立项目或服务边界，并为每个负责人提供配额和升级路径。生产可用不只是第一次请求成功，还包括已知成本上限、可用的网络路径、可轮换的密钥，以及账单或配额失败时的处理方式。
把可用性视为有条件的结果。Google Cloud、网络路径、配置文件、源页面和浏览器会话共同决定结果。任一依赖不可用时，保留原页面并报告翻译不可用，不要仅因翻译命令可见就标记为已翻译。
启用前：
- 选择数据处理策略和安全的验证页面。
- 选择客户管理的 Google Cloud 项目。
- 启用 Cloud Translation API、计费、配额限制和告警。
- 将密钥限制到所需 API 和应用路径。
- 把密钥放在源码、配置文件、截图和共享日志之外。
- 选择匹配的 BotBrowser配置文件、版本、用户数据策略和代理。
运行中：
- 在环境变量已存在时启动 BotBrowser。
- 使用浏览器正常翻译命令。
- 确认可见结果，服务不可用时保留原页面。
- 留意权限、配额、计费和网络错误。
- 记录运行元数据，不复制私人文本或凭据。
运行后：
- 在 Google Cloud 项目中检查预期用量。
- 检查语言和页面状态是否符合预期。
- 怀疑泄露或负责人变化时轮换密钥。
- 工作流、配置文件或用户范围变化时重新审查配额和隐私决定。
第一次翻译成功只是形成运行模式的开始。如果有多人或定时任务使用该功能，请为这个流程指定明确的负责人。负责人应当知道哪个云项目接收请求、哪个配置文件已获批准、预期使用哪条网络路径，以及服务不可用时该怎么做。管理浏览器配置文件的人不一定需要修改云计费的权限，管理云项目的人也不一定需要查看页面内容。职责分开，审查更容易。
把开发、预发布和生产的决定分开。测试项目可以使用较小的配额和安全的示例页面，生产项目可以有不同的预算、告警接收方式和密钥限制。不要假设能在笔记本电脑上使用的密钥也能在服务器路径上使用，也不要假设为某个版本准备的配置文件适用于所有浏览器版本。记录通过用户可见检查的完整组合。
定期运行的会话也需要状态策略。决定会话是保留用户数据目录、使用全新目录，还是按照有文档记录的轮换计划处理。这个选择影响的不只是 Cookie。语言偏好、站点相关决定和其他浏览器状态都可能改变页面体验，也会影响对之后检查结果的解读。全新会话不一定更安全，持久会话也不一定有问题。关键是这个选择经过考虑，并且符合数据策略。
翻译请求失败时，保留原始页面，并给操作人员一个有用的状态。要区分服务不可用、页面尚未翻译、页面本来不需要翻译，以及页面被数据策略排除这几种情况。它们对应不同的后续处理：服务中断可能需要重试或升级处理，被排除的页面需要策略决定，已经是目标语言的页面不需要发出云请求。清晰的状态能减少不必要的重试，也避免在排查错误问题时消耗配额。
当任何边界发生变化时，重新审查这个流程，例如新的浏览器版本、新的配置文件系列、新的主机、新的代理、更换的云项目、变化的使用对象或数据分类。使用同一个安全的验证页面，对比可见结果，并检查预期用量。只保留下一次决定所需的运行证据。这既保护隐私，也让一致性可以衡量。
BotBrowser 支持浏览器内置的网页翻译：启动时，它会从浏览器进程的环境中读取由客户自行提供的 GOOGLE_API_KEY。因此，你的团队可以在自己的 Google Cloud 项目、配额和计费策略下运行翻译，并与自己选择的配置文件和代理搭配使用。BotBrowser 不提供共享的翻译密钥，也不能保证翻译一定成功：密钥限制、计费、配额、服务可用性、网络路径和源页面都取决于 Google Cloud 和你的环境，而不是 BotBrowser。它也不能替代你自己的数据处理审查。
实践结论
将翻译视为客户管理的云集成：加载已批准的配置文件，在启动前设置 GOOGLE_API_KEY，限制密钥和网络路径，并为安全页面保留最小运行记录。浏览器可以请求翻译，但不能决定页面内容是否允许离开你的环境。
公开来源
本文属于指南： 浏览器自动化入门：首次运行地图