Puppeteer Screenshot with a Specific Locale and Timezone

To take a Puppeteer screenshot with a specific timezone, create a page, call page.emulateTimezone('America/Los_Angeles'), navigate to the page, wait for the content you need, and capture it with page.screenshot(). Set the page locale before navigation too, but first check the API reference for your installed Puppeteer version: locale emulation was added in Puppeteer 25.2.0, and the available research does not verify its current method name or signature. Do not copy an unverified locale call into production.

Timezone emulation affects browser date and time behavior. Locale can affect language selection and formatting behavior, but the exact effects depend on the API and the page. Neither setting automatically translates a website or guarantees that its server returns regional content.

1. Check Puppeteer and browser versions

Record the Puppeteer version, browser version, protocol, timezone, locale, viewport, and screenshot settings alongside each captured artifact. Puppeteer documents compatibility guarantees for its bundled browser; if you select a separate browser executable, treat its version and choice as part of the capture configuration.

Locale emulation support was added in Puppeteer 25.2.0. Consult the versioned API reference for your installed release to find the supported method and arguments. The references available for this guide confirm the feature’s introduction but not its current signature, so this example deliberately leaves that one step as a comment rather than guessing.

2. Apply settings before navigation

Set the timezone and the version-specific locale setting before loading the page. This gives page scripts the configured browser environment from the start. Use an ICU-supported timezone identifier, such as America/Los_Angeles or Europe/Paris. Puppeteer documents null as disabling timezone emulation.

const puppeteer = require('puppeteer');

async function capture() {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();

    // Check the API reference for your installed Puppeteer version.
    // Locale emulation is available starting in Puppeteer 25.2.0;
    // use its documented method and arguments here.

    await page.emulateTimezone('America/Los_Angeles');
    await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });

    await page.goto('https://example.com', {
      waitUntil: 'networkidle2',
      timeout: 60000
    });

    await page.screenshot({ path: 'page.png', fullPage: true });
  } finally {
    await browser.close();
  }
}

capture().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

Run it with Node.js after installing Puppeteer in your project. This is runnable for timezone capture once Puppeteer and its browser are installed; add locale emulation only after verifying the exact API for that installed version.

3. Choose what to capture

page.screenshot() captures the page. Use the options below to control the output; confirm option support against the API reference and protocol used by your Puppeteer version.

Option	Purpose	Notes
path	Writes the image to a file.	Omit it if you want the screenshot returned as binary data or base64.
type	Selects an image format.	Choose a format supported by the installed browser; quality settings apply to formats that support them.
fullPage	Captures the full page rather than only the viewport.	Long pages can produce large images and take longer to capture.
clip	Captures a specified rectangular region.	Use it when a fixed area is more useful than a full-page image.
omitBackground	Omits the default page background for transparency.	Useful for transparent output where the chosen format supports it.

For an element-level image, find the element and call elementHandle.screenshot(). Puppeteer scrolls the element into view if needed before capturing it.

const element = await page.$('#receipt');
if (!element) throw new Error('Could not find #receipt');
await element.screenshot({ path: 'receipt.png' });

4. Wait for the right page state

The example uses networkidle2, a wait condition shown in Puppeteer’s screenshot guide. It is not a universal signal that a page is ready: analytics, polling, streaming, or other ongoing requests may keep a site active, while an application may render important content after network activity settles.

Choose a wait condition based on the content being captured. For pages with a clear completion marker, wait for that selector after navigation:

await page.goto('https://example.com/report', { waitUntil: 'domcontentloaded' });
await page.waitForSelector('[data-report-ready]', { timeout: 15000 });
await page.screenshot({ path: 'report.png', fullPage: true });

If the page shows local time or dates, make sure the relevant content has rendered after navigation before taking the screenshot. Apply locale and timezone before navigation so scripts that inspect browser settings during startup see the intended environment.

5. Understand locale and timezone boundaries

