Arabic and RTL localization engineering guide

What RTL support does—and does not—do

Right-to-left support changes the base direction used to lay out text and directional UI. Modern Apple, Android, and web frameworks can mirror leading/trailing relationships and apply the Unicode bidirectional algorithm. They cannot decide whether a custom icon should mirror, rewrite a fixed left/right constraint, or make an inflexible component fit longer Arabic copy.

Framework responsibility

Resolve base direction, shape Arabic glyphs, reorder bidirectional runs, expose locale-aware formatting, and mirror directional primitives when configured correctly.

Application responsibility

Use leading/trailing constraints, mark language and direction, isolate mixed-direction values, allow text growth, and test every important screen in RTL.

Localization-content responsibility

Provide natural Arabic, preserve placeholders and markup, select correct plural forms, and avoid embedding layout assumptions in translated text.

GoLocalise responsibility

Store regional locales such as ar-LB, validate placeholders and plurals, publish versioned text artifacts, and let SDKs retain cache and bundled fallback. It does not repair UI layout or mirroring bugs.

Direction and layout mirroring

Prefer semantic direction over physical coordinates. In iOS, use leading and trailing anchors and verify SwiftUI environment direction. In Android and Compose, use start/end padding and alignment rather than left/right. On the web, set an accurate lang and dir at the document or component boundary.

Directional icons such as back arrows often mirror; logos, media play controls, clocks, and some charts often do not. Make that choice per asset rather than mirroring an entire rendered screen.

Mixed Arabic and Latin text

Order IDs, email addresses, URLs, model numbers, and Latin brand names create left-to-right runs inside Arabic sentences. Punctuation may appear on an unexpected side when those runs are not isolated. Keep machine identifiers separate from prose where possible and use the platform's bidirectional isolation APIs.

Web bidirectional isolation

<p dir="rtl" lang="ar">
  رقم الطلب <bdi>GL-2048</bdi>
</p>

Do not insert arbitrary invisible direction marks until the problem is reproduced and understood. Hidden marks are difficult to review and can move punctuation differently across platforms.

Numbers, punctuation, placeholders, and plurals

Arabic interfaces may use Western or Arabic-Indic digits depending on product requirements and locale. Format dates, currency, decimals, and counts with locale-aware platform APIs instead of concatenating fragments. Keep punctuation inside the translated sentence so the translator controls its placement.

Stable placeholder contract

// Keep the identifier and placeholders stable.
"order.status" = "الطلب {0} سيصل خلال {count} أيام";

// Example values:
// {0}     → GL-2048
// {count} → 3

A translated value must preserve the source placeholder contract. GoLocalise supports canonical positional placeholders and locale-aware plural categories. Arabic commonly needs zero, one, two, few, many, and other forms; test actual counts rather than checking only singular and plural labels.

Text expansion and truncation

Arabic is not uniformly shorter or longer than English. Font metrics, shaping, line height, and translated phrasing all affect layout. Avoid fixed-width text containers, permit multiple lines where the design allows, and test accessibility font sizes. A screenshot at one device width is not sufficient evidence.

How should Arabic RTL localization be tested?

Test a real Arabic locale, not only forced visual mirroring.
Check navigation, forms, lists, dialogs, empty states, and errors.
Use strings containing Latin IDs, email, phone numbers, and punctuation.
Exercise zero, one, two, few, many, and other plural counts.
Check clipping at small widths and large accessibility text sizes.
Verify focus order, screen-reader labels, and keyboard navigation.
Start offline and confirm bundled Arabic fallback remains readable.
Refresh copy and confirm the UI—not just the data—still behaves correctly.

Platform setup details are covered in the iOS guide and Android guide.

Updating Arabic copy safely

Treat copy changes like releases: review placeholders and plural forms, preview the relevant screens, publish to a non-production environment, and promote only the reviewed snapshot. OTA delivery can shorten the copy-release cycle, but it cannot replace UI testing. If a published translation is wrong, an immutable rollback release restores known content without rewriting history.