Google Translate Page Translation

Use your own Google Cloud API key to enable page translation in BotBrowser.

Requirements

A BotBrowser release and a matching profile.
A Google Cloud project with billing enabled.
The Cloud Translation API enabled for that project.
An API key restricted to the Cloud Translation API.

Google Cloud controls pricing and quotas. Check the Cloud Translation pricing and quotas pages before production use.

What this enables

The key supplies the Google service used by the browser’s built-in page translation flow. BotBrowser does not provide a shared translation key. Each deployment can use its own Google Cloud project, quota, and billing policy.

The hrefTranslate page capability and the full translation service are separate. A page can expose the standard translation-related DOM surface while translation remains unavailable because the deployment has no usable key or network access.

Create an API key

Open the Google Cloud Console.
Create or select a project for translation.
Enable the Cloud Translation API.
Link the project to a billing account.
Open APIs & Services > Credentials, then create an API key.
Edit the key and set API restrictions to Cloud Translation API.
Add an application restriction that matches where BotBrowser runs. An IP restriction is suitable for a stable server egress. Review referrer restrictions carefully because translation requests are made by the browser session.

Keep the key out of source control, profile files, screenshots, and shared logs. Rotate or revoke it from Google Cloud if it is exposed.

Launch BotBrowser

Set GOOGLE_API_KEY in the environment of the BotBrowser process before launch:


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

The key is read when the browser process starts. Restart BotBrowser after changing the environment variable. Do not put the key in a page script or pass it only to an outer HTTP client.

After opening a page in another language, use the browser’s normal page-translation command. Translation availability depends on the key, billing account, quota, proxy, network access, and the source page.

macOS and Linux

Export the variable in the same shell that starts BotBrowser:


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

Set the variable for the process before launching the browser:


$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 and Puppeteer

The environment must belong to the process that launches the browser. The browser arguments still carry the profile and user-data paths:


const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  env: { ...process.env, GOOGLE_API_KEY: process.env.GOOGLE_API_KEY },
  args: [
    '--bot-profile=/absolute/path/to/profile.enc',
    '--user-data-dir=/absolute/path/to/user-data',
  ],
});

Do not place the key in a committed .env file. Use the deployment secret store or an interactive shell instead.

Verify the setup

Confirm that the BotBrowser process was restarted after the key was set.
Open a page whose main text is not in the browser’s target language.
Use the normal page-translation command from the browser menu or context menu.
Confirm that the translated page is rendered and that the Google Cloud project shows the expected request usage.

Run this check with the same profile, proxy, and launch method used by the deployment. A successful DOM capability check alone does not prove that the external translation service is available.

Troubleshooting

Symptom	Check
Translation is unavailable	Confirm that `GOOGLE_API_KEY` was set before the browser process started and that the Cloud Translation API is enabled.
Permission denied	Check the key restrictions and confirm that the selected project has billing enabled.
Quota or rate-limit errors	Review the project quotas and usage in Google Cloud Console.
Requests fail through a proxy	Confirm that the proxy is configured in BotBrowser and that it permits the required Google services.
The key was exposed	Revoke or rotate it in Google Cloud, then update the launch environment.

Privacy and cost

Page translation sends the text needed by the translation service to Google’s service. Review your data-handling requirements before translating sensitive content. Set quotas and monitor usage so the project stays within the intended budget.

Profile Management - choose and launch a matching profile.
Proxy Configuration - configure browser-level proxy routing.
First Verification - verify a new BotBrowser launch.