Options

Set options for every test in playwright.config.ts, under use.fitlocale, or for a file or group with test.use({ fitlocale: { … } }). A test.use value is merged over the config value.

import { defineConfig } from '@playwright/test';
import type { FitlocaleTestOptions } from 'fitlocale/playwright';

export default defineConfig<FitlocaleTestOptions>({
  use: { fitlocale: { sourceMessages: 'locales/en.json', failOn: 'warning' } },
});

modes

Array<'pseudo-long' | 'pseudo-rtl'> · default ['pseudo-long', 'pseudo-rtl']

The pseudo modes: text made longer, and the page forced right-to-left. Both run while the page shows the source locale; forced right-to-left also runs on pages in a pseudo locale, where the text is already long.

expansion

number · default 0.4

Extra length for pseudo-long text, as a fraction: 0.4 makes each text about 40% longer. Some languages run longer (Finnish, German): try 0.6 for tight designs.

sourceLocale

string · default 'en'

Your source language. A page in this language gets the pseudo modes, and other locales are compared with it.

pseudoLocales

string[] · default ['en-XA', 'ar-XB']

Locale codes whose messages were generated by fitlocale pseudo. Pages in them get the integrated checks: hardcoded text, glued sentences and real overflow.

setLocale

(page, locale) => Promise<void> · no default

How your app switches language; needed by useLocale(). Use a helper, or write your own:

import { byCookie, byLocalStorage, byPathPrefix, byQueryParam } from 'fitlocale/playwright';

test.use({ fitlocale: { setLocale: byPathPrefix() } }); // /en/x → /de/x

localeProbe

(page) => Promise<string> · default: reads <html lang>

How to read the current locale, when your app does not keep <html lang> up to date. It is used for the persistence check, and without useLocale() to recognise a page in a pseudo locale.

sourceMessages

string · no default

Path to your source-language message JSON, relative to playwright.config. With it, fitlocale recognises your raw keys on screen (leak/raw-key) and text left in the source language (i18n/untranslated).

localeMessages

string · no default

Path to each locale's message JSON, with {locale} where the locale code goes, relative to playwright.config: for example 'locales/{locale}.json'. With it, a page switched with useLocale() gets the overflow checks too, and only the issues its translation causes are reported. fitlocale puts the source text back in place of each translation it finds in the file, measures again, and leaves out what overflows in the source language as well.

For useLocale('de-CH'), fitlocale reads de-CH.json, else de_CH.json, else de.json. When both a regional file and de.json exist, the regional file is laid over de.json, as vue-i18n and i18next fall back from one to the other. It needs sourceMessages, since each translation is matched to the source text with the same key.

ignore

string[] · default []

CSS selectors to skip in every check: user content, code samples, third-party widgets. script, code, pre, textarea, editable areas and [data-fitlocale-ignore] are always skipped. An ignored shadow host or <iframe> skips everything inside it.

mirrorIgnore

string[] · default: logos, video, audio, code, pre

Elements that legitimately keep their place in right-to-left layouts, skipped by rtl/not-mirrored.

icons

Record<string, 'mirror' | 'invariant' | 'ignore'> · default {}

Your own icon names (one lower-case word) and whether they flip in right-to-left. Per element, use data-fitlocale-icon:

test.use({ fitlocale: { icons: { glyph: 'mirror', compass: 'invariant' } } });

viewports

Array<{ width, height }> | 'current' · default [{ width: 1280, height: 800 }, { width: 390, height: 844 }]

Viewports to check each page at, or 'current' to keep the test's viewport. The window size is restored afterwards.

failOn

'error' | 'warning' | 'never' · default 'error'

What fails the test: issues of severity error, of warning and up, or nothing. Info notes never fail.

baseline

string | false · default 'fitlocale-baseline.json'

The accepted-issues file, relative to playwright.config. Without the file, issues are reported but no test fails. With it, only new issues fail. false fails on every issue at or above failOn. See fitlocale baseline.

screenshots

boolean · default true

Save a full-page screenshot when a mode finds issues, for the HTML report.

mask

string[] · default []

Selectors whose boxes are painted over in every fitlocale screenshot and crop, for customer data and anything you upload. A selector that matches nothing is fine; one that is not valid CSS fails the check with an error naming it. mask covers pixels only: an issue on a masked element still has its text in results.json. Use ignore for elements whose text must not be reported.

fitlocale: { mask: ['.customer-email', '[data-private]'] }

devtools

boolean · default true

Use Chromium DevTools for the fallback-font check and to point mirroring issues at their CSS line. On Firefox and WebKit these two are skipped, and mirroring issues keep the generic fix. Turn it off to save time on very large pages.