RTL Testing for Arabic Interfaces

Start with dir and lang

Every RTL page needs two attributes on its root element: lang, which declares the language (ar, or ar-SA), and dir="rtl", which sets the base direction. The W3C internationalization guidance is to set direction with the dir attribute in the markup, not with the CSS direction property alone, because direction is part of the content’s meaning and must survive when styles are missing, when content is copied, and when it is read by assistive technology. The same applies to HTML emails and to templates that generate PDFs.

The lang attribute does more than document the language: it lets a screen reader choose an Arabic voice, lets the browser pick suitable fonts, and drives the :lang() selector used for script-specific styling. A page marked lang="en" and dir="rtl" is a defect even when it looks right.

• Check the root element on every page, including error pages, emails, printable views and PDFs.
• Switch the language at runtime and back again: direction, fonts and cached layout must all change, with no screen left half-mirrored.

What mirrors and what does not

In a right-to-left layout the reading flow starts at the right, so the interface mirrors along the vertical axis. Apple’s Human Interface Guidelines give a practical rule set: flip controls that show progress from one value to another (sliders, progress indicators), controls that navigate through items in a fixed order (back and next), and icons that represent text or reading direction or forward and backward motion; reverse the order of images when the order is meaningful. Do not flip photographs and artwork, logos and universal marks such as the check mark, icons that depict real-world objects such as a clock, controls that refer to a real physical direction, or the digits inside a single number such as a phone or card number.

Media playback is a deliberate exception on many platforms: Material Design’s bidirectionality guidance, which Android’s documentation points to, keeps playback controls and the media progress bar left-to-right because they reflect the direction of the media being played (the tape), not the direction of time. Whatever your product decides, write it in the design specification and test against that decision, because inconsistent handling between screens is the actual defect. Source code, terminal output and mathematical expressions also stay left-to-right.

• Mirror: page layout, navigation drawers, tab order, breadcrumbs, back/forward arrows, steppers, carousels, progress bars, sliders, chevrons in lists, table column order, the position of icons relative to their labels.
• Do not mirror: logos, check marks, clocks and circular refresh icons that depict real clockwise motion, photos, maps, phone and card numbers, code blocks, charts whose axis represents time unless the design says so.

CSS logical properties and platform layout

Most mirroring defects come from physical layout code. CSS properties such as margin-left, padding-right, left, right and text-align: left stay on the same side whatever the direction; their logical equivalents — margin-inline-start, padding-inline-end, inset-inline-start, text-align: start — follow the writing direction. Flexbox and grid follow the direction automatically; absolute positioning, transforms, background positions and shadow offsets do not. Directional icons need an explicit flip, and only directional ones.

Mobile platforms have the same concept under other names. On Android, the app declares android:supportsRtl="true", layouts use start and end instead of left and right, and simple directional drawables can set android:autoMirrored="true". On iOS, Auto Layout’s leading and trailing constraints mirror while left and right constraints do not, and directional images must be marked to flip for right-to-left layouts. A tester does not need to write this code, but recognising physical properties in a review or in the developer tools explains most "this element did not move" defects.

/* Physical properties: do not mirror */
.card   { margin-left: 16px; text-align: left; }
.badge  { position: absolute; right: 8px; }

/* Logical properties: follow the writing direction */
.card   { margin-inline-start: 16px; text-align: start; }
.badge  { position: absolute; inset-inline-end: 8px; }
.list   { padding-inline-start: 24px; border-inline-end: 1px solid; }

/* Directional icons flip explicitly; logos, check marks and media icons do not */
[dir="rtl"] .icon-chevron-next { transform: scaleX(-1); }

/* Arabic text: no letter-spacing, room for diacritics */
:lang(ar) { letter-spacing: 0; line-height: 1.8; }

Bidirectional text and the Unicode Bidirectional Algorithm

