Publishing right-to-left: an Arabic and Persian website that reads natively

What reading natively means

Setting a page to right-to-left takes one attribute. Making it read natively takes everything after that: the Latin fragments that run through Arabic and Persian text, type set for the script, numbers that keep their shape, and an address for each language. The failures are small and very visible — a handle printed backwards, a price split from its label, two lines of a headline colliding — and each one tells the reader the page was built for someone else.

For an introducing broker that is a trust problem, not a cosmetic one. The IB business depends on a referred trader checking the IB's page and trusting what they find there — the reason an IB needs a website, not just a feed. A page that stumbles over its reader's language has not earned that trust. The lessons below come from building Gravity's right-to-left sites¹; the rules come from the W3C, MDN and Google's own documentation.

Declare language and direction in markup

Put the language and the direction on the html element. The W3C's guidance is to add dir="rtl" to the html tag whenever a document's overall direction is right-to-left, and not to set base direction with CSS, so the direction holds even when styles do not load². Declare the language with lang as well, and keep the two apart: a language declaration does not set direction, and a direction does not name a language².

<!doctype html>
<html lang="ar" dir="rtl">
  <body>
    <!-- a handle: isolate it, or it renders as "yourhandle@" -->
    <p>تابعونا على <bdi>@yourhandle</bdi></p>

    <!-- a ticker: always left-to-right -->
    <p>الرمز <span dir="ltr">XAUUSD</span></p>

    <!-- text from data, direction unknown: let the browser decide -->
    <h2 dir="auto">…</h2>
  </body>
</html>

Lay the page out with CSS logical properties rather than left and right: margin-inline-start instead of margin-left, padding-inline instead of a left and right pair. Logical properties map to physical sides from the writing direction, so one stylesheet serves both editions⁶.

Isolate every Latin fragment

Every left-to-right run inside right-to-left text must be isolated: handles, brand names, tickers such as XAUUSD, prices, web addresses. Without isolation, "@handle" renders as "handle@" and quotation marks swap ends¹.

Text that mixes the two directions is bidirectional text, and browsers order it with the Unicode Bidirectional Algorithm. Letters carry a strong direction. Punctuation and spaces are neutral, and a run of neutrals takes the direction of the strong text around it — or, where the two sides disagree, the direction of the paragraph⁴. An @ between Arabic text and a Latin handle sits exactly where the sides disagree. It takes the paragraph's right-to-left direction and moves to the far end of the handle. A closing quotation mark or a trailing full stop does the same.

The fix is isolation. When a fragment's direction is known, wrap it in an element with dir set — dir="ltr" for a ticker. When it is not known, as with a name that arrives from data, use dir="auto" or the bdi element, both of which take the direction from the fragment's first strong character³. An isolated fragment is laid out as one unit, and nothing inside it disturbs the text outside. A site built from data rarely knows in advance which way a name runs, which makes dir="auto" the safer default for anything a user supplies.

Numbers and tickers stay left-to-right

Numbers are not mirrored. Material Design's bidirectionality guidance keeps numbers, such as phone numbers, left-to-right inside a right-to-left interface⁸. A ticker, a price or a spread reads the same way in any language. Wrap each one with dir="ltr" and it will neither split from its label nor pull neighbouring punctuation across.

Set the type for the script

Typographic settings tuned for Latin break Arabic and Persian. Three matter most.

No letter-spacing

Arabic letters join. Tracking that makes a Latin headline look tight and deliberate pulls Arabic letters apart: MDN notes that languages using the Arabic script expect connected letters to stay visually connected, and that letter spacing can make the text look broken⁷. Gravity tracks its Latin display type tight and drops the tracking to zero wherever the text is Arabic¹. Where Arabic must be stretched, the script has its own tool — the kashida, a lengthened join between letters — rather than space between them⁵.

More room between lines

