emulation.setLocaleOverride command

The emulation.setLocaleOverride command of the emulation module overrides the locale for the specified top-level contexts or user contexts.

Syntax

json
/* 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:

contexts Optional

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 if userContexts is also specified, but it is required if userContexts is not specified.

locale

A string that specifies a structurally valid language tag, such as fr-FR. It can be null to remove the locale override at the specified scope.

userContexts Optional

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.createUserContext or browser.getUserContexts. This field cannot be used if contexts is also specified, but it is required if contexts is 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 contexts and userContexts are specified.
  • Neither contexts nor userContexts is specified.
  • contexts or userContexts is an empty array.
  • A context specified in contexts is not a top-level context.
  • locale is not null and is not a structurally valid language tag.
no such frame

No context with an ID specified in contexts is found.

no such user context

No user context with an ID specified in userContexts is 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:

json
{
  "id": 1,
  "method": "emulation.setLocaleOverride",
  "params": {
    "contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"],
    "locale": "fr-FR"
  }
}

The browser responds with an empty result object:

json
{
  "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

Browser compatibility

See also