Arabic sentences routinely contain left-to-right content: English brand names, order numbers, SKUs, email addresses, URLs, phone numbers and code. The display order is decided by the Unicode Bidirectional Algorithm (UAX #9). At a practical level, characters are strong (Arabic and Latin letters have a direction), weak (digits and some separators) or neutral (spaces and most punctuation). Neutrals between runs of different directions, and at the edge of a paragraph, take the base direction — which is why punctuation after an English phrase jumps to the wrong side. Numbers follow further rules: digits that come after Arabic letters are given the bidi type Arabic Number (AN), though their glyphs do not change, and a hyphen or space between such numbers, or a plus sign in front of them, resolves to right-to-left, so each group of digits is laid out as its own run — which is why a hyphenated order number or a spaced phone number can be displayed with its parts reordered inside an Arabic sentence.

The fix is isolation. In HTML, wrap embedded content of known direction in an element with its own dir, use <bdi> or dir="auto" for content whose direction is not known in advance (user names, reviews, search terms), and put dir="auto" on free-text input fields. Outside HTML — in plain-text notifications, SMS or native strings — the Unicode isolate controls (U+2066 LRI, U+2067 RLI, U+2068 FSI, closed by U+2069 PDI) do the same job. The older embedding controls (U+202A–U+202E) are harder to use correctly and can affect the text that follows them.

• Build a bidi test set: Arabic sentences with an English brand at the start, middle and end; with an order number, email, URL and phone number; with numbers followed by units or percent signs; with parentheses and quotation marks.
• Inspect invisible characters: a string that "looks right" may carry stray direction marks copied from another system; decode it to code points to see them.

<!-- page: base direction and language on the root element -->
<html lang="ar" dir="rtl">

<!-- order number that must keep its order -->
<p>رقم الطلب: <bdi dir="ltr">2026-0042</bdi></p>

<!-- identifiers that must always read left-to-right -->
<p>للتواصل: <span dir="ltr">+966 50 123 4567</span></p>

<!-- user-generated text of unknown direction -->
<p dir="auto">{review.text}</p>

<!-- English phrase inside Arabic: direction and pronunciation -->
<p>جرّب أداة <bdi lang="en">Mutqan Tools!</bdi> مجاناً</p>

Without isolation, an RTL paragraph can display (example):
  2026-0042            as  0042-2026
  +966 50 123 4567     as  4567 123 50 966+
  Mutqan Tools!        as  !Mutqan Tools

Try it: Unicode Decoder Try it: Unicode Encoder Try it: Multilingual Test Data Generator

Arabic rendering: shaping, fonts, diacritics and truncation

Arabic is cursive: most letters take a different form depending on whether they stand alone or join the letter before, after, or both, and some pairs such as lam-alef (لا) form a mandatory ligature. The shaping engine chooses these forms, and anything that interferes with it produces disconnected letters. Letter-spacing on Arabic text is a classic cause — depending on the engine it inserts gaps that break the joins or is simply ignored — so the safe rule is letter-spacing: 0 for Arabic. Inserting a character inside a word (a zero-width non-joiner, a masking character, a soft hyphen), drawing text one character at a time for an animation, or highlighting part of a word with separate styling can also break joining on some engines.

Generated output is where rendering fails most often. PDF generators, chart libraries, canvas drawing and image watermarks without an Arabic shaping step typically show Arabic as isolated letters in reverse order. Fonts matter too: a Latin-first font with an Arabic fallback can mix sizes and baselines, and Apple’s guidance notes that Arabic next to all-caps Latin can look too small and may need a slightly larger size. Diacritics (tashkeel), as in the example word مُتْقَن, extend above and below the line, so fixed line heights and hidden overflow clip them. When text is truncated, the ellipsis must sit at the logical end of the text — on the left for Arabic — which only happens when the element’s direction is set correctly.

• Use realistic Arabic: long names, words with diacritics, lam-alef, the tatweel (ـ) that some users type, Arabic-Indic digits and Arabic punctuation (، ؛ ؟).
• Check headings, buttons, badges, tooltips, charts, PDFs, emails and push notifications — not only the main page body.

Try it: Arabic Test Data Generator Try it: Fake Name Generator Try it: String Length Counter

RTL forms

Forms combine every RTL difficulty in one place. Labels, required-field markers, help text and error messages move to the mirrored side; free-text fields for Arabic follow the content direction; and fields that hold identifiers stay left-to-right in every locale: phone numbers, email addresses, URLs, IBANs, card numbers, national ID and residence numbers, postal codes and verification codes. Decide how those LTR fields are aligned inside the RTL form and apply it consistently. Hint text shown inside an empty field must match the direction of what the user will type, otherwise the text jumps to the other side when typing starts.

Validation must speak the user’s language: client-side and server-side messages, messages for each rule (required, format, length, range), and messages generated by third-party components such as payment widgets. Numeric fields need a decision about Arabic-Indic digits — an Arabic keyboard can produce them — and the product must either accept and normalise them or reject them with a clear Arabic message. For example, try a Saudi mobile number in local and international form (such as 05XXXXXXXX and +9665XXXXXXXX), and try national ID, Iqama and phone fields with the same digits typed on an Arabic keyboard ("٠٥٠١٢٣٤٥٦٧"); a field that neither accepts them nor explains the rule in Arabic is a defect.

• Date pickers: the calendar grid runs right-to-left, month arrows are mirrored, and Hijri or Gregorian selection follows the product’s rule.
• Checkboxes, radio buttons and toggles sit on the right of their labels; toggle "on" direction follows the design decision.
• Addresses: test with generated Saudi National Address–style data, where building number, street, district, city, postal code and additional number mix Arabic words with Western digits.

Try it: Saudi Address Test Data Try it: Arabic Test Data Generator Try it: Special Character Dataset Generator

Accessibility in RTL interfaces

Screen readers depend on lang. WCAG 2.2 success criterion 3.1.1 Language of Page requires the page language to be programmatically determinable, and 3.1.2 Language of Parts requires the same for passages and phrases in another language, with exceptions that include proper names and technical terms. An English sentence inside Arabic text therefore needs lang="en"; marking English brand names and terms the same way is good practice even though the criterion does not require it, because without it a screen reader reads them with Arabic pronunciation rules. Test with the screen readers your users have (NVDA or JAWS on Windows, VoiceOver on Apple devices, TalkBack on Android) with an Arabic voice installed.

Reading order and focus order follow the DOM. When mirroring is done with logical properties and dir, the DOM order stays meaningful and the visual order mirrors with it. When a layout is faked with row-reverse, order or absolute positioning, the visual order and the focus order disagree, which conflicts with WCAG 1.3.2 Meaningful Sequence and 2.4.3 Focus Order. Also check that horizontal arrow-key behaviour in tabs, sliders and carousels matches the mirrored visual direction, and that accessible names of icon buttons are translated.

RTL test checklist

Run this list for every screen in Arabic on each target browser and device class. Record the decisions it asks for (media controls, LTR field alignment, digit handling) in the design specification so every tester checks against the same rule.

RTL test checklist (ar, ar-SA)

Direction and language
[ ] <html lang="ar" dir="rtl"> on every page, email and PDF template
[ ] Switching language flips direction without a reload glitch or mixed state
Mirroring
[ ] Navigation, back/next arrows, breadcrumbs, steppers, sliders, progress bars mirror
[ ] Logos, check marks, clocks, photos, phone numbers, code do not mirror
[ ] Media playback controls follow the product's documented decision
Bidirectional text
[ ] Order numbers, SKUs, emails, URLs, phone numbers keep their order in Arabic sentences
[ ] Punctuation stays on the correct side of embedded English phrases
[ ] User content with unknown direction is shown with dir="auto" or <bdi>
Rendering
[ ] Arabic letters join (no letter-spacing, no characters inserted inside words)
[ ] Diacritics are not clipped; truncation ellipsis sits at the logical end
[ ] Arabic renders correctly in PDFs, emails, charts and canvas output
Forms
[ ] Labels, required markers, errors and hint text sit on the correct side
[ ] Phone, email, IBAN, ID and code fields are LTR; free-text fields follow content
[ ] Arabic-Indic digits are accepted or rejected with a clear Arabic message
Accessibility
[ ] Screen reader uses an Arabic voice; English phrases carry lang="en"
[ ] Focus order and reading order match the mirrored visual order

Automating RTL checks

Automation catches regressions in direction and layout well and linguistic problems poorly. Run the end-to-end smoke suite in the Arabic locale as well as English; assert the root dir and lang; check the position of a few anchor elements (the back link belongs on the right); assert that embedded identifiers are isolated; and add per-locale screenshot comparison for key screens, because text assertions read the DOM and cannot see visual reordering. A search for physical CSS properties in the stylesheets finds mirroring defects before they reach a screen.

On Android, the AR (XB) pseudo-locale switches a debug build to right-to-left with reversed English text, and the developer option to force RTL layout direction flips the layout without changing the language. Xcode offers a right-to-left pseudolanguage in the scheme’s app-language options.

// RTL smoke check (Playwright Test)
test("checkout is laid out right-to-left in Arabic", async ({ browser }) => {
  const page = await (await browser.newContext({ locale: "ar-SA" })).newPage();
  await page.goto("/ar/checkout");

  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");
  await expect(page.locator("html")).toHaveAttribute("lang", /^ar/);

  // the back link sits in the right half of the viewport
  const box = await page.getByRole("link", { name: "رجوع" }).boundingBox();
  expect(box.x).toBeGreaterThan(page.viewportSize().width / 2);

  // the order id is isolated; text assertions cannot see visual reordering
  await expect(page.getByTestId("order-id")).toHaveAttribute("dir", "ltr");

  await expect(page).toHaveScreenshot("checkout-ar.png");
});

# Find physical CSS that will not mirror (review each hit)
grep -rnE "margin-(left|right)|padding-(left|right)|text-align: *(left|right)|float: *(left|right)|[^-](left|right): *[0-9]" src/

RTL defect examples, written as bug titles

These are illustrative examples, not real incidents. Each names the symptom, the place and the condition, as described in the bug report guide.

• Order number 2026-0042 displays as 0042-2026 in the Arabic order summary
• Phone number shown with its digit groups reversed on the Arabic profile page
• Exclamation mark appears before the English brand name in the Arabic success message
• Back arrow in the Arabic checkout header points left and returns to the next step
• Arabic letters disconnected in section headings styled with letter-spacing: 0.1em
• Invoice PDF renders the Arabic customer name as isolated letters in reverse order
• Diacritics on Arabic product names clipped by the card’s fixed line height
• Mobile number field rejects Arabic-Indic digits with an English-only error message
• Screen reader pronounces the English brand name with Arabic rules — lang="en" missing

Frequently asked questions

References

• Unicode Standard Annex #9: Unicode Bidirectional AlgorithmUnicode ConsortiumThe algorithm that decides the display order of mixed right-to-left and left-to-right text — the source of most bidirectional-text bugs.
• Structural markup and right-to-left text in HTMLW3CHow to set base direction with the dir attribute on html and structural elements, and why CSS alone should not be used for it.
• Inline markup and bidirectional text in HTMLW3CHow the bidirectional algorithm treats inline runs — numbers, names, URLs inside Arabic text — and the markup (bdi, dir) that isolates them.
• Arabic & Persian Layout RequirementsW3C · 2025The layout and typography requirements of the Arabic script — direction, joining, justification, numerals — that software must support (a W3C Draft Note).
• Right to left — Human Interface GuidelinesAppleApple's guidance on flipping an interface for right-to-left languages: which elements mirror, which do not, and how text and numbers behave.
• Support different languages and culturesAndroid Developers (Google)Localising Android apps: locale resources, layout mirroring for right-to-left languages and RTL-aware attributes.
• Web Content Accessibility Guidelines (WCAG) 2.2W3C · 2024The W3C Recommendation that defines the testable success criteria for accessible web content, organised under four principles and three conformance levels (A, AA, AAA).
• Internationalization (i18n) ActivityW3CW3C's internationalization articles, tutorials and checks for building and testing multilingual web content.