SurfSense/.cursor/skills/playwright-testing/testing-patterns/i18n.md

# Internationalization (i18n) Testing

## Table of Contents

1. [Locale Configuration](#locale-configuration)
2. [Testing Multiple Locales](#testing-multiple-locales)
3. [RTL Layout Testing](#rtl-layout-testing)
4. [Date, Time & Number Formats](#date-time--number-formats)
5. [Translation Verification](#translation-verification)
6. [Visual Regression for i18n](#visual-regression-for-i18n)

## Locale Configuration

### Setting Browser Locale

```typescript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  projects: [
    {
      name: "english",
      use: {
        ...devices["Desktop Chrome"],
        locale: "en-US",
        timezoneId: "America/New_York",
      },
    },
    {
      name: "german",
      use: {
        ...devices["Desktop Chrome"],
        locale: "de-DE",
        timezoneId: "Europe/Berlin",
      },
    },
    {
      name: "japanese",
      use: {
        ...devices["Desktop Chrome"],
        locale: "ja-JP",
        timezoneId: "Asia/Tokyo",
      },
    },
    {
      name: "arabic",
      use: {
        ...devices["Desktop Chrome"],
        locale: "ar-SA",
        timezoneId: "Asia/Riyadh",
      },
    },
  ],
});
```

### Per-Test Locale Override

```typescript
test("test in French locale", async ({ browser }) => {
  const context = await browser.newContext({
    locale: "fr-FR",
    timezoneId: "Europe/Paris",
  });

  const page = await context.newPage();
  await page.goto("/");

  // Verify French content
  await expect(page.getByRole("button", { name: "Connexion" })).toBeVisible();

  await context.close();
});
```

### Accept-Language Header

```typescript
test("server-side locale detection", async ({ browser }) => {
  const context = await browser.newContext({
    locale: "es-ES",
    extraHTTPHeaders: {
      "Accept-Language": "es-ES,es;q=0.9,en;q=0.8",
    },
  });

  const page = await context.newPage();
  await page.goto("/");

  // Server should respond with Spanish content
  await expect(page.locator("html")).toHaveAttribute("lang", "es");
});
```

## Testing Multiple Locales

### Parameterized Locale Tests

```typescript
const locales = [
  { locale: "en-US", greeting: "Hello", button: "Sign In" },
  { locale: "de-DE", greeting: "Hallo", button: "Anmelden" },
  { locale: "fr-FR", greeting: "Bonjour", button: "Se connecter" },
  { locale: "ja-JP", greeting: "こんにちは", button: "ログイン" },
];

for (const { locale, greeting, button } of locales) {
  test(`login page in ${locale}`, async ({ browser }) => {
    const context = await browser.newContext({ locale });
    const page = await context.newPage();

    await page.goto("/login");

    await expect(page.getByText(greeting)).toBeVisible();
    await expect(page.getByRole("button", { name: button })).toBeVisible();

    await context.close();
  });
}
```

### Locale Fixture

```typescript
// fixtures/i18n.ts
import { test as base } from "@playwright/test";

type LocaleFixtures = {
  localePage: (locale: string) => Promise<Page>;
};

export const test = base.extend<LocaleFixtures>({
  localePage: async ({ browser }, use) => {
    const pages: Page[] = [];

    const createLocalePage = async (locale: string) => {
      const context = await browser.newContext({ locale });
      const page = await context.newPage();
      pages.push(page);
      return page;
    };

    await use(createLocalePage);

    // Cleanup
    for (const page of pages) {
      await page.context().close();
    }
  },
});

// Usage
test("compare locales", async ({ localePage }) => {
  const enPage = await localePage("en-US");
  const dePage = await localePage("de-DE");

  await enPage.goto("/pricing");
  await dePage.goto("/pricing");

  const enPrice = await enPage.getByTestId("price").textContent();
  const dePrice = await dePage.getByTestId("price").textContent();

  expect(enPrice).toContain("$");
  expect(dePrice).toContain("€");
});
```

### Testing Locale Switching

```typescript
test("user can switch locale", async ({ page }) => {
  await page.goto("/");

  // Initial locale (from browser)
  await expect(page.locator("html")).toHaveAttribute("lang", "en");

  // Switch to German
  await page.getByRole("button", { name: "Language" }).click();
  await page.getByRole("menuitem", { name: "Deutsch" }).click();

  // Verify switch
  await expect(page.locator("html")).toHaveAttribute("lang", "de");
  await expect(page.getByRole("heading", { level: 1 })).toContainText(
    /Willkommen/,
  );

  // Verify persistence (reload)
  await page.reload();
  await expect(page.locator("html")).toHaveAttribute("lang", "de");
});
```

## RTL Layout Testing

### Setting Up RTL Tests

```typescript
// playwright.config.ts
export default defineConfig({
  projects: [
    {
      name: "rtl-arabic",
      use: {
        locale: "ar-SA",
        // RTL is usually set by the app based on locale
      },
    },
    {
      name: "rtl-hebrew",
      use: {
        locale: "he-IL",
      },
    },
  ],
});
```

### Verifying RTL Direction

```typescript
test("RTL layout is applied", async ({ page }) => {
  await page.goto("/");

  // Check document direction
  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");

  // Or check computed style
  const direction = await page.evaluate(() => {
    return window.getComputedStyle(document.body).direction;
  });
  expect(direction).toBe("rtl");
});
```

### RTL-Specific Element Positioning

```typescript
test("sidebar is on the right in RTL", async ({ page }) => {
  await page.goto("/dashboard");

  const sidebar = page.getByTestId("sidebar");
  const main = page.getByTestId("main-content");

  const sidebarBox = await sidebar.boundingBox();
  const mainBox = await main.boundingBox();

  // In RTL, sidebar should be to the right of main content
  expect(sidebarBox!.x).toBeGreaterThan(mainBox!.x);
});
```

### RTL Visual Regression

```typescript
test("RTL layout matches snapshot", async ({ page }) => {
  await page.goto("/");

  // Screenshot for RTL comparison
  await expect(page).toHaveScreenshot("homepage-rtl.png", {
    // Separate snapshots per locale/direction
    fullPage: true,
  });
});

// LTR comparison
test("LTR layout matches snapshot", async ({ browser }) => {
  const context = await browser.newContext({ locale: "en-US" });
  const page = await context.newPage();

  await page.goto("/");
  await expect(page).toHaveScreenshot("homepage-ltr.png", { fullPage: true });
});
```

### Testing Bidirectional Text

```typescript
test("bidirectional text renders correctly", async ({ page }) => {
  await page.goto("/profile");

  // Mixed LTR/RTL content
  const nameField = page.getByTestId("full-name");

  // Arabic name with English email
  await expect(nameField).toContainText("محمد (mohammed@example.com)");

  // Verify text doesn't overlap or break
  const box = await nameField.boundingBox();
  expect(box!.width).toBeGreaterThan(100); // Content not collapsed
});
```

## Date, Time & Number Formats

### Testing Date Formats

```typescript
test("dates are formatted per locale", async ({ browser }) => {
  const testDate = new Date("2024-03-15");

  const formats = [
    { locale: "en-US", expected: "March 15, 2024" },
    { locale: "en-GB", expected: "15 March 2024" },
    { locale: "de-DE", expected: "15. März 2024" },
    { locale: "ja-JP", expected: "2024年3月15日" },
  ];

  for (const { locale, expected } of formats) {
    const context = await browser.newContext({ locale });
    const page = await context.newPage();

    await page.goto(`/event?date=${testDate.toISOString()}`);

    const dateDisplay = page.getByTestId("event-date");
    await expect(dateDisplay).toContainText(expected);

    await context.close();
  }
});
```

### Testing Number Formats

```typescript
test("numbers are formatted per locale", async ({ browser }) => {
  const testNumber = 1234567.89;

  const formats = [
    { locale: "en-US", expected: "1,234,567.89" },
    { locale: "de-DE", expected: "1.234.567,89" },
    { locale: "fr-FR", expected: "1 234 567,89" },
  ];

  for (const { locale, expected } of formats) {
    const context = await browser.newContext({ locale });
    const page = await context.newPage();

    await page.goto(`/stats?value=${testNumber}`);

    await expect(page.getByTestId("formatted-number")).toHaveText(expected);

    await context.close();
  }
});
```

### Testing Currency Formats

```typescript
test("currency displays correctly", async ({ browser }) => {
  const price = 99.99;

  const currencies = [
    { locale: "en-US", currency: "USD", expected: "$99.99" },
    { locale: "de-DE", currency: "EUR", expected: "99,99 €" },
    { locale: "ja-JP", currency: "JPY", expected: "￥100" }, // JPY has no decimals
    { locale: "en-GB", currency: "GBP", expected: "£99.99" },
  ];

  for (const { locale, currency, expected } of currencies) {
    const context = await browser.newContext({ locale });
    const page = await context.newPage();

    await page.goto(`/product?price=${price}&currency=${currency}`);

    await expect(page.getByTestId("price")).toContainText(expected);

    await context.close();
  }
});
```

## Translation Verification

### Checking for Missing Translations

```typescript
test("no missing translations", async ({ page }) => {
  await page.goto("/");

  // Common patterns for missing translations
  const missingPatterns = [
    /\{\{.*\}\}/, // Handlebars-style
    /\$\{.*\}/, // Template literal style
    /t\(["'][\w.]+["']\)/, // i18n key exposed
    /MISSING_TRANSLATION/, // Common placeholder
    /\[UNTRANSLATED\]/, // Another placeholder
  ];

  const bodyText = await page.locator("body").textContent();

  for (const pattern of missingPatterns) {
    expect(bodyText).not.toMatch(pattern);
  }
});
```

### Detecting Text Overflow

```typescript
test("translations fit UI containers", async ({ browser }) => {
  const locales = ["en-US", "de-DE", "fr-FR", "es-ES"];
  const issues: string[] = [];

  for (const locale of locales) {
    const context = await browser.newContext({ locale });
    const page = await context.newPage();
    await page.goto("/");

    const overflowing = await page.evaluate(() => {
      const elements = document.querySelectorAll("button, .label, h1, h2, h3");
      return Array.from(elements)
        .filter(
          (el) =>
            (el as HTMLElement).scrollWidth > (el as HTMLElement).clientWidth,
        )
        .map((el) => `${el.tagName}: "${el.textContent?.substring(0, 20)}..."`);
    });

    if (overflowing.length > 0)
      issues.push(`${locale}: ${overflowing.join(", ")}`);
    await context.close();
  }

  expect(issues).toEqual([]);
});
```

## Visual Regression for i18n

### Locale-Specific Snapshots

```typescript
// playwright.config.ts
export default defineConfig({
  snapshotPathTemplate:
    "{testDir}/__snapshots__/{projectName}/{testFilePath}/{arg}{ext}",

  projects: [
    { name: "en-US", use: { locale: "en-US" } },
    { name: "de-DE", use: { locale: "de-DE" } },
    { name: "ja-JP", use: { locale: "ja-JP" } },
    { name: "ar-SA", use: { locale: "ar-SA" } },
  ],
});
```

```typescript
// test file
test("homepage visual", async ({ page }) => {
  await page.goto("/");

  // Snapshot auto-saved to {projectName}/homepage.png
  await expect(page).toHaveScreenshot("homepage.png");
});
```

### Critical Element Screenshots

```typescript
test("navigation in all locales", async ({ page }) => {
  await page.goto("/");

  // Just the nav - catches overflow, truncation
  const nav = page.getByRole("navigation");
  await expect(nav).toHaveScreenshot("navigation.png");
});

test("buttons dont truncate", async ({ page }) => {
  await page.goto("/checkout");

  const ctaButton = page.getByRole("button", {
    name: /checkout|kaufen|acheter/i,
  });
  await expect(ctaButton).toHaveScreenshot("checkout-button.png");
});
```

### Font Loading for i18n

```typescript
test("wait for fonts before screenshot", async ({ page }) => {
  await page.goto("/");

  // Wait for fonts (important for CJK, Arabic)
  await page.evaluate(() => document.fonts.ready);
  await page.waitForFunction(() =>
    document.fonts.check("16px 'Noto Sans Arabic'"),
  );

  await expect(page).toHaveScreenshot("with-fonts.png");
});
```

## Anti-Patterns to Avoid

| Anti-Pattern              | Problem                         | Solution                        |
| ------------------------- | ------------------------------- | ------------------------------- |
| Hardcoded text assertions | Breaks in other locales         | Use test IDs or parameterize    |
| Single locale testing     | Misses i18n bugs                | Test multiple locales           |
| Ignoring RTL              | Layout broken for RTL users     | Dedicated RTL project           |
| No font wait              | Screenshots with fallback fonts | Wait for `document.fonts.ready` |

## Related References

- **Clock Mocking**: See [clock-mocking.md](../advanced/clock-mocking.md) for timezone testing
- **Mobile Testing**: See [mobile-testing.md](../advanced/mobile-testing.md) for device-specific locales