Arabic documentation and RTL: a practical implementation guide

Turning on dir="rtl" is the quick part. The useful test comes next: put an option such as -d, a path, and a version number inside an Arabic sentence, then search for a word with and without its hamza.

Those two tests expose many defects that a translated landing page will not. This guide covers the layout, bidirectional text, search, language-tree, hreflang, and typography checks we use in Nibleaf. You can apply the same checks to another documentation stack.

Use logical CSS properties

Physical CSS properties encode a side. Logical properties encode the start or end of a line and adapt to the document direction.

/* Fixed to the left */
.nav-item {
  margin-left: 12px;
  border-left: 2px solid var(--accent);
}

/* Adapts to LTR and RTL */
.nav-item {
  margin-inline-start: 12px;
  border-inline-start: 2px solid var(--accent);
}

The same principle applies to padding, positioning, alignment, borders, and corner radii. Tailwind has included logical utilities such as ms-*, me-*, ps-*, pe-*, start-*, and end-* since v3.3.

Directional icons require a separate decision. A next-page arrow should flip with the interface. A logo, screenshot, or icon that depicts a physical object should not be mirrored automatically.

Isolate LTR code inside RTL prose

Arabic technical writing mixes two directions. The sentence runs right-to-left, while commands, paths, flags, identifiers, and version numbers run left-to-right. Characters such as -, /, and . can take their visual placement from the surrounding text.

Unicode UAX #9 defines isolation for keeping the inner and outer directional runs from affecting each other. Apply an explicit direction and isolation to inline code, and keep code blocks left-aligned:

.docs-content :not(pre) > code {
  direction: ltr;
  unicode-bidi: isolate;
}

.docs-content pre {
  direction: ltr;
  text-align: left;
}

Test the same mixed sentence in both the editor and the published reader. Then copy the command into a terminal. Visual order and copy behavior both matter.

Nibleaf now applies this rule to inline and block code in the reader and the editor. Regression tests should still keep a mixed Arabic, path, and command sample because bidi defects are easy to reintroduce with a styling change.

Separate Arabic tokenization from normalization

An English-default tokenizer can drop Arabic text entirely. Selecting an Arabic tokenizer solves that first problem, but it does not make every spelling or inflected form equivalent.

Useful spelling tests include:

Page text	Query	Difference
الإعدادات	الاعدادات	alef with hamza
إِعْدادات	إعدادات	diacritics
التحكــم	التحكم	tatweel
إلى	الي	alef maqsura and ya

Nibleaf uses Orama's Arabic tokenizer. It also applies conservative normalization to indexed text and queries: diacritics and tatweel are removed, common alef forms are folded, and alef maqsura is folded to ya.

The implementation deliberately does not fold ta marbuta ة into ha ه. They are different letters, and merging them can change the words returned. A separate conservative morphology field removes a bounded set of common conjunction, preposition, definite-article, attached-pronoun, plural, and dual affixes. That lets مستخدم match للمستخدمين without applying aggressive root extraction.

Original normalized tokens remain in higher-weight exact fields, while morphology-only hits use lower boosts. Short words, code, mixed Arabic/Latin identifiers, and reviewed ambiguous words are protected. This improves documentation recall, but it is still a light search analyzer rather than a full dictionary lemmatizer: uncommon broken plurals, dialectal forms, and many verb conjugations can remain distinct.

Let each language tree reflect reader needs

An Arabic documentation section often begins with installation, quickstart, and common support tasks rather than a complete translation of the English tree. Forcing a mirrored folder can leave the team with stubs or stale pages.

Nibleaf gives each language its own page tree and connects corresponding pages through translation keys. An English /getting-started page and an Arabic /البدء page can be paired without sharing a slug or position.

This is a product choice, not a universal rule. A docs-as-code team may prefer mirrored locale directories because that fits its review and build process. The Nibleaf and Docusaurus comparison describes that workflow trade-off.

Make canonical and hreflang signals agree

Google may discover translated pages without hreflang, and fully translated pages are not duplicates simply because they cover the same subject. Explicit alternates still help Google choose the suitable language URL.

<html lang="ar" dir="rtl">
<link rel="canonical" href="https://docs.example.com/ar/deploy" />
<link rel="alternate" hreflang="ar" href="https://docs.example.com/ar/deploy" />
<link rel="alternate" hreflang="en" href="https://docs.example.com/en/deploy" />
<link rel="alternate" hreflang="x-default" href="https://docs.example.com/en/deploy" />

Google's localized-page guidance requires each listed version to reference itself and its counterpart. Alternate links must be reciprocal to be processed. Google recommends x-default for users whose language does not match another alternate.

Use generic ar unless the page is genuinely specific to a region. Also verify lang, dir, the canonical, og:locale, and structured data in the server response. Changing them only after JavaScript runs is too late for a reliable SSR implementation.

Nibleaf emits alternates for pages that have an actual linked translation. It should not advertise a missing or non-indexable sibling.

Test the real Arabic font stack

Arabic letters change shape according to their position. A Latin font without Arabic coverage can fall back silently to a system font, producing a different weight, baseline, and apparent size inside one sentence.

Build a small font specimen with:

• a long heading with diacritics;
• Arabic and English in the same paragraph;
• every weight used by the interface;
• a table, list, link, and inline code sample.

Open it on the operating systems and phones your readers use. Set line height from that test rather than copying a fixed ratio. Remove letter-spacing and text-transform from Arabic headings because tracking can break the visual connection between letters.

A release checklist

Before shipping an Arabic documentation section, verify:

• html has the correct lang and dir in the initial response.
• Inline code and code blocks remain LTR in reader and editor.
• Directional icons, breadcrumbs, and pagination move correctly.
• Search covers the spelling variants your readers use.
• Arabic has a deliberate font in every required weight.
• Paired pages publish reciprocal hreflang and consistent canonicals.
• Arabic pages declare Arabic in Open Graph and Article structured data.
• The Arabic tree can grow without placeholder translations.

Nibleaf currently provides per-language trees, RTL layout, inline-code isolation, Arabic tokenization with spelling normalization and conservative light morphology, hreflang, and an English and Arabic interface. The morphology deliberately favors precision over exhaustive linguistic coverage, and it cannot repair inconsistent terminology or weak translations.

For an Arabic version of this checklist, read كيف تنشر وثائق منتج بالعربية. You can also run the HTML through the private, browser-only RTL documentation readiness grader, start on the hosted beta, or follow the public self-hosting guide.