Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Set Playwright’s locale when you create a browser context. For a single script, use browser.newContext({ locale: 'de-DE' }). For Playwright Test, set use.locale globally or override it with test.use. This changes the page’s navigator.language, the Accept-Language request header, and locale-sensitive number and date formatting.
Use locale on the browser context
The normal, documented API is the locale context option. Create the context with the language-and-region tag you need, then create pages from that context:
import { chromium } from '@playwright/test';
const browser = await chromium.launch();
const context = await browser.newContext({
locale: 'de-DE',
});
const page = await context.newPage();
await page.goto('https://example.com');
console.log(await page.evaluate(() => navigator.language)); // de-DE
await browser.close();Use a BCP 47 locale tag such as en-GB, en-US, fr-FR, or ja-JP. The language and region are meaningful: en-GB and en-US can produce different date, number, currency, and spelling behavior. If you omit locale, Playwright uses the system locale.
What the setting changes
navigator.languagereports the selected locale.navigator.languagesbegins with the selected locale.- Requests send a matching
Accept-Languageheader. - Browser-side number and date formatting follows the locale, including APIs such as
Intl.NumberFormatandIntl.DateTimeFormat.
The setting belongs to the browser context, so every page created from that context receives the same emulation.
#1 Best Overall
Set a locale in Playwright Test
Playwright Test lets you choose the scope that matches your suite. Put a default in playwright.config.ts when most tests use one locale:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
locale: 'en-GB',
},
});This applies to tests using that configuration. A project can have its own value, which is useful when one project represents a regional deployment or browser matrix.
Override one test
Use test.use when only a test or a group of tests needs another locale:
Recommended Free Tools
import { test, expect } from '@playwright/test';
test.use({ locale: 'de-DE' });
test('German locale', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveTitle(/Example/);
});The effective precedence is the narrowest configuration you provide: a single test or test group can override the project or global use value. Keep regional tests explicit so a later configuration change does not silently alter their expectations.
Locale and timezone are different settings
A locale controls language negotiation and locale-sensitive formatting. It does not select the browser’s time zone. If the site must behave like a user in a particular region, set both:
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
const context = await browser.newContext({
locale: 'de-DE',
timezoneId: 'Europe/Berlin',
});timezoneId changes the emulated browser context. It does not change the timezone of the Node.js process running your tests. If test-runner code itself must use another timezone, configure the process with the TZ environment variable. Treat these as separate controls when diagnosing date failures: the page may be correctly emulated while assertions or fixture code still use the runner’s timezone.
Use separate contexts for multiple languages
A browser context is isolated. You can test several locales in one scenario by creating one context per locale:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →import { chromium } from '@playwright/test';
const browser = await chromium.launch();
const german = await browser.newContext({ locale: 'de-DE' });
const french = await browser.newContext({ locale: 'fr-FR' });
const germanPage = await german.newPage();
const frenchPage = await french.newPage();
await germanPage.goto('https://example.com');
await frenchPage.goto('https://example.com');
console.log(await germanPage.evaluate(() => navigator.language)); // de-DE
console.log(await frenchPage.evaluate(() => navigator.language)); // fr-FR
await german.close();
await french.close();
await browser.close();Do not try to change a context’s locale after pages have been created. Close it and create a new context with the desired option. This keeps cookies, storage, headers, and language behavior isolated between regional cases.
Verify the browser language and HTTP header
Check the browser-facing values in the page before debugging application logic:
import { expect, test } from '@playwright/test';
test.use({ locale: 'de-DE' });
test('locale signals are present', async ({ page }) => {
await page.goto('https://example.com');
await expect(
page.evaluate(() => navigator.language)
).resolves.toBe('de-DE');
await expect(
page.evaluate(() => navigator.languages[0])
).resolves.toBe('de-DE');
});To verify negotiation at the network boundary, inspect a request or the server log and confirm its Accept-Language value. A page can display one language because of a cookie, account preference, URL, or application setting even when the header is correct. Testing both the JavaScript values and the request prevents that ambiguity.
Rank #3
Choosing the right configuration scope
| Scope | Configuration | Best use | Isolation |
|---|---|---|---|
| Suite default | use: { locale: 'en-GB' } in playwright.config.ts |
Most tests share one regional behavior | Each test receives the configured context |
| Project | Set use.locale in a project definition |
Separate regional or browser projects | Project-specific contexts |
| Test or group | test.use({ locale: 'de-DE' }) |
One localized flow or a focused group | Only the selected tests are overridden |
| Raw context | browser.newContext({ locale }) |
Library scripts and custom fixtures | Explicit context boundary |
Why --lang is usually not the answer
Chromium launch arguments can be passed through Playwright’s args option, so a --lang flag is technically available. It is an advanced fallback, not the normal language API. Playwright warns that custom browser arguments are used at your own risk because some can break Playwright functionality.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Prefer locale for ordinary emulation because it is the documented setting that coordinates the JavaScript language value, request header, and formatting rules. Consider a launch argument only when you have a browser-specific requirement that the context option cannot meet, and test the resulting browser behavior after every Playwright upgrade.
Common problems and fixes
navigator.language did not change
Cause: The page came from a context created without locale, or the test is using a different project configuration.
Fix: Put locale on the exact browser.newContext call, or set test.use in the test file. Log the effective value in the page and confirm that the page was created after the configured context.
The site still shows the old language
Cause: The application may prioritize a saved cookie, account preference, URL parameter, or in-app language selector over browser negotiation.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Fix: Start with a fresh context, remove or avoid language cookies, and inspect the response and application settings. Verify the outgoing Accept-Language header separately from the rendered text.
Dates are off by one day
Cause: Locale and timezone are independent, and the test runner can have a different timezone from the browser.
Fix: Set timezoneId for the browser context and use TZ when runner-side code also needs a controlled timezone. Assert dates with an explicit zone rather than relying on the machine running the test.
Accept-Language is unexpected
Cause: The request may not originate from the context you configured, or a proxy/server layer may rewrite headers.
Fix: Capture the request from the target page, compare it with a server log, and check proxy behavior. Ensure the navigation occurs after the locale-enabled context is created.
A custom Chromium argument breaks tests
Cause: Playwright’s warning about custom browser arguments is practical: flags can interfere with automation features.
Fix: Remove the argument and use the context locale option. If the flag is unavoidable, isolate it to the smallest project and run the full browser test suite against that configuration.
Performance, reliability, and test design
- Locale selection is a context setting, so it should be decided before creating pages and fixtures.
- Reuse a context only for tests that intentionally share its locale and state; use separate contexts for independent regional flows.
- Use stable locale-specific assertions, such as checking a known formatted value or language attribute, instead of asserting every translated string in a browser-language test.
- When testing server-side localization, verify both the request header and the final response because application routing may apply its own preference rules.
- Keep timezone tests explicit. A locale-only test should not accidentally depend on the machine’s local clock.
Or skip the browser setup
If your goal is a rendered screenshot rather than an interactive Playwright test, ScreenshotNeo provides a single request-based capture API. It accepts consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers.
For a locale-aware page, pass the relevant request options documented for your account and inspect the returned image or PDF. The basic call is:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://example.com
-o shot.webpSee the complete parameter reference at ScreenshotNeo’s documentation. Python and Node.js equivalents:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
r.raise_for_status()
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 failed: ${res.status}`);
const bytes = await res.arrayBuffer();
// Save bytes as shot.webp in your application.ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Every feature is included on every plan. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I change the locale after creating a Playwright page?
No. Create a new browser context with the desired locale, then create the page from that context.
Does Playwright locale translate my application automatically?
No. It supplies browser language signals and formatting behavior. Your application still decides how to select and render translations.
Should I set locale or only an HTTP header?
Use locale when you want consistent browser values, request negotiation, and formatting. Set a header separately only for a deliberate, narrower network test.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