• Browser emulation is not server geolocation. A site may use your IP address, account settings, cookies, or request headers to choose content. Emulating a timezone or locale does not set those values.
• Locale support is version-specific. Confirm the method, arguments, and protocol support in the documentation for your installed Puppeteer release. The changelog places its introduction in 25.2.0.
• Timezone IDs must be recognized. Use an ICU-supported identifier. If emulation fails, check the spelling and identifier against the supported list.
• Protocol support can vary. Puppeteer’s WebDriver BiDi documentation lists screenshot parameters and timezone emulation, while noting that some features are not available over every protocol. Verify the combination you run.
• Locale does not guarantee translation. A site must itself respond to locale preferences for visible text to change.

6. Troubleshooting

Symptom	Likely cause	Fix
Locale setting method is missing	The installed Puppeteer version predates locale emulation, or the API name differs from the assumed signature.	Check the versioned API reference. Locale emulation was added in 25.2.0; upgrade only if the required API is available in the newer version.
Timezone emulation rejects the identifier	The ID is misspelled or unsupported by the runtime’s ICU data.	Use an ICU-supported timezone ID and verify its spelling.
The screenshot still shows the wrong regional content	The site uses server-side location, cookies, account preferences, or other signals rather than browser locale or timezone alone.	Inspect the site’s own regional selection behavior and configure the relevant inputs separately.
Capture times out waiting for network idle	The page keeps requests open or performs background polling.	Use a more suitable navigation wait condition, then wait for a selector that identifies the content you need.
Important content is missing	The screenshot was taken before client rendering or lazy content completed.	Wait for a page-specific selector or readiness signal before capture.
Output differs between machines	Browser executable, Puppeteer version, protocol, viewport, device scale factor, fonts, or page state differs.	Record and pin the browser and capture configuration, and use Puppeteer’s bundled browser when its compatibility guarantee fits your needs.
Screenshot options behave differently	The selected protocol or browser does not support every option.	Check the documentation for the actual protocol and browser combination; BiDi and other protocols can have different feature availability.

7. Performance, reliability, and cost

Full-page images can be much larger than viewport captures, especially on long pages or at a high device scale factor. Use a viewport or clip when it answers the task. Select only the output format and dimensions you need, and wait for a specific readiness marker instead of depending on a long, open-ended wait.

For repeatable results, keep the Puppeteer and browser versions, protocol, locale, timezone, viewport, device scale factor, wait condition, and screenshot options with the artifact. A locally managed browser gives you control over those inputs, but you must maintain the runtime and account for failed navigations and retries in your own workflow.

Or skip the browser setup

For a hosted screenshot API, ScreenshotNeo accepts a URL in one GET request and returns an image or PDF. Its timezone and geolocation options can set the capture environment; check the ScreenshotNeo API documentation for parameter names and supported values.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

Equivalent requests in Python and Node.js:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

Cookie banners, newsletter popups, and chat widgets are removed before the shot, with each cleanup step optional. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. ScreenshotNeo also offers an MCP server for AI agents, and its free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up free and capture your first 1,000 screenshots a month without a card.

FAQ

Does Puppeteer locale emulation translate a website?

No. It can provide locale settings to the page, but the website must use those settings to choose translated content.

Can I use a timezone and locale together?

Yes, configure both before navigation. Use the documented locale API for your installed Puppeteer version and page.emulateTimezone() for the timezone.

Can I capture a single element?

Yes. Use ElementHandle.screenshot(); Puppeteer scrolls the element into view when needed.

Why does my API screenshot look different from a local Puppeteer capture?

The browser environment, viewport, page readiness, locale, timezone, and site-side regional signals may differ. Match the relevant settings and verify which inputs the site uses.

References

• Puppeteer Page.screenshot API
• Puppeteer Page.emulateTimezone API
• Puppeteer screenshot guide
• Puppeteer changelog (locale emulation introduction in 25.2.0)
• Puppeteer WebDriver BiDi guide
• Puppeteer launch API