1# Internationalization (i18n) Testing
2 
3## Table of Contents
4 
51. [Locale Configuration](#locale-configuration)
62. [Testing Multiple Locales](#testing-multiple-locales)
73. [RTL Layout Testing](#rtl-layout-testing)
84. [Date, Time & Number Formats](#date-time--number-formats)
95. [Translation Verification](#translation-verification)
106. [Visual Regression for i18n](#visual-regression-for-i18n)
11 
12## Locale Configuration
13 
14### Setting Browser Locale
15 
16```typescript
17// playwright.config.ts
18import { defineConfig, devices } from "@playwright/test";
19 
20export default defineConfig({
21  projects: [
22    {
23      name: "english",
24      use: {
25        ...devices["Desktop Chrome"],
26        locale: "en-US",
27        timezoneId: "America/New_York",
28      },
29    },
30    {
31      name: "german",
32      use: {
33        ...devices["Desktop Chrome"],
34        locale: "de-DE",
35        timezoneId: "Europe/Berlin",
36      },
37    },
38    {
39      name: "japanese",
40      use: {
41        ...devices["Desktop Chrome"],
42        locale: "ja-JP",
43        timezoneId: "Asia/Tokyo",
44      },
45    },
46    {
47      name: "arabic",
48      use: {
49        ...devices["Desktop Chrome"],
50        locale: "ar-SA",
51        timezoneId: "Asia/Riyadh",
52      },
53    },
54  ],
55});
56```
57 
58### Per-Test Locale Override
59 
60```typescript
61test("test in French locale", async ({ browser }) => {
62  const context = await browser.newContext({
63    locale: "fr-FR",
64    timezoneId: "Europe/Paris",
65  });
66 
67  const page = await context.newPage();
68  await page.goto("/");
69 
70  // Verify French content
71  await expect(page.getByRole("button", { name: "Connexion" })).toBeVisible();
72 
73  await context.close();
74});
75```
76 
77### Accept-Language Header
78 
79```typescript
80test("server-side locale detection", async ({ browser }) => {
81  const context = await browser.newContext({
82    locale: "es-ES",
83    extraHTTPHeaders: {
84      "Accept-Language": "es-ES,es;q=0.9,en;q=0.8",
85    },
86  });
87 
88  const page = await context.newPage();
89  await page.goto("/");
90 
91  // Server should respond with Spanish content
92  await expect(page.locator("html")).toHaveAttribute("lang", "es");
93});
94```
95 
96## Testing Multiple Locales
97 
98### Parameterized Locale Tests
99 
100```typescript
101const locales = [
102  { locale: "en-US", greeting: "Hello", button: "Sign In" },
103  { locale: "de-DE", greeting: "Hallo", button: "Anmelden" },
104  { locale: "fr-FR", greeting: "Bonjour", button: "Se connecter" },
105  { locale: "ja-JP", greeting: "こんにちは", button: "ログイン" },
106];
107 
108for (const { locale, greeting, button } of locales) {
109  test(`login page in ${locale}`, async ({ browser }) => {
110    const context = await browser.newContext({ locale });
111    const page = await context.newPage();
112 
113    await page.goto("/login");
114 
115    await expect(page.getByText(greeting)).toBeVisible();
116    await expect(page.getByRole("button", { name: button })).toBeVisible();
117 
118    await context.close();
119  });
120}
121```
122 
123### Locale Fixture
124 
125```typescript
126// fixtures/i18n.ts
127import { test as base } from "@playwright/test";
128 
129type LocaleFixtures = {
130  localePage: (locale: string) => Promise<Page>;
131};
132 
133export const test = base.extend<LocaleFixtures>({
134  localePage: async ({ browser }, use) => {
135    const pages: Page[] = [];
136 
137    const createLocalePage = async (locale: string) => {
138      const context = await browser.newContext({ locale });
139      const page = await context.newPage();
140      pages.push(page);
141      return page;
142    };
143 
144    await use(createLocalePage);
145 
146    // Cleanup
147    for (const page of pages) {
148      await page.context().close();
149    }
150  },
151});
152 
153// Usage
154test("compare locales", async ({ localePage }) => {
155  const enPage = await localePage("en-US");
156  const dePage = await localePage("de-DE");
157 
158  await enPage.goto("/pricing");
159  await dePage.goto("/pricing");
160 
161  const enPrice = await enPage.getByTestId("price").textContent();
162  const dePrice = await dePage.getByTestId("price").textContent();
163 
164  expect(enPrice).toContain("$");
165  expect(dePrice).toContain("€");
166});
167```
168 
169### Testing Locale Switching
170 
171```typescript
172test("user can switch locale", async ({ page }) => {
173  await page.goto("/");
174 
175  // Initial locale (from browser)
176  await expect(page.locator("html")).toHaveAttribute("lang", "en");
177 
178  // Switch to German
179  await page.getByRole("button", { name: "Language" }).click();
180  await page.getByRole("menuitem", { name: "Deutsch" }).click();
181 
182  // Verify switch
183  await expect(page.locator("html")).toHaveAttribute("lang", "de");
184  await expect(page.getByRole("heading", { level: 1 })).toContainText(
185    /Willkommen/,
186  );
187 
188  // Verify persistence (reload)
189  await page.reload();
190  await expect(page.locator("html")).toHaveAttribute("lang", "de");
191});
192```
193 
194## RTL Layout Testing
195 
196### Setting Up RTL Tests
197 
198```typescript
199// playwright.config.ts
200export default defineConfig({
201  projects: [
202    {
203      name: "rtl-arabic",
204      use: {
205        locale: "ar-SA",
206        // RTL is usually set by the app based on locale
207      },
208    },
209    {
210      name: "rtl-hebrew",
211      use: {
212        locale: "he-IL",
213      },
214    },
215  ],
216});
217```
218 
219### Verifying RTL Direction
220 
221```typescript
222test("RTL layout is applied", async ({ page }) => {
223  await page.goto("/");
224 
225  // Check document direction
226  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");
227 
228  // Or check computed style
229  const direction = await page.evaluate(() => {
230    return window.getComputedStyle(document.body).direction;
231  });
232  expect(direction).toBe("rtl");
233});
234```
235 
236### RTL-Specific Element Positioning
237 
238```typescript
239test("sidebar is on the right in RTL", async ({ page }) => {
240  await page.goto("/dashboard");
241 
242  const sidebar = page.getByTestId("sidebar");
243  const main = page.getByTestId("main-content");
244 
245  const sidebarBox = await sidebar.boundingBox();
246  const mainBox = await main.boundingBox();
247 
248  // In RTL, sidebar should be to the right of main content
249  expect(sidebarBox!.x).toBeGreaterThan(mainBox!.x);
250});
251```
252 
253### RTL Visual Regression
254 
255```typescript
256test("RTL layout matches snapshot", async ({ page }) => {
257  await page.goto("/");
258 
259  // Screenshot for RTL comparison
260  await expect(page).toHaveScreenshot("homepage-rtl.png", {
261    // Separate snapshots per locale/direction
262    fullPage: true,
263  });
264});
265 
266// LTR comparison
267test("LTR layout matches snapshot", async ({ browser }) => {
268  const context = await browser.newContext({ locale: "en-US" });
269  const page = await context.newPage();
270 
271  await page.goto("/");
272  await expect(page).toHaveScreenshot("homepage-ltr.png", { fullPage: true });
273});
274```
275 
276### Testing Bidirectional Text
277 
278```typescript
279test("bidirectional text renders correctly", async ({ page }) => {
280  await page.goto("/profile");
281 
282  // Mixed LTR/RTL content
283  const nameField = page.getByTestId("full-name");
284 
285  // Arabic name with English email
286  await expect(nameField).toContainText("محمد ([email protected])");
287 
288  // Verify text doesn't overlap or break
289  const box = await nameField.boundingBox();
290  expect(box!.width).toBeGreaterThan(100); // Content not collapsed
291});
292```
293 
294## Date, Time & Number Formats
295 
296### Testing Date Formats
297 
298```typescript
299test("dates are formatted per locale", async ({ browser }) => {
300  const testDate = new Date("2024-03-15");
301 
302  const formats = [
303    { locale: "en-US", expected: "March 15, 2024" },
304    { locale: "en-GB", expected: "15 March 2024" },
305    { locale: "de-DE", expected: "15. März 2024" },
306    { locale: "ja-JP", expected: "2024年3月15日" },
307  ];
308 
309  for (const { locale, expected } of formats) {
310    const context = await browser.newContext({ locale });
311    const page = await context.newPage();
312 
313    await page.goto(`/event?date=${testDate.toISOString()}`);
314 
315    const dateDisplay = page.getByTestId("event-date");
316    await expect(dateDisplay).toContainText(expected);
317 
318    await context.close();
319  }
320});
321```
322 
323### Testing Number Formats
324 
325```typescript
326test("numbers are formatted per locale", async ({ browser }) => {
327  const testNumber = 1234567.89;
328 
329  const formats = [
330    { locale: "en-US", expected: "1,234,567.89" },
331    { locale: "de-DE", expected: "1.234.567,89" },
332    { locale: "fr-FR", expected: "1 234 567,89" },
333  ];
334 
335  for (const { locale, expected } of formats) {
336    const context = await browser.newContext({ locale });
337    const page = await context.newPage();
338 
339    await page.goto(`/stats?value=${testNumber}`);
340 
341    await expect(page.getByTestId("formatted-number")).toHaveText(expected);
342 
343    await context.close();
344  }
345});
346```
347 
348### Testing Currency Formats
349 
350```typescript
351test("currency displays correctly", async ({ browser }) => {
352  const price = 99.99;
353 
354  const currencies = [
355    { locale: "en-US", currency: "USD", expected: "$99.99" },
356    { locale: "de-DE", currency: "EUR", expected: "99,99 €" },
357    { locale: "ja-JP", currency: "JPY", expected: "￥100" }, // JPY has no decimals
358    { locale: "en-GB", currency: "GBP", expected: "£99.99" },
359  ];
360 
361  for (const { locale, currency, expected } of currencies) {
362    const context = await browser.newContext({ locale });
363    const page = await context.newPage();
364 
365    await page.goto(`/product?price=${price}&currency=${currency}`);
366 
367    await expect(page.getByTestId("price")).toContainText(expected);
368 
369    await context.close();
370  }
371});
372```
373 
374## Translation Verification
375 
376### Checking for Missing Translations
377 
378```typescript
379test("no missing translations", async ({ page }) => {
380  await page.goto("/");
381 
382  // Common patterns for missing translations
383  const missingPatterns = [
384    /\{\{.*\}\}/, // Handlebars-style
385    /\$\{.*\}/, // Template literal style
386    /t\(["'][\w.]+["']\)/, // i18n key exposed
387    /MISSING_TRANSLATION/, // Common placeholder
388    /\[UNTRANSLATED\]/, // Another placeholder
389  ];
390 
391  const bodyText = await page.locator("body").textContent();
392 
393  for (const pattern of missingPatterns) {
394    expect(bodyText).not.toMatch(pattern);
395  }
396});
397```
398 
399### Detecting Text Overflow
400 
401```typescript
402test("translations fit UI containers", async ({ browser }) => {
403  const locales = ["en-US", "de-DE", "fr-FR", "es-ES"];
404  const issues: string[] = [];
405 
406  for (const locale of locales) {
407    const context = await browser.newContext({ locale });
408    const page = await context.newPage();
409    await page.goto("/");
410 
411    const overflowing = await page.evaluate(() => {
412      const elements = document.querySelectorAll("button, .label, h1, h2, h3");
413      return Array.from(elements)
414        .filter(
415          (el) =>
416            (el as HTMLElement).scrollWidth > (el as HTMLElement).clientWidth,
417        )
418        .map((el) => `${el.tagName}: "${el.textContent?.substring(0, 20)}..."`);
419    });
420 
421    if (overflowing.length > 0)
422      issues.push(`${locale}: ${overflowing.join(", ")}`);
423    await context.close();
424  }
425 
426  expect(issues).toEqual([]);
427});
428```
429 
430## Visual Regression for i18n
431 
432### Locale-Specific Snapshots
433 
434```typescript
435// playwright.config.ts
436export default defineConfig({
437  snapshotPathTemplate:
438    "{testDir}/__snapshots__/{projectName}/{testFilePath}/{arg}{ext}",
439 
440  projects: [
441    { name: "en-US", use: { locale: "en-US" } },
442    { name: "de-DE", use: { locale: "de-DE" } },
443    { name: "ja-JP", use: { locale: "ja-JP" } },
444    { name: "ar-SA", use: { locale: "ar-SA" } },
445  ],
446});
447```
448 
449```typescript
450// test file
451test("homepage visual", async ({ page }) => {
452  await page.goto("/");
453 
454  // Snapshot auto-saved to {projectName}/homepage.png
455  await expect(page).toHaveScreenshot("homepage.png");
456});
457```
458 
459### Critical Element Screenshots
460 
461```typescript
462test("navigation in all locales", async ({ page }) => {
463  await page.goto("/");
464 
465  // Just the nav - catches overflow, truncation
466  const nav = page.getByRole("navigation");
467  await expect(nav).toHaveScreenshot("navigation.png");
468});
469 
470test("buttons dont truncate", async ({ page }) => {
471  await page.goto("/checkout");
472 
473  const ctaButton = page.getByRole("button", {
474    name: /checkout|kaufen|acheter/i,
475  });
476  await expect(ctaButton).toHaveScreenshot("checkout-button.png");
477});
478```
479 
480### Font Loading for i18n
481 
482```typescript
483test("wait for fonts before screenshot", async ({ page }) => {
484  await page.goto("/");
485 
486  // Wait for fonts (important for CJK, Arabic)
487  await page.evaluate(() => document.fonts.ready);
488  await page.waitForFunction(() =>
489    document.fonts.check("16px 'Noto Sans Arabic'"),
490  );
491 
492  await expect(page).toHaveScreenshot("with-fonts.png");
493});
494```
495 
496## Anti-Patterns to Avoid
497 
498| Anti-Pattern              | Problem                         | Solution                        |
499| ------------------------- | ------------------------------- | ------------------------------- |
500| Hardcoded text assertions | Breaks in other locales         | Use test IDs or parameterize    |
501| Single locale testing     | Misses i18n bugs                | Test multiple locales           |
502| Ignoring RTL              | Layout broken for RTL users     | Dedicated RTL project           |
503| No font wait              | Screenshots with fallback fonts | Wait for `document.fonts.ready` |
504 
505## Related References
506 
507- **Clock Mocking**: See [clock-mocking.md](../advanced/clock-mocking.md) for timezone testing
508- **Mobile Testing**: See [mobile-testing.md](../advanced/mobile-testing.md) for device-specific locales
509