Arabic and Persian have tall ascenders and deep descenders. A Latin display line height — Gravity's is 0.98 — makes a wrapped Arabic headline collide with itself, the marks of one line touching the letters of the next. Gravity sets about 1.3 for Arabic display type and 1.4 for titles¹.

Name the Arabic face in the stack

The quietest failure is in font fallback. A framework's font loader may generate a metric-matched fallback face for a Latin web font; in Gravity's case it was local Arial, declared with no unicode-range. Arial carries Arabic, so a fallback placed ahead of the intended Arabic face catches every Arabic letter first, and the Arabic face never appears¹. Name the families directly: the Latin face first, then the Arabic face, then the fallbacks. Latin words in the line — a brand, a handle — keep their own family, and Arabic letters fall through to the Arabic face.

:root {
  --font-display: "Space Grotesk", "Vazirmatn",
    "Space Grotesk Fallback", system-ui, sans-serif;
}

.display {
  font-family: var(--font-display);
  letter-spacing: -0.04em;
  line-height: 0.98;
}

.display:lang(ar),
.display:lang(fa) {
  letter-spacing: 0;
  line-height: 1.3;
}

Gravity sets Arabic and Persian in Vazirmatn, an open-source Persian and Arabic typeface under the SIL Open Font License, drawn in weights from Thin to Black and also shipped as a variable font⁹. Its thin end suits a light, linear design: hairline display, light titles¹.

For the type itself — choosing an Arabic web font, why tracking breaks joined letters, Persian letters and digits, and the font-fallback trap — see Arabic and Persian typography for the web.

Arabic and Persian are two editions

Arabic and Persian share a script, not a spelling. Persian adds four letters Arabic does not use — پ, چ, ژ and گ — and writes ی and ک where Arabic writes ي and ك: pairs that look alike in some positions but are different characters⁵. Text typed on the wrong keyboard mixes the two, and a search for one form can miss the other. Keep each edition to its own letters.

Digits differ too. Western digits (0–9) are used in parts of the Arab world such as Algeria and Morocco; Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩) in Egypt, Saudi Arabia and Iraq; extended Arabic-Indic digits (۰۱۲۳۴۵۶۷۸۹) in Iran and Afghanistan⁵. The two Eastern sets visibly differ at four, five and six. Pick one system per edition and use it everywhere — prices, dates, phone numbers — so a reader never meets two ways of writing the same figure on one page.

Mirror the layout, not every icon

A right-to-left page mirrors its layout: navigation starts from the right, the back arrow points right and the forward arrow left. Icons that show direction mirror with it. Icons that show something else do not. Material Design keeps media playback controls unmirrored, because they refer to the direction of the media being played, and keeps clocks turning clockwise⁸. A logo is a fixed mark and keeps its orientation.

A language switch is a control, not a sentence. Gravity keeps "EN" first in either direction, so the switch looks and works the same whichever edition a reader lands on¹.

Give each language its own address

Each language should be its own edition with its own address, linked to the others with hreflang¹. Google reads hreflang from HTML link elements, HTTP headers or a sitemap, and treats the three as equivalent. It ignores the annotations unless both pages point to each other, so each edition lists itself and every alternate; x-default names the page for readers whose language matches none¹⁰. Language codes use ISO 639-1 — ar for Arabic, fa for Persian¹⁰.

<link rel="alternate" hreflang="en" href="https://example.com/en/">
<link rel="alternate" hreflang="ar" href="https://example.com/ar/">
<link rel="alternate" hreflang="fa" href="https://example.com/fa/">
<link rel="alternate" hreflang="x-default" href="https://example.com/en/">

Hreflang tells a search engine which page to show; it does not tell it what language a page is in. Google works that out from the content and does not use hreflang or the lang attribute to detect it¹⁰. A page with an Arabic address and English copy will be read as English. Translate the whole edition, including the risk warning, which only protects the people who can read it.

What breaks, and the fix

Before an Arabic or Persian page goes live