# Internationalization and Localization Testing

> **When to use**: Verifying your application works correctly across locales, languages, text directions, date/number formats, and timezones. Catches layout breaks, missing translations, and format errors before they reach international users.
> **Prerequisites**: [core/configuration.md](configuration.md), [core/locators.md](locators.md)

## Quick Reference

```typescript
// Set locale and timezone per context
const context = await browser.newContext({
  locale: 'de-DE',
  timezoneId: 'Europe/Berlin',
});

// Or in playwright.config.ts for project-level locale testing
projects: [
  { name: 'english', use: { locale: 'en-US', timezoneId: 'America/New_York' } },
  { name: 'german',  use: { locale: 'de-DE', timezoneId: 'Europe/Berlin' } },
  { name: 'arabic',  use: { locale: 'ar-SA', timezoneId: 'Asia/Riyadh' } },
],
```

## Patterns

### Setting Browser Locale

**Use when**: Testing locale-dependent rendering -- date formats, number formatting, currency, sorting, and browser-level localization.
**Avoid when**: Your app does not use the browser locale and instead relies on a user preference stored server-side.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test.describe("locale-specific formatting", () => {
  test("US locale formats dates as MM/DD/YYYY", async ({ browser }) => {
    const context = await browser.newContext({ locale: "en-US" })
    const page = await context.newPage()
    await page.goto("/dashboard")

    // Verify date format matches US convention
    await expect(page.getByTestId("last-updated")).toHaveText(/\d{1,2}\/\d{1,2}\/\d{4}/)
    await context.close()
  })

  test("German locale formats dates as DD.MM.YYYY", async ({ browser }) => {
    const context = await browser.newContext({ locale: "de-DE" })
    const page = await context.newPage()
    await page.goto("/dashboard")

    await expect(page.getByTestId("last-updated")).toHaveText(/\d{1,2}\.\d{1,2}\.\d{4}/)
    await context.close()
  })

  test("Japanese locale formats numbers with commas", async ({ browser }) => {
    const context = await browser.newContext({ locale: "ja-JP" })
    const page = await context.newPage()
    await page.goto("/pricing")

    // Japanese yen: no decimal places, uses comma grouping
    await expect(page.getByTestId("price")).toHaveText(/[\d,]+円/)
    await context.close()
  })
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("German locale formats dates as DD.MM.YYYY", async ({ browser }) => {
  const context = await browser.newContext({ locale: "de-DE" })
  const page = await context.newPage()
  await page.goto("/dashboard")

  await expect(page.getByTestId("last-updated")).toHaveText(/\d{1,2}\.\d{1,2}\.\d{4}/)
  await context.close()
})
```

### Multi-Locale Project Configuration

**Use when**: Running the full test suite across multiple locales in CI.
**Avoid when**: You only need to test a single locale or the app does not vary by locale.

**TypeScript**

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

export default defineConfig({
  projects: [
    {
      name: "en-US",
      use: {
        locale: "en-US",
        timezoneId: "America/New_York",
      },
    },
    {
      name: "de-DE",
      use: {
        locale: "de-DE",
        timezoneId: "Europe/Berlin",
      },
    },
    {
      name: "ar-SA",
      use: {
        locale: "ar-SA",
        timezoneId: "Asia/Riyadh",
      },
    },
    {
      name: "ja-JP",
      use: {
        locale: "ja-JP",
        timezoneId: "Asia/Tokyo",
      },
    },
  ],
})
```

**JavaScript**

```javascript
// playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  projects: [
    { name: "en-US", use: { locale: "en-US", timezoneId: "America/New_York" } },
    { name: "de-DE", use: { locale: "de-DE", timezoneId: "Europe/Berlin" } },
    { name: "ar-SA", use: { locale: "ar-SA", timezoneId: "Asia/Riyadh" } },
    { name: "ja-JP", use: { locale: "ja-JP", timezoneId: "Asia/Tokyo" } },
  ],
})
```

### RTL Layout Testing

**Use when**: Your app supports right-to-left languages (Arabic, Hebrew, Persian, Urdu) and you need to verify layout direction, text alignment, and mirrored UI.
**Avoid when**: Your app has no RTL support.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test.describe("RTL layout", () => {
  test("Arabic locale renders RTL layout", async ({ browser }) => {
    const context = await browser.newContext({ locale: "ar-SA" })
    const page = await context.newPage()
    await page.goto("/")

    // Verify the document direction
    const dir = await page.getAttribute("html", "dir")
    expect(dir).toBe("rtl")

    // Verify navigation is right-aligned
    const nav = page.getByRole("navigation", { name: "Main" })
    const navBox = await nav.boundingBox()
    const viewportWidth = page.viewportSize()!.width
    // Nav should start from the right side
    expect(navBox!.x + navBox!.width).toBeGreaterThan(viewportWidth * 0.5)

    // Verify text alignment
    const heading = page.getByRole("heading", { level: 1 })
    const textAlign = await heading.evaluate((el) => window.getComputedStyle(el).textAlign)
    expect(textAlign).toMatch(/right|start/)

    await context.close()
  })

  test("RTL layout does not cause horizontal overflow", async ({ browser }) => {
    const context = await browser.newContext({ locale: "ar-SA" })
    const page = await context.newPage()
    await page.goto("/dashboard")

    // Check for horizontal scrollbar (content overflow)
    const hasHorizontalOverflow = await page.evaluate(() => {
      return document.documentElement.scrollWidth > document.documentElement.clientWidth
    })
    expect(hasHorizontalOverflow).toBe(false)

    await context.close()
  })

  test("icons and directional elements are mirrored in RTL", async ({ browser }) => {
    const context = await browser.newContext({ locale: "ar-SA" })
    const page = await context.newPage()
    await page.goto("/dashboard")

    // Back arrow should point right in RTL
    const backButton = page.getByRole("button", { name: /back|رجوع/i })
    const transform = await backButton.evaluate((el) => window.getComputedStyle(el).transform)
    // CSS transform for horizontal flip: matrix(-1, 0, 0, 1, 0, 0) or scaleX(-1)
    // Or check the logical property direction
    expect(transform).not.toBe("none")

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

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("Arabic locale renders RTL layout", async ({ browser }) => {
  const context = await browser.newContext({ locale: "ar-SA" })
  const page = await context.newPage()
  await page.goto("/")

  const dir = await page.getAttribute("html", "dir")
  expect(dir).toBe("rtl")

  const hasHorizontalOverflow = await page.evaluate(
    () => document.documentElement.scrollWidth > document.documentElement.clientWidth
  )
  expect(hasHorizontalOverflow).toBe(false)

  await context.close()
})
```

### Date, Number, and Currency Format Verification

**Use when**: Your app uses `Intl.DateTimeFormat`, `Intl.NumberFormat`, or similar locale-sensitive APIs.
**Avoid when**: Formats are hardcoded and do not depend on locale.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

const FORMAT_EXPECTATIONS = {
  "en-US": {
    date: /\d{1,2}\/\d{1,2}\/\d{4}/, // 1/15/2025
    number: /1,234,567\.89/, // 1,234,567.89
    currency: /\$[\d,]+\.\d{2}/, // $1,234.56
  },
  "de-DE": {
    date: /\d{1,2}\.\d{1,2}\.\d{4}/, // 15.1.2025
    number: /1\.234\.567,89/, // 1.234.567,89
    currency: /[\d.,]+\s?€/, // 1.234,56 €
  },
  "ja-JP": {
    date: /\d{4}\/\d{1,2}\/\d{1,2}/, // 2025/1/15
    number: /1,234,567\.89/, // 1,234,567.89
    currency: /[¥￥][\d,]+/, // ¥1,235
  },
} as const

for (const [locale, expected] of Object.entries(FORMAT_EXPECTATIONS)) {
  test.describe(`${locale} formatting`, () => {
    test(`dates match ${locale} format`, async ({ browser }) => {
      const context = await browser.newContext({ locale })
      const page = await context.newPage()
      await page.goto("/account")

      const dateText = await page.getByTestId("member-since").textContent()
      expect(dateText).toMatch(expected.date)
      await context.close()
    })

    test(`currency matches ${locale} format`, async ({ browser }) => {
      const context = await browser.newContext({ locale })
      const page = await context.newPage()
      await page.goto("/pricing")

      const priceText = await page.getByTestId("monthly-price").textContent()
      expect(priceText).toMatch(expected.currency)
      await context.close()
    })
  })
}
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

const locales = [
  { locale: "en-US", datePattern: /\d{1,2}\/\d{1,2}\/\d{4}/, currencyPattern: /\$[\d,]+\.\d{2}/ },
  { locale: "de-DE", datePattern: /\d{1,2}\.\d{1,2}\.\d{4}/, currencyPattern: /[\d.,]+\s?€/ },
]

for (const { locale, datePattern, currencyPattern } of locales) {
  test(`${locale} date format`, async ({ browser }) => {
    const context = await browser.newContext({ locale })
    const page = await context.newPage()
    await page.goto("/account")

    const dateText = await page.getByTestId("member-since").textContent()
    expect(dateText).toMatch(datePattern)
    await context.close()
  })
}
```

### Language Switcher Testing

**Use when**: Your app has an in-app language selector that changes the UI language without depending on browser locale.
**Avoid when**: Language is determined purely by browser locale with no user override.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("language switcher changes UI language", async ({ page }) => {
  await page.goto("/")

  // Default language
  await expect(page.getByRole("heading", { level: 1 })).toContainText("Welcome")
  await expect(page.getByRole("button", { name: "Sign in" })).toBeVisible()

  // Switch to French
  await page.getByRole("combobox", { name: /language|langue/i }).selectOption("fr")

  // UI should update to French
  await expect(page.getByRole("heading", { level: 1 })).toContainText("Bienvenue")
  await expect(page.getByRole("button", { name: "Se connecter" })).toBeVisible()

  // Verify language persists after navigation
  await page.getByRole("link", { name: /about|à propos/i }).click()
  await expect(page.getByRole("heading", { level: 1 })).not.toContainText("About")
})

test("language preference persists across sessions", async ({ page, context }) => {
  await page.goto("/")
  await page.getByRole("combobox", { name: /language/i }).selectOption("es")
  await expect(page.getByRole("button", { name: "Iniciar sesión" })).toBeVisible()

  // Reload page — language should persist (cookie/localStorage)
  await page.reload()
  await expect(page.getByRole("button", { name: "Iniciar sesión" })).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("language switcher changes UI language", async ({ page }) => {
  await page.goto("/")

  await expect(page.getByRole("heading", { level: 1 })).toContainText("Welcome")

  await page.getByRole("combobox", { name: /language/i }).selectOption("fr")

  await expect(page.getByRole("heading", { level: 1 })).toContainText("Bienvenue")
  await expect(page.getByRole("button", { name: "Se connecter" })).toBeVisible()
})
```

### Translation Completeness Checks

**Use when**: Verifying that all visible UI strings are translated and no fallback keys leak into the UI.
**Avoid when**: You have a build-time translation validation step that already catches missing keys.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

const LANGUAGES = ["en", "fr", "de", "es", "ja"]
const PAGES_TO_CHECK = ["/", "/login", "/dashboard", "/settings", "/pricing"]

for (const lang of LANGUAGES) {
  test.describe(`${lang} translation completeness`, () => {
    for (const pagePath of PAGES_TO_CHECK) {
      test(`no missing translations on ${pagePath}`, async ({ page }) => {
        // Set language via URL param, cookie, or language switcher
        await page.goto(`${pagePath}?lang=${lang}`)

        // Check for common translation key leak patterns
        const pageText = await page.textContent("body")

        // Translation keys typically look like: key.subkey, UPPER_SNAKE_CASE, or {{key}}
        expect(pageText).not.toMatch(/\b[a-z]+\.[a-z]+\.[a-z]+\b/) // dot.notation.keys
        expect(pageText).not.toContain("{{") // Unresolved templates
        expect(pageText).not.toContain("}}")
        expect(pageText).not.toMatch(/\bTODO\b/i) // Placeholder text

        // Check for untranslated English text when in non-English locale
        if (lang !== "en") {
          // These common English strings should be translated
          const untranslated = ["Sign in", "Log out", "Settings", "Dashboard", "Submit"]
          for (const text of untranslated) {
            const count = await page.getByText(text, { exact: true }).count()
            // Allow 0 matches (element not on page) but flag exact English matches
            if (count > 0) {
              console.warn(`Possible untranslated text "${text}" found on ${pagePath} for ${lang}`)
            }
          }
        }
      })
    }
  })
}
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

const LANGUAGES = ["en", "fr", "de"]
const PAGES = ["/", "/login", "/dashboard"]

for (const lang of LANGUAGES) {
  for (const pagePath of PAGES) {
    test(`${lang}: no missing translations on ${pagePath}`, async ({ page }) => {
      await page.goto(`${pagePath}?lang=${lang}`)

      const pageText = await page.textContent("body")
      expect(pageText).not.toMatch(/\b[a-z]+\.[a-z]+\.[a-z]+\b/)
      expect(pageText).not.toContain("{{")
      expect(pageText).not.toContain("}}")
    })
  }
}
```

### Timezone Testing

**Use when**: Your app displays time-sensitive data (event times, deadlines, scheduling) and you need to verify correct timezone rendering.
**Avoid when**: All times are displayed in UTC with no local conversion.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test.describe("timezone rendering", () => {
  test("event times adjust to user timezone", async ({ browser }) => {
    // Event stored as 2025-03-15T14:00:00Z (2 PM UTC)
    const contextNY = await browser.newContext({
      locale: "en-US",
      timezoneId: "America/New_York", // UTC-5 in March (EST)
    })
    const pageNY = await contextNY.newPage()
    await pageNY.goto("/events/123")
    // Should display 9:00 AM
    await expect(pageNY.getByTestId("event-time")).toContainText("9:00 AM")
    await contextNY.close()

    const contextTokyo = await browser.newContext({
      locale: "en-US",
      timezoneId: "Asia/Tokyo", // UTC+9
    })
    const pageTokyo = await contextTokyo.newPage()
    await pageTokyo.goto("/events/123")
    // Should display 11:00 PM
    await expect(pageTokyo.getByTestId("event-time")).toContainText("11:00 PM")
    await contextTokyo.close()
  })

  test("deadline displays correctly across DST boundary", async ({ browser }) => {
    const context = await browser.newContext({
      locale: "en-US",
      timezoneId: "America/Los_Angeles",
    })
    const page = await context.newPage()

    // Test a deadline that crosses DST (March second Sunday)
    await page.goto("/tasks?deadline=2025-03-10T07:00:00Z")
    // Before DST: UTC-8, so 11 PM on March 9
    await expect(page.getByTestId("deadline")).toContainText("Mar 9")

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

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("event times adjust to user timezone", async ({ browser }) => {
  const context = await browser.newContext({
    locale: "en-US",
    timezoneId: "America/New_York",
  })
  const page = await context.newPage()
  await page.goto("/events/123")
  await expect(page.getByTestId("event-time")).toContainText("9:00 AM")
  await context.close()
})
```

### Multi-Language Screenshot Comparison

**Use when**: Catching visual layout regressions caused by text expansion, RTL mirroring, or font rendering differences across locales.
**Avoid when**: Visual regression testing is handled separately and locale is not a layout risk.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

const LOCALES_TO_SCREENSHOT = [
  { locale: "en-US", name: "english" },
  { locale: "de-DE", name: "german" }, // German text is ~30% longer than English
  { locale: "ja-JP", name: "japanese" }, // CJK characters, different font metrics
  { locale: "ar-SA", name: "arabic" }, // RTL layout
]

for (const { locale, name } of LOCALES_TO_SCREENSHOT) {
  test(`visual snapshot for ${name} (${locale})`, async ({ browser }) => {
    const context = await browser.newContext({
      locale,
      viewport: { width: 1280, height: 720 },
    })
    const page = await context.newPage()
    await page.goto("/")

    // Wait for fonts and images to load
    await page.waitForLoadState("networkidle")

    await expect(page).toHaveScreenshot(`homepage-${name}.png`, {
      maxDiffPixelRatio: 0.02, // Allow 2% pixel difference for font rendering
      fullPage: true,
    })

    await context.close()
  })
}

test("long German text does not overflow buttons", async ({ browser }) => {
  const context = await browser.newContext({ locale: "de-DE" })
  const page = await context.newPage()
  await page.goto("/dashboard")

  // Check that no button has overflowing text
  const buttons = page.getByRole("button")
  const count = await buttons.count()
  for (let i = 0; i < count; i++) {
    const button = buttons.nth(i)
    const overflow = await button.evaluate((el) => {
      const style = window.getComputedStyle(el)
      return el.scrollWidth > el.clientWidth && style.overflow !== "hidden"
    })
    if (overflow) {
      const text = await button.textContent()
      expect(overflow, `Button "${text}" overflows in German`).toBe(false)
    }
  }

  await context.close()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

const LOCALES = [
  { locale: "en-US", name: "english" },
  { locale: "de-DE", name: "german" },
  { locale: "ar-SA", name: "arabic" },
]

for (const { locale, name } of LOCALES) {
  test(`visual snapshot for ${name}`, async ({ browser }) => {
    const context = await browser.newContext({ locale, viewport: { width: 1280, height: 720 } })
    const page = await context.newPage()
    await page.goto("/")
    await page.waitForLoadState("networkidle")

    await expect(page).toHaveScreenshot(`homepage-${name}.png`, {
      maxDiffPixelRatio: 0.02,
      fullPage: true,
    })
    await context.close()
  })
}
```

## Decision Guide

| Scenario                                   | Approach                                                | Why                                                             |
| ------------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------- |
| Test locale-dependent formatting           | Set `locale` in browser context                         | Playwright sets `navigator.language` and affects `Intl` APIs    |
| Test app language switcher                 | Interact with the switcher UI directly                  | Tests the actual user workflow, not just browser locale         |
| Test timezone rendering                    | Set `timezoneId` in browser context                     | Overrides `Date` and `Intl.DateTimeFormat` timezone             |
| Catch text overflow from long translations | Visual regression + bounding box checks                 | German/Finnish text is 30-40% longer than English               |
| Verify RTL layout                          | Set Arabic/Hebrew locale + assert `dir="rtl"`           | Tests both browser signal and app response                      |
| Catch missing translations                 | Scan page text for key patterns (`{{`, dot notation)    | Catches build/deploy issues where translation files are missing |
| Compare layouts across locales             | `toHaveScreenshot` per locale with project-based config | Captures visual differences automatically                       |
| Test DST edge cases                        | Set specific `timezoneId` + known date boundaries       | DST boundaries cause the most timezone bugs                     |

## Anti-Patterns

| Don't Do This                                        | Problem                                            | Do This Instead                                                                 |
| ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- |
| Hardcoding translated text in assertions             | Breaks when translations change                    | Use `getByRole` with `name` regex, or test IDs for locale-independent selection |
| Testing only `en-US`                                 | Misses RTL, text overflow, and format bugs         | Test at least one LTR, one RTL, and one CJK locale                              |
| Setting `locale` on the page instead of context      | `locale` is a context-level option, not page-level | Set locale when creating the context or in project config                       |
| Ignoring text expansion for German/Finnish           | Buttons and labels overflow in longer languages    | Use visual regression or bounding box assertions                                |
| Using `toHaveScreenshot` without `maxDiffPixelRatio` | Font rendering differs slightly across OS/CI       | Set `maxDiffPixelRatio: 0.02` or higher for cross-platform tolerance            |
| Testing timezone only in UTC                         | Masks timezone conversion bugs                     | Test with at least 3 timezones: UTC-negative, UTC, UTC-positive                 |
| Relying on browser locale for app language           | Many apps use server-side or cookie-based language | Test via the app's own language switching mechanism                             |
| Not testing DST boundaries                           | Time displayed can be off by 1 hour at transitions | Test dates near DST transitions for your target timezones                       |

## Troubleshooting

| Symptom                                         | Likely Cause                                                     | Fix                                                                            |
| ----------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `locale` option has no effect                   | App ignores `navigator.language` and uses server-side locale     | Set locale through the app's own mechanism (cookie, URL param, API)            |
| Date format does not change with locale         | App hardcodes date format instead of using `Intl.DateTimeFormat` | This is an app bug to fix, not a test issue                                    |
| RTL page still renders LTR                      | App checks locale but does not set `dir="rtl"`                   | Verify the app's RTL detection logic; may need to set `Accept-Language` header |
| Visual screenshots fail across OS               | Font rendering differs between macOS, Linux, Windows             | Run visual tests in Docker for consistency, or increase `maxDiffPixelRatio`    |
| `timezoneId` does not affect page               | App uses server time, not client `Date`                          | Timezone testing only works for client-side date rendering                     |
| Translation key appears briefly then disappears | Translation files load asynchronously                            | Wait for `networkidle` or a specific translated element before asserting       |
| Character encoding issues (garbled text)        | Incorrect charset in HTML or missing font                        | Verify `<meta charset="utf-8">` and that CJK/Arabic fonts are available        |

## Related

- [core/locators.md](locators.md) -- locator strategies that work across locales
- [core/configuration.md](configuration.md) -- project-level locale and timezone configuration
- [core/visual-regression.md](visual-regression.md) -- screenshot comparison fundamentals
- [core/clock-and-time-mocking.md](clock-and-time-mocking.md) -- mocking time for date-dependent testing
- [ci/docker-and-containers.md](../ci/docker-and-containers.md) -- consistent font rendering in CI with Docker