emulation.setLocaleOverride command
The emulation.setLocaleOverride command of the emulation module overrides the locale for the specified top-level contexts or user contexts.
Syntax
/* With required parameters and `contexts` */
{
"method": "emulation.setLocaleOverride",
"params": {
"contexts": [
"5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
],
"locale": "fr-FR"
}
}
/* With required parameters and `userContexts` */
{
"method": "emulation.setLocaleOverride",
"params": {
"locale": "fr-FR",
"userContexts": [
"a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c"
]
}
}
Parameters
The params field contains:
contextsOptional-
An array of one or more strings that contains the IDs of the top-level contexts to affect. Context IDs are returned by commands such as
browsingContext.getTree. This field cannot be used ifuserContextsis also specified, but it is required ifuserContextsis not specified. locale-
A string that specifies a structurally valid language tag, such as
fr-FR. It can benullto remove the locale override at the specified scope. userContextsOptional-
An array of one or more strings that contains the IDs of the user contexts to affect. User context IDs are returned by commands such as
browser.createUserContextorbrowser.getUserContexts. This field cannot be used ifcontextsis also specified, but it is required ifcontextsis not specified.
Return value
The result field in the response is an empty object ({}).
Errors
invalid argument-
Thrown in any of the following cases:
- A required parameter is missing, or a parameter has an invalid type or value.
- Both
contextsanduserContextsare specified. - Neither
contextsnoruserContextsis specified. contextsoruserContextsis an empty array.- A context specified in
contextsis not a top-level context. localeis notnulland is not a structurally valid language tag.
no such frame-
No context with an ID specified in
contextsis found. no such user context-
No user context with an ID specified in
userContextsis found.
Description
The emulation.setLocaleOverride command allows you to simulate a locale for the selected top-level contexts or user contexts.
The command changes the default locale used by internationalization APIs such as Intl.DateTimeFormat.
It also changes the language preferences exposed through navigator.language and navigator.languages.
The command also sets the Accept-Language request header to the overridden locale when the request does not already specify that header.
To remove an override, set locale to null for the affected contexts or user contexts.
If you remove an override for a top-level context, an override configured for its user context still applies.
Examples
>Overriding a tab's locale with French
Assume you have a WebDriver BiDi connection and an active session.
Suppose you have a web page that formats dates using the browser's default locale, and you want to verify that it displays dates in French when the locale is fr-FR.
First, open a tab using browsingContext.create, which returns its context ID.
Then load the page you're testing.
Send the following message to set the tab's locale to French:
{
"id": 1,
"method": "emulation.setLocaleOverride",
"params": {
"contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"],
"locale": "fr-FR"
}
}
The browser responds with an empty result object:
{
"type": "success",
"id": 1,
"result": {}
}
After the command succeeds, trigger the page's date formatting.
When the page creates a new Intl.DateTimeFormat object without specifying a locale, the object uses the overridden locale, fr-FR.
Check that the page displays dates using French formatting conventions, such as "14 mars 2026" for March 14, 2026, when using the dateStyle: "long" option.
To remove the override, send the same command with locale set to null and the same contexts array.
Specifications
| Specification |
|---|
| WebDriver BiDi> # command-emulation-setLocaleOverride> |