Rtl Internationalization

RTL (Right-to-Left) Internationalization

Supporting RTL languages such as Hebrew, Arabic, Persian, and Urdu requires building layouts with direction-agnostic CSS and treating text direction as a first-class, runtime-switchable property rather than a fixed assumption baked into left/right styles.

Workflow for Making a UI RTL-Safe

1. Audit for physical properties — Search the codebase for margin-left/right, padding-left/right, left/right positioning, text-align: left/right, and Tailwind classes like ml-*, mr-*, pl-*, pr-*, left-*, right-*.
2. Convert to logical properties — Replace each physical property/class with its logical equivalent (margin-inline-start, ms-*, etc.) so the browser flips it automatically based on dir.
3. Set direction at the root — Apply dir="rtl" (or dir="auto") on <html> or a top-level container, driven by the active locale, not hardcoded per component.
4. Handle mixed-script text — Wrap user-generated or interpolated strings that may differ in direction from the surrounding text with <bdi>.
5. Audit icons and directional components — Mirror arrows, chevrons, and back/forward buttons; leave non-directional icons (search, settings, home) unmirrored; reverse carousels, sliders, and progress bars.
6. Externalize all strings — Route every user-facing string through a translation function and use Intl APIs for numbers, currency, and dates instead of manual formatting.
7. Test in RTL — Render the app with dir="rtl" and real RTL content (not just mirrored LTR placeholder text) and visually verify every screen.

Logical CSS Properties

Always use CSS logical properties instead of physical ones — logical properties resolve to the correct physical side automatically based on the element's direction and writing-mode, so the same stylesheet works for LTR and RTL without duplication.

/* Before: breaks in RTL */
.card {
  margin-left: 1rem;
  padding-right: 1.5rem;
  border-left: 2px solid var(--border);
  text-align: left;
}

/* After: direction-agnostic */
.card {
  margin-inline-start: 1rem;
  padding-inline-end: 1.5rem;
  border-inline-start: 2px solid var(--border);
  text-align: start;
}

Tailwind CSS Logical Classes

Use Tailwind's logical utilities instead of the directional (l/r) ones:

• ms-4 instead of ml-4 (margin-inline-start)
• me-4 instead of mr-4 (margin-inline-end)
• ps-4 instead of pl-4 (padding-inline-start)
• pe-4 instead of pr-4 (padding-inline-end)
• start-0 instead of left-0 (inset-inline-start)
• end-0 instead of right-0 (inset-inline-end)
• text-start instead of text-left
• text-end instead of text-right

<!-- Before -->
<div class="ml-4 pr-6 text-left">...</div>

<!-- After -->
<div class="ms-4 pe-6 text-start">...</div>

React Native Logical Properties

React Native's Yoga layout engine also supports logical properties — use them instead of Left/Right variants:

• paddingStart / paddingEnd instead of paddingLeft / paddingRight
• marginStart / marginEnd instead of marginLeft / marginRight
• borderStartWidth / borderEndWidth instead of borderLeftWidth / borderRightWidth
• start / end instead of left / right in absolute positioning

const styles = StyleSheet.create({
  row: {
    flexDirection: 'row',
    paddingStart: 16,
    paddingEnd: 16,
  },
  badge: {
    position: 'absolute',
    end: 8, // flips automatically with I18nManager.isRTL
    top: 8,
  },
})

Bidirectional Text Safety

Wrap text whose direction may differ from its surrounding context — usernames, product codes, file paths, or any user-generated content interpolated into a translated sentence — with <bdi> so the browser's bidi algorithm isolates it correctly.

<p>User <bdi>{userName}</bdi> posted a comment</p>
<p>Order number: <bdi>{orderCode}</bdi> has shipped</p>

Without <bdi>, a Latin-script username embedded in an Arabic sentence (or vice versa) can visually reorder surrounding punctuation and neighboring words.

Directional Icons and Components

• Mirror directional icons in RTL mode: arrows, chevrons, back/forward/next/previous buttons, and the "reply" icon in mail/chat UIs.
• Do not mirror non-directional icons: home, settings, search, print, trash, checkmarks, and icons of real-world objects (a clock face, a phone).
• Reverse the direction of carousels, sliders, and progress bars in RTL so "next" still corresponds to the reading direction.
• Reverse swipe gesture direction in RTL (e.g. a swipe-to-dismiss card should swipe toward the trailing edge, not always left).
• Flip charts and graphs that have a directional axis (e.g. a timeline running left-to-right) so time still flows in reading order.

/* Mirror an icon only when the document is RTL */
[dir="rtl"] .icon-chevron-forward {
  transform: scaleX(-1);
}

// React: pick the mirrored icon variant based on direction
function BackButton({ dir }: { dir: 'ltr' | 'rtl' }) {
  const Icon = dir === 'rtl' ? ChevronRightIcon : ChevronLeftIcon
  return (
    <button aria-label="Back">
      <Icon aria-hidden="true" />
    </button>
  )
}