@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/testing-patterns/i18n.md

@@ -0,0 +1,508 @@
+# 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