Engineering notes Note
Thera Brainex BYC Internationalization · Frontend · Testing
One interface for English and Arabic
Translation is the easy part of a bilingual product; direction is what breaks layouts. Five practices for English/Arabic interfaces with right-to-left layouts, and the checks that keep them from regressing.
Three products I’ve worked on ship in English and Arabic with right-to-left layouts: Thera on the web and in its customer app, Brainex’s React Native apps for iOS and Android, and BYC’s money-transfer app.
Translating strings turns out to be the easy part. Direction is what breaks layouts. The examples below come from Thera, my own product, where I can show the details; the habits are the ones I carry between the three codebases.
Direction is a document property
Set dir on the root element from the active language, once, and do it before the first paint. If it is applied after hydration, Arabic users see the page flash in left-to-right first, and server and client markup disagree.
Thera does this in a small inline script in the root layout that reads the saved language (illustrative):
const lang = localStorage.getItem(LANGUAGE_KEY) ?? 'en';
document.documentElement.setAttribute('lang', lang);
document.documentElement.setAttribute('dir', lang === 'ar' ? 'rtl' : 'ltr');The language switcher updates the same attribute at runtime. With direction decided once, most components never need to know the language at all.
Write layout in start and end
Physical properties — margin-left, padding-right, text-align: left — are wrong half the time in a bilingual product. Logical ones such as margin-inline-start and text-align: start (ms-, pe- and text-start in Tailwind) flip with the document’s direction automatically.
In Thera’s web app, logical spacing utilities outnumber physical left/right ones by roughly seven to one. The remaining physical ones are exactly the places worth reviewing first when a screen looks wrong in Arabic.
Mirror only what has direction
Arrows, chevrons and “back” icons point somewhere, so they flip in right-to-left. Most icons don’t. In the customer app, an icon flips only when it is explicitly marked as directional, matching the convention on the web. Flipping everything by default produces backwards checkmarks and mirrored logos.
Keep left-to-right islands
Some content stays left-to-right inside an Arabic page: error codes, references and other identifiers. Mark those spans explicitly with dir="ltr" instead of hoping the browser’s bidirectional algorithm guesses right. Mixed-direction strings that look fine with test data can reorder with real data.
Make parity a build failure
There are over 6,600 keys in each language. The customer app’s strings are generated from the web’s files and drift-checked in the mobile pipeline, so the two clients can’t quietly diverge.
Browser tests cover the launch path in both directions: with Arabic saved, the marketplace and the login page render right-to-left with Arabic copy; with nothing saved, English remains the default left-to-right experience.