We shipped the Arabic build on a Thursday. The strings were right, the alignment was right, and the back arrow still pointed at the exit. The progress bar filled from the wrong end, the onboarding carousel advanced backwards, and a phone number in the middle of a sentence had its digits rearranged like a typo. Nothing was broken in the translation. We'd just set direction: rtl on the root and assumed the interface would follow.
It doesn't. Directionality isn't a text property, it's a spatial one. Every icon that implies movement, every offset you wrote in left, every gesture and every timeline was drawn with a left-to-right world in mind. Flip the text and those decisions stay exactly where they were, quietly wrong.
What the flip doesn't reach
The useful audit isn't "does the page look mirrored". It's "which elements carry meaning through direction". There are more of them than anyone expects on the first pass.
| Element | What LTR assumes | What RTL actually needs | The usual miss |
|---|---|---|---|
| Back arrow | Points left | Points right, and the whole nav stack reads right-to-left | Icon flipped, swipe-back gesture not |
| Progress bar | Fills left to right | Fills right to left | Hardcoded width and gradient direction |
| Phone numbers in a sentence | The string is one direction | Digits stay LTR, the surrounding text stays RTL | Wrapping the whole string in direction: rtl |
| Form labels | Labels sit left | Labels sit right, but number and email inputs stay LTR | Using text-align instead of logical alignment |
| Corner badges | left: 8px | inset-inline-start: 8px | Pseudo-elements still pinned to left |
| Swipe to advance | Swipe left goes forward | Forward is right-to-left | Carousel and onboarding keep LTR ordering |
| Charts and timelines | Time flows left to right | Time flows right to left; axis labels are bidi | Only the container got flipped |
Bidirectional text is the row that keeps biting us. A number, a Latin brand name, or an @handle inside an Arabic sentence keeps its own direction, and the browser's bidi algorithm mostly gets it right — until you add punctuation, parentheses or a stray direction on a wrapper. Then the closing bracket lands on the wrong side and someone files it as a translation bug. It isn't. It's a markup bug, and no translator can fix it for you.
The honest tradeoff
Let's be straight about the cost: this is a design-system rebuild, not a stylesheet patch. If your components encode position with left, right, margin-left and padding-right, you have hundreds of small decisions to convert to logical properties. We've done it half-way before, and half-way is worse than not starting, because now some components mirror and some don't and nobody can predict which. Either commit to inline-start / inline-end across the library, or accept that RTL will be a permanent second-class build.
Mixed-direction content doesn't automate away. There's no linter that reliably tells you a string will render correctly once a user types their own Latin username into an Arabic form field. You need real fixtures — real Arabic copy, real Hebrew copy, a genuine phone number, a Latin brand, a date — reviewed by someone who reads the language. Which brings us to the bill nobody puts in the sprint: the test matrix doubles. Every screen, every state, every animation now has two directions, and the RTL half is the one your team is less fluent in. We've caught more RTL regressions in a ten-minute walkthrough with a native reader than in a month of screenshot diffs.
And there's the uncomfortable industry habit worth naming: Arabic and Hebrew get treated as launch-week polish. Teams build the whole product LTR, then "add RTL" right before a market launch, discover the icon and gesture problems above, and ship a version that technically works and feels subtly foreign to the people it was for. That's not a technical debt story, it's a prioritisation story. Doing it late genuinely costs more, but doing it never costs you the market. We'd rather carve out the logical-property migration early, while the component library is still small and the arguments are cheap.
One more honest limit: some things shouldn't mirror. A play button, a media scrubber's direction, or a brand logo usually stays put, and a phone keypad has its own logic. Blanket mirroring is as wrong as no mirroring. Deciding case by case is slower, and it's the job.
Build the direction in, not on top
Set dir on the document root and let logical properties carry the layout, so one attribute can flip the whole tree. Audit directional icons as a set with a name, not as scattered SVGs, and give them a mirrored variant. Keep numeric and Latin inputs explicitly LTR inside an RTL form. Add bidi fixtures with real punctuation to your snapshot tests, and get a native reader to walk the checkout and the onboarding in both directions before you call the build done.
The quick check is annoyingly simple: switch a test device to Arabic, open the app, and try to go back, swipe through onboarding, and read a price with a phone number under it. If any of those three feels like it's fighting you, the text was never the problem. The space around it was.
Sources
- W3C — Internationalization — the reference material on bidi text and the
dirattribute. - MDN — CSS direction — what the property changes, and what it deliberately doesn't.
- MDN — HTML dir attribute — setting base direction at the document level.
- Apple — Human Interface Guidelines — platform guidance on right-to-left layout and which controls shouldn't mirror.
- Android Developers — RTL support, logical alignment and bidirectional text handling on the host OS.