i18n

Testing Chrome extension localization requires more than setting Playwright's locale option. Chrome selects extension translations using its browser UI locale, which depends on the operating system and how Chrome is launched. For example, macOS uses system language preferences, while Linux supports a language environment variable. See Chrome's locale setup. Playwright's locale option alone does not switch this browser UI locale.

playwright-webext provides a workaround: choose a test locale, and the package prepares a temporary extension copy with the matching translations. This lets you test the extension's manifest, messages, and UI in different languages without changing your system settings.

For multiple locales, use Playwright projects with different use.locale values.

Example

This example assumes your manifest declares a popup and sets "default_locale": "en". The translation catalogs contain a single greeting message:

_locales/
├── en/
│   └── messages.json
└── es/
    └── messages.json

_locales/en/messages.json

{
  "greeting": {
    "message": "Hello"
  }
}

_locales/es/messages.json

{
  "greeting": {
    "message": "Hola"
  }
}

The popup displays chrome.i18n.getMessage('greeting') in a heading:

test/i18n.spec.ts

import { expect } from '@playwright/test';
import { test } from 'playwright-webext';

test.use({ locale: 'es' });

test('shows the Spanish greeting in the popup', async ({ extension }) => {
  const popupPage = await extension.openPopup();
  await expect(popupPage.getByRole('heading')).toHaveText('Hola');
});

Under the hood

For a non-default locale, the package creates a temporary copy of your extension and:

1. Selects the requested translation catalog. For example, es-ES first looks for _locales/es_ES, then falls back to _locales/es. Installation fails if neither exists.
2. Sets the copy's default_locale to the selected locale and removes the other catalogs.
3. Loads this copy so Chrome resolves manifest messages and chrome.i18n.getMessage() using the selected catalog. The API itself is not mocked.

The original extension directory is unchanged. The temporary copy is removed after the browser closes.

Playwright supplies en-US by default. That value loads the original extension without modifying its catalogs, even when explicitly configured. Other values, including en-GB, require an exact or base-language catalog.

Limitations

Chromium's UI locale remains unchanged. chrome.i18n.getUILanguage() and chrome.i18n.getMessage('@@ui_locale') still return the browser's actual UI locale, which can differ from the configured test locale. Predefined direction messages such as @@bidi_dir also follow the browser's UI locale. See Chrome's i18n reference.

Only the selected catalog is retained, so this does not test fallback for missing messages to your extension's original default catalog.

Localized copies can have different path-derived extension IDs unless your manifest defines a stable key.