Orrery

ADR-045 — RTL strategy for Arabic locale ​

Status · Accepted Date · 2026-05-06 Supersedes in part · docs/adr/ADR-032.md (Wave 3 RTL deferred note) Scope · ar runtime direction handling

Context ​

Issue #38 adds Wave 3 locales including Arabic (ar), which requires right-to-left document flow. ADR-032 deferred the RTL strategy decision pending Wave 3 scheduling.

The app is SvelteKit SPA navigation with ?lang= as locale source-of-truth. Direction must update both on first load and client-side route transitions.

Decision ​

Use a lightweight global document-attribute strategy:

  • set <html lang="..."> to the active locale code
  • set <html dir="rtl"> only when locale is ar
  • set <html dir="ltr"> for all other locales

Direction updates run in the existing locale runtime effect tied to URL ?lang=.

No global CSS rewrite is performed in this rollout.

Rationale ​

  • Minimal invasive change that aligns with existing locale resolution flow.
  • Works across all routes, including canvas-heavy views, without route-specific overrides.
  • Avoids risk and churn of immediate full migration to CSS logical properties.
  • Keeps room for progressive RTL hardening later if component-level issues emerge.

Consequences ​

Positive:

  • Arabic UI chrome mirrors via native browser bidi/layout behavior.
  • Runtime behavior stays consistent during in-app navigation.
  • Non-RTL locales remain unchanged (ltr).

Negative:

  • Components using physical left/right CSS may need targeted follow-up fixes.
  • This does not by itself guarantee perfect mirrored spacing in every legacy selector.

Alternatives considered ​

  • Full logical-properties refactor now: highest long-term correctness, but too broad and risky for locale rollout scope.
  • Separate rtl.css override sheet: can work, but adds maintenance burden and selector drift risk.
  • Per-component conditional classes only: fragmented and error-prone compared with a single global source.

Implementation notes ​

  • Extend locale utilities with RTL awareness (ar only in current set).
  • Sync document.documentElement lang/dir from the resolved URL locale on runtime updates.
  • Cover with Arabic e2e smoke that asserts RTL + locale persistence.

Orrery — architecture documentation · MIT · No tracking

© Marko Dragoljević and contributors