Stats
Actions
Tags
From qa-localization
Build-an-X workflow for verifying RTL (right-to-left) layouts - runs the test suite under Arabic / Hebrew / Persian / Urdu locales, asserts the `dir="rtl"` attribute is set, verifies layout mirrors correctly (text alignment, icon positions, scrollbar location), uses logical CSS properties (`start`/`end` over `left`/`right`) per W3C guidance, captures per-locale screenshots for visual review. Use when the app supports RTL languages.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qa-localization:rtl-rendering-testerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Per [w3-rtl][w3rtl]:
Per w3-rtl:
"If the overall document direction is right-to-left, add
dir='rtl'to thehtmltag."
The dir attribute is the standard way to signal direction. Per
w3-rtl, it affects:
- Paragraphs and blocks align right
- Bidirectional text flows correctly right-to-left
- Punctuation appears in correct positions
- Table columns progress right-to-left
- Form inputs start at the right by default
Common RTL languages: Arabic, Hebrew, Persian, Urdu.
This skill verifies the app handles RTL correctly.
dir attribute presenceimport { test, expect } from '@playwright/test';
test.use({ extraHTTPHeaders: { 'Accept-Language': 'ar' } });
test('Arabic locale sets dir=rtl on <html>', async ({ page }) => {
await page.goto('/');
const dir = await page.locator('html').getAttribute('dir');
expect(dir).toBe('rtl');
});
test('Hebrew locale sets dir=rtl on <html>', async ({ page }) => {
await page.goto('/?lng=he');
await expect(page.locator('html')).toHaveAttribute('dir', 'rtl');
});
Per w3-rtl: the html-level dir is the canonical
signal; CSS-only direction setting is incorrect:
"Do not use CSS to apply base direction in HTML pages. Direction is semantic content and should reside in markup, not styling."
test('text aligns right in RTL', async ({ page }) => {
await page.goto('/?lng=ar');
const heading = page.locator('h1').first();
const align = await heading.evaluate(el => getComputedStyle(el).textAlign);
expect(['right', 'start']).toContain(align); // 'start' resolves to right in RTL
});
Per w3-rtl: prefer logical properties (start, end)
over directional (left, right) so the layout flips automatically.
Common RTL gotchas:
test('back arrow mirrors in RTL', async ({ page }) => {
await page.goto('/cart?lng=ar');
const backArrow = page.getByRole('link', { name: /back/i });
const transform = await backArrow.evaluate(el => getComputedStyle(el).transform);
// RTL should apply scaleX(-1) (or use a different mirrored asset)
expect(transform).toContain('-1');
});
Mixed LTR + RTL content is a common bidi issue:
"My order #ORD-12345 has shipped."
In Arabic locale, the order number "ORD-12345" must remain LTR inside the RTL paragraph. Without proper bidi markers, the ordering can flip.
test('order number preserves LTR direction inside RTL paragraph', async ({ page }) => {
await page.goto('/orders/ORD-12345?lng=ar');
const paragraph = page.locator('p').filter({ hasText: 'ORD-12345' });
const orderNumber = paragraph.locator('bdi, [dir="ltr"]');
await expect(orderNumber).toBeVisible();
await expect(orderNumber).toHaveText('ORD-12345');
});
The <bdi> element or dir="ltr" on a span isolates LTR text
within an RTL block - without it, browser bidi heuristics may
flip.
Per w3-rtl: in RTL, "Form inputs start at the right by default."
test('form inputs start at right in RTL', async ({ page }) => {
await page.goto('/checkout?lng=he');
const emailField = page.getByLabel(/email/i);
await emailField.click();
// Cursor / placeholder text should be at the right edge
// (assert via screenshot or computed-style direction)
await expect(emailField).toHaveCSS('text-align', /(right|start)/);
});
test('home page Arabic snapshot', async ({ page }) => {
await page.goto('/?lng=ar');
await expect(page).toHaveScreenshot('home-ar.png');
});
test('home page Hebrew snapshot', async ({ page }) => {
await page.goto('/?lng=he');
await expect(page).toHaveScreenshot('home-he.png');
});
RTL screenshots catch regressions like:
- name: RTL rendering tests
run: npx playwright test e2e/rtl/ --project=mobile-iphone-15 --project=desktop-chromium
- uses: actions/upload-artifact@v4
if: failure()
with:
name: rtl-screenshots
path: test-results/
Run on both desktop and mobile profiles - RTL handling can differ per breakpoint.
dirname for form submissionPer w3-rtl: "Use dir='auto' to automatically detect
text direction from the first strongly-typed character. Pair with
the dirname attribute to send information about direction to the
server in addition to the usual form data."
Verify forms submitted from RTL contexts include the direction information when needed:
test('comment form sends direction with submission', async ({ page }) => {
await page.goto('/post/123?lng=ar');
await page.getByLabel(/comment/i).fill('مرحبا — hello');
// Listen for the form submission
const responsePromise = page.waitForResponse('/api/comments');
await page.getByRole('button', { name: /submit/i }).click();
const response = await responsePromise;
// The form's `dirname` attribute should send a separate field with the direction
expect(response.request().postData()).toContain('comment.dir=rtl');
});
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| CSS-only direction | Per w3-rtl: "Do not use CSS to apply base direction." | dir="rtl" on the html tag (Step 1). |
Hardcoded left / right in CSS | Doesn't mirror in RTL. | Logical properties (start / end) per w3-rtl. |
| Mirroring brand logos / icons with embedded text | Brand recognition + readability suffer. | Per-asset decision; not all icons mirror. |
Order numbers / IDs without <bdi> / dir="ltr" isolation | Bidi heuristics may flip; "ORD-12345" becomes "12345-ORD". | Wrap in <bdi> (Step 4). |
| Skipping per-locale visual regression | Regressions visible only when RTL activated. | Per-locale screenshots (Step 6). |
dir attribute, RTL effects, semantic
vs CSS direction, dirname attribute.pseudo-localization-runner - sibling: layout-level i18n testing including RTL pseudo-loc
variant.i18n-string-coverage -
source-scan complement.playwright-snapshots - visual regression for catching RTL layout issues.npx claudepluginhub testland/qa --plugin qa-localizationProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.