AI Khazna
MENA & Arabic AI

Building Arabic, right-to-left apps with AI coding tools

What AI tools get wrong with Arabic, and the rules that make them get it right every time

ATAI Khazna Team6 min read

You ask your AI coding tool to "add Arabic". It translates the labels and maybe flips the page. Then the problems start: the back arrow points the wrong way, padding sits on the wrong side, a phone number appears scrambled inside a sentence, and searching for a name finds nothing because the user typed the letter alef without its hamza.

AI tools learned mostly from left-to-right English code, so this is their default. They can build excellent Arabic interfaces, but only when you tell them the rules. This guide covers what they usually get wrong and how to put the fixes into your project's rules file so they are applied every time, not only when you remember to ask.

Start with dir and lang

Set both on the root element: <html lang="ar" dir="rtl">. The two attributes do different jobs. dir sets the base direction of the text; lang tells browsers, screen readers and search engines which language they are reading, and helps with font selection. MDN notes that lang does not set direction, and recommends the dir attribute over the CSS direction property, because direction belongs to the content, not the styling.

A common AI mistake is to fake right-to-left with flex-direction: row-reverse or float: right scattered through the code. That breaks the moment you switch back to English. For a bilingual app, the language switch should change lang and dir on the root, and nothing else in the layout should need to know.

For content whose direction you cannot predict, such as user posts, use dir="auto", which MDN recommends for user input and external data.

Use CSS logical properties

Physical properties such as margin-left and padding-right stay on the same side whatever the language. Logical properties follow the reading direction instead: margin-inline-start is the left margin in English and the right margin in Arabic. Use padding-inline-end, inset-inline-start and text-align: start in the same way. If you use Tailwind, the logical utilities such as ms-4 and me-8 do the same job as ml-4 and mr-8 while flipping correctly.

With logical properties, one stylesheet serves both languages. Without them, the AI will keep writing [dir="rtl"] overrides, and every new component becomes a new bug.

Mirror direction, not everything

Icons that show movement or sequence should flip in Arabic: back and forward arrows, chevrons in lists and breadcrumbs, "next" buttons and progress indicators. Icons that show real objects should not: logos, a clock, a phone, a search magnifier. A common convention also leaves media play buttons as they are. Ask the AI to mark directional icons with a class and mirror only those, for example with transform: scaleX(-1) under [dir="rtl"], rather than flipping every image.

Mixed Arabic and English text

Arabic interfaces are full of English: product names, email addresses, order codes, usernames. The browser's bidirectional algorithm usually copes, but text inserted at runtime can reorder the sentence around it. MDN describes the <bdi> element as isolating text from its surroundings, which is exactly what you need when you insert a name whose direction you do not know. Write <bdi>{userName}</bdi>, not the bare variable.

Phone numbers, email fields, codes and URLs should usually be left-to-right even on an Arabic page: give those inputs and values dir="ltr".

Fonts that support Arabic

Many fonts AI tools pick by default have no Arabic letters, so the browser falls back to a system font that clashes with your design. Choose a family designed for Arabic, such as Noto Sans Arabic, IBM Plex Sans Arabic, Cairo or Tajawal, and load it for Arabic text using the :lang(ar) selector. Arabic usually needs a little more line height than English. Do not apply letter-spacing to Arabic, because the letters are joined and spacing breaks the connections. Avoid fake italics too.

Numbers are a product decision

Arabic can be written with Latin digits (1, 2, 3) or Arabic-Indic digits (١, ٢, ٣). Many Gulf products use Latin digits; others prefer Arabic-Indic. Neither is wrong, but you must choose, and the AI should not choose for you. Formatting libraries make their own choice per locale: in our test with Node.js 22, Intl.NumberFormat('ar-KW') produced Arabic-Indic digits, while 'ar-u-nu-latn' produced Latin ones. The -u-nu- extension, documented on MDN, lets you set the numbering system explicitly. Put your decision in the rules file and make the AI pass it everywhere.

Dates

Decide three things: the calendar (Gregorian, Hijri, or both), the order of day, month and year, and whether month names or numbers appear. Then use one format across the whole app. Intl.DateTimeFormat supports a calendar option, including islamic-umalqura. Formatted Arabic dates can contain invisible direction marks, so never parse a formatted string back into a date; store ISO dates and format only for display.

Text expansion and real copy

Arabic labels can be longer or shorter than their English versions, and Arabic script needs more vertical space. Fixed-width buttons, single-line tabs and truncated cards break first. Ask the AI to avoid fixed widths on text containers, and test every screen with real Arabic copy rather than placeholder text.

Search that understands Arabic

Users type the same word in different ways. Normalise both the stored text and the search query: unify the alef forms (أ، إ، آ to ا), treat taa marbuta (ة) as haa (ه), treat alef maqsura (ى) as yaa (ي), and remove tashkeel and the tatweel character. In JavaScript that can be as simple as:

text.replace(/[\u064B-\u0652\u0670\u0640]/g, '').replace(/[\u0622\u0623\u0625]/g, '\u0627').replace(/\u0629/g, '\u0647').replace(/\u0649/g, '\u064A')

Store a normalised copy of searchable fields in the database so queries stay fast, and keep the original text for display.

Put the rules in your rules file

All of this is wasted if the AI forgets it next session. Add an Arabic section to CLAUDE.md, AGENTS.md or your .cursor/rules file. Our guide to writing a rules file for CLAUDE.md and Cursor explains where it goes. A starting point:

  • Arabic pages use lang="ar" dir="rtl" on the root; language switching changes only these attributes.
  • Use CSS logical properties only; never margin-left, padding-right, left or right for layout.
  • Mirror only icons marked as directional.
  • Wrap inserted user text in <bdi>; phone, email and code fields are dir="ltr".
  • Arabic font: [your choice]; no letter-spacing on Arabic.
  • Digits: [Latin or Arabic-Indic], set explicitly in every number and date formatter.
  • Dates: [your format and calendar], the same everywhere.
  • Search normalises alef forms, taa marbuta, alef maqsura, tashkeel and tatweel on both sides.

Quick checklist

  • Root element has the right lang and dir in both languages.
  • No physical left or right properties in the layout code.
  • Arrows and chevrons point the right way; logos are not mirrored.
  • Names, emails and phone numbers display correctly inside Arabic sentences.
  • The Arabic font loads and letters stay joined.
  • Digits and dates follow one documented decision.
  • Buttons and tabs survive long Arabic labels.
  • Searching with or without hamza returns the same results.

Next step: new to building with these tools? Start with your first app with Claude Code, then use the Vibe Coding hub to plan, build and launch your Arabic app safely.

Frequently Asked Questions

Is setting CSS direction: rtl enough for an Arabic page?
No. MDN recommends the dir attribute on the html element, because direction belongs to the content. Pair it with lang="ar" and use CSS logical properties so the layout follows the direction automatically.
Should my Arabic app use Latin or Arabic-Indic digits?
It is a product decision. Many Gulf products use Latin digits, others prefer Arabic-Indic. Choose one, write it in your rules file and set the numbering system explicitly in every formatter.
Why does searching for an Arabic name sometimes find nothing?
Users write the same word differently, for example with or without a hamza on the alef, or with taa marbuta written as haa. Normalise both the stored text and the query so these variants match.
How do I stop the AI repeating RTL mistakes?
Put the Arabic rules in the file your tool reads every session, such as CLAUDE.md, AGENTS.md or .cursor/rules. Short, specific lines work better than general instructions.
arabicrtlvibe codinglocalisationrules file