How to Build an RTL Website Correctly with Nuwat

Start with direction at the document root

The browser should know both the language of the page and the direction it should follow. lang identifies the language of the document, while dir controls text and layout direction. Do not rely only on body { direction: rtl; }; direction should be part of the document structure rather than a CSS patch applied after the interface has already been designed. If your product supports Arabic and English, keep each language on clear URLs such as /pricing and /en/pricing so language switching, internal linking, canonical URLs, and localized SEO stay easy to manage.

<html lang="ar" dir="rtl">

<html lang="en" dir="ltr">

body {
  direction: rtl;
}

Build around start and end, not left and right

One of the most common RTL mistakes is building the entire interface around left and right and trying to reverse it later. When you mean the beginning or end of an element, use CSS Logical Properties. The same idea applies to margin-inline-start, margin-inline-end, padding-inline, border-inline-start, and inset-inline-end. Your component APIs can follow the same principle: iconStart is more flexible than iconLeft. Prefer gap with Flexbox and Grid instead of manually assigning margin-left or margin-right, and do not treat row-reverse as a universal RTL solution because the direction may already have changed through dir=rtl.

.card {
  padding-inline-start: 24px;
}

.search-icon {
  inset-inline-end: 12px;
}

.nav {
  display: flex;
  align-items: center;
  gap: 1rem;
}

Arabic and English will appear together

Real Arabic products rarely contain Arabic alone. A sentence might say تم تعديل الملف src/components/Header.tsx وتشغيل npm run build بنجاح, or تم إرسال الرسالة إلى ahmed@example.com. That means an RTL interface still needs to contain LTR content. Code, terminal commands, file paths, URLs, email addresses, package names, Git hashes, and JSON should generally remain left-to-right. For dynamic content where the direction is unknown, bdi can isolate a value from the surrounding sentence. These details are easy to miss when testing with clean Arabic paragraphs, but they appear constantly in real products.

<code dir="ltr">npm run build</code>

<span dir="ltr">
  src/components/Navbar.tsx
</span>

code, pre {
  direction: ltr;
  text-align: left;
}

<p>قام <bdi>Ahmed_92</bdi> بتحديث المشروع.</p>

Components need more than mirroring

Some UI components expose RTL problems much faster than others. Forms are a good example: an Arabic form may have RTL labels and validation messages, while the email address, phone number, card number, or verification code needs different direction handling. Sidebars need similar thought. Check their opening direction, border position, collapsed state, submenu arrows, tooltip placement, and mobile close button. Use logical properties where possible, and review breadcrumbs, tables, dropdowns, popovers, modals, drawers, command palettes, and toast notifications. A table might contain an Arabic customer name, an English email address, a URL, and a numeric amount in the same row; direction should follow the content rather than forcing every cell into the same behavior.

<input type="email" dir="ltr" />

.sidebar {
  border-inline-end: 1px solid #ddd;
}

Do not mirror every icon

Not every icon needs to change direction in RTL. Back and forward arrows often do because direction is part of their meaning. But search, delete, settings, download, video play, GitHub icons, company logos, and many chart symbols should usually remain unchanged. Ask: Is direction part of what this icon means? If not, it probably should not be mirrored just because the surrounding interface is RTL. Make RTL a direction system, not an instruction to flip every visual element.

Arabic typography changes the layout

Typography is another area where reusing English settings can produce a weak result. Arabic characters have different shapes, vertical proportions, connections, and visual density. A font weight that feels balanced in English may appear too light or too heavy in Arabic, and a line height that works for an English heading may become cramped when the component contains Arabic. Test the production font on real headings, paragraphs, buttons, form labels, validation messages, numbers, and mixed Arabic and English text. Also expect translated text to change length; components should adapt to their content rather than force Arabic into an English-sized box.

• Headings and paragraphs
• Buttons and form labels
• Validation messages and numbers
• Mixed Arabic and English text

.button {
  min-inline-size: 120px;
  padding-inline: 20px;
}

Test RTL on mobile early

Many RTL issues appear only when the viewport becomes narrow. A desktop layout may look perfect while the mobile version has a menu button on the wrong side, a close icon overlapping the title, a long Arabic heading overflowing its card, an LTR file path breaking the layout, or navigation wrapping incorrectly. Do not wait until the end of development to test the Arabic version; RTL is much easier to support when it is part of component development from the beginning.

• Menu button placement
• Close icon and title overlap
• Long heading overflow
• LTR file paths
• Navigation wrapping

pre {
  overflow-x: auto;
}

.long-text {
  overflow-wrap: anywhere;
}

Use real Arabic content while developing

Placeholder text hides problems. Test with real examples containing Arabic, English technical terms, numbers, commands, usernames, and file paths. These combinations expose bidirectional text problems much faster than a short Arabic sentence.

أنشئ لوحة تحكم لإدارة الطلبات والعملاء والفواتير من مكان واحد.

تم ربط المشروع مع GitHub. يمكنك الآن تشغيل npm install ثم البدء في تعديل الملفات.

تم إرسال الرسالة إلى ahmed@example.com

شغّل npm run dev

الإصدار الحالي هو v2.14.0

افتح الملف src/app/page.tsx

السعر 99 SAR شهريًا

Test the whole experience

Component-level testing is useful, but users experience complete flows. Open the site, use the navigation, create an account, enter an Arabic name and an English email, open a dashboard, interact with a sidebar and table, trigger a validation error, open a modal, and switch the interface to English. Check Tab order, arrow-key behavior, selects, menus, dialogs, and carousels. The visual order created by CSS should not conflict with the semantic order of the DOM. Use semantic elements such as nav, main, header, button, and label, connect labels correctly, make error messages understandable, and preserve the current page when switching languages, such as /docs/installation to /en/docs/installation.

RTL also affects SEO

Arabic localization does not stop at the interface. Each language version should have its own appropriate title, meta description, canonical URL, and hreflang references. Arabic search intent may differ from English search intent, so a useful Arabic page should reflect the way Arabic users actually describe and search for the problem rather than simply translating an English SEO page word for word.

<link rel="alternate" hreflang="ar" href="https://example.com/rtl-web-development" />

<link rel="alternate" hreflang="en" href="https://example.com/en/rtl-web-development" />

Build RTL interfaces with Nuwat

Instead of translating your requirements into a long English prompt, describe the interface the way you naturally think about it. The goal is not simply to understand Arabic words. Nuwat is designed to bring Arabic product context into the request: RTL, mixed-language content, component direction, and the expectations of Arabic interfaces. You can describe what you want in the language and technical vocabulary you already use while the coding agent works on the implementation.

Good RTL should feel intentional

A strong Arabic interface should not look like an English website that was mirrored at the last minute. Direction, typography, mixed content, forms, icons, navigation, responsiveness, accessibility, and localization should work together. The best RTL implementation is usually the one that needs the fewest RTL-specific hacks because the components were designed around direction from the beginning.