This post covers four traps when searching Arabic text in JavaScript, then builds a search-normalization function, a function that finds match positions so you can highlight them, and finally when you should not normalize.

Disclosure: I work on an open-source Arabic text library that has normalization functions; I mention it briefly at the end. Everything before that is plain JavaScript, no libraries.

Trap 1: includes() matches characters exactly

'محمد أحمد'.includes('احمد');  // false
'مُحَمَّد'.includes('محمد');      // false
'مـحـمـد'.includes('محمد');     // false

includes, indexOf and regular expressions do exact matching, with no Arabic-specific normalization. «أ» (alef with hamza, U+0623) is not «ا» (bare alef, U+0627); the vowel marks (harakat) are separate characters between the letters, and so is the tatweel «ـ» (U+0640). People also spell hamza forms, teh marbuta «ة» and alef maksura «ى» inconsistently, so literal search fails a lot.

Trap 2: two strings that look identical but aren't

const a = 'أحمد';
const b = 'ا\u0654حمد';   // alef + separate hamza above (U+0654)
a === b;                       // false
a === b.normalize('NFC');      // true

«أ» can arrive as one code point, or as two: a bare alef followed by a combining hamza. They render the same, but they don't compare equal. This shows up in text copied from some programs and in file names from some systems; normalize('NFC') unifies these canonically equivalent forms.

There's a second case NFC doesn't cover. Text copied from some PDFs arrives in Arabic "presentation forms": dedicated code points for certain letter shapes and ligatures.

const fromPdf = '\uFEE3\uFEA4\uFEE4\uFEAA';   // «محمد» in presentation forms
fromPdf === 'محمد';                   // false
fromPdf.normalize('NFC') === 'محمد';  // false
fromPdf.normalize('NFKC') === 'محمد'; // true

NFKC maps them back to the base letters, but it also changes other characters (ﷺ, for example, expands into a whole phrase), so we'll use it only inside the search key.

Trap 3: Intl.Collator compares, it doesn't search

Intl.Collator looks like the answer, since it compares strings using language rules. On Node 24.21 / ICU 78.3:

const collator = new Intl.Collator('ar', { sensitivity: 'base' });
collator.compare('أحمد', 'احمد');     // 0
collator.compare('مُحَمَّد', 'محمد');   // 0
collator.compare('مـحـمـد', 'محمد');  // 0
collator.compare('على', 'علي');       // 0
collator.compare('مدرسة', 'مدرسه');   // -1

0 means equal. It's great for sorting and for comparing two whole words, but it has three problems for search:

• It compares a whole string to a whole string. It doesn't find a word inside a text, and JavaScript has no search API built on it.
• Its rules aren't your rules: here it treats «على» (the preposition "on") and «علي» (the name Ali) as equal, yet keeps «مدرسة» and «مدرسه» apart.
• Results depend on the ICU version in the browser or server, so they can differ between environments.

Trap 4: characters you can't see

Text copied from web pages or chat apps can carry invisible characters inside words, such as direction marks (U+200F, U+061C) or a zero-width space (U+200B):

'محمد\u200F'.includes('محمد');  // true
'مح\u200Bمد'.includes('محمد');  // false

The first works because the mark sits at the end of the word; the second fails because the invisible character is in the middle. The user can't see it and won't understand why the result is missing.

The fix: a normalized search key

Don't search the text as-is. Compute a normalized "search key" for each text, compute the same key for the query, and compare keys. Keep the original text for display.

The rules below are a search policy that suits most general Arabic text, not an exhaustive list; adjust them for your app:

// Removed from the key: Arabic combining marks (including the separate hamza U+0654/U+0655), tatweel,
// and selected invisible and direction-control characters
const DROP = /[\u064B-\u065F\u0670\u0640\u200B-\u200F\u061C\u202A-\u202E\u2066-\u2069]/;
// Unified: alef forms, alef maksura, teh marbuta, the Persian keheh (ک) and yeh (ی)
const MAP = { 'أ': 'ا', 'إ': 'ا', 'آ': 'ا', 'ٱ': 'ا', 'ى': 'ي', 'ة': 'ه', 'ک': 'ك', 'ی': 'ي' };

// Key for one character: NFKC maps presentation forms to letters, then drop and unify
function keyOf(ch) {
  let out = '';
  for (const c of ch.normalize('NFKC')) {
    if (!DROP.test(c)) out += MAP[c] ?? c;
  }
  return out;
}

function searchKey(text) {
  let key = '';
  for (const ch of text.normalize('NFC')) key += keyOf(ch);
  return key;
}

searchKey('أحمد');           // 'احمد'
searchKey('مُحَمَّد');         // 'محمد'
searchKey('مـحـمـد');        // 'محمد'
searchKey('مدرسة');          // 'مدرسه'
searchKey('مستشفى');         // 'مستشفي'
searchKey('ا\u0654حمد');     // 'احمد'
searchKey('مح\u200Bمد');     // 'محمد'
searchKey(fromPdf);          // 'محمد'

searchKey('ذهب محمد أحمد إلى المدرسة').includes(searchKey('احمد'));  // true

Notes:

• Apply it to both sides, the text and the query. Normalize only one and they won't match.
• Don't store it instead of the original: it loses information. «مدرسه» in the key could be «مدرسة» or «مدرسه» in the source.
• It leaves «ؤ», «ئ» and the standalone hamza «ء» alone, because stripping the hamza from them changes the word more than it helps search. If you need that, add them to MAP deliberately.
• This is substring search, so «علي» also matches inside «عليكم». For whole words, tokenize the text with a word-boundary strategy that suits your app, or check the boundaries around each match.
• NFKC inside the key also folds other characters, such as fullwidth digits and Latin letters. We apply it per character to keep offsets; that's enough for Arabic presentation forms, but it isn't exactly the same as running NFKC on the whole string.

Highlighting matches

The key differs from the text in length and positions (harakat and tatweel are gone, and NFKC can make it longer), so a match position in the key isn't its position in the text. The fix: while building the key, record the start and end of the character each key unit came from. We walk the text by code point with for...of, and record offsets in UTF-16 code units, because that's what slice and indexOf use:

// Returns match ranges [start, end) in the NFC text, including consecutive dropped characters (e.g. harakat) after the last match
function findMatches(text, query) {
  text = text.normalize('NFC');
  let key = '';
  const starts = [];
  const ends = [];
  let i = 0;
  for (const ch of text) {
    const k = keyOf(ch);
    key += k;
    for (let u = 0; u < k.length; u++) {
      starts.push(i);
      ends.push(i + ch.length);
    }
    i += ch.length;
  }
  const q = searchKey(query);
  const matches = [];
  if (!q) return matches;
  for (let at = key.indexOf(q); at !== -1; at = key.indexOf(q, at + q.length)) {
    const start = starts[at];
    let end = ends[at + q.length - 1];
    while (end < text.length && DROP.test(text[end])) end++; // keep a haraka with its letter
    const prev = matches[matches.length - 1];
    if (prev && start < prev[1]) prev[1] = Math.max(prev[1], end); // two matches in one character (like ﷺ): merge them
    else matches.push([start, end]);
  }
  return matches;
}

const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);

function highlight(text, query) {
  text = text.normalize('NFC');
  let html = '';
  let last = 0;
  for (const [start, end] of findMatches(text, query)) {
    html += escapeHtml(text.slice(last, start)) + '<mark>' + escapeHtml(text.slice(start, end)) + '</mark>';
    last = end;
  }
  return html + escapeHtml(text.slice(last));
}

highlight('قال مُحَمَّد: أهلاً يا محمد', 'محمد');  // 'قال <mark>مُحَمَّد</mark>: أهلاً يا <mark>محمد</mark>'
highlight('ذهبت إلى المـدرسـة', 'مدرسه');       // 'ذهبت إلى ال<mark>مـدرسـة</mark>'
highlight('😀 مُحَمَّد', 'محمد');                 // '😀 <mark>مُحَمَّد</mark>'

The output shows the NFC text with its harakat and tatweel, even though the search ignored them (NFC doesn't change how the text looks). And the function escapes HTML before inserting <mark>, so user text can't inject markup here. This escaping is enough for text inside an element, as in this example, not for attributes or URLs.

In the database

Don't compute the key for every row on every search. Store it in its own column when you save, and search that:

• A name column for display and a name_search column = searchKey(name), updated whenever the name changes.
• Normalize the query with the same function before querying, on the server, not only in the browser. Pass it as a parameter in a prepared statement, and with LIKE, escape % and _ in the query so they're treated as literal characters.
• An ordinary index helps exact matches and prefix searches, but usually not LIKE '%term%'. For word search in long text, consider a full-text index; arbitrary substring search usually needs an n-gram or trigram index, depending on your database.
• If you change the searchKey rules later, recompute the column for every row, or the keys won't match.

When not to normalize

Normalization widens results, and some of them aren't what the user wants:

• «على» (preposition) and «علي» (the name Ali) get the same key.
• «حماة» (the city of Hama) and «حماه» get the same key.
• In Quranic text or vowelled poetry, the reader may be searching for the vowels themselves.

So:

• Use normalization for search only; keep the original for display and storage.
• Rank results: exact matches first, then normalized matches. If the user searched «على», show «على» before «علي».
• Offer an exact-search option where vowels or hamza forms carry meaning.

Summary

• includes matches characters exactly, and Intl.Collator compares whole strings rather than searching inside them.
• Unify forms with NFC, and presentation forms with NFKC inside the search key, then apply your policy: drop marks, tatweel and selected invisible characters; unify alef forms, teh marbuta and alef maksura.
• Apply the key to both the text and the query, and keep offsets so you can highlight matches.
• Store the key in its own column; never replace the original with it.

Disclosure: the open-source @kirnu/arabic-core library has normalizeArabic (alef forms, yeh, teh marbuta, the Persian ک and ی, and tatweel, each rule a separate option) and removeTashkeel (vowel marks), with tests; their rules are close to this article's policy but not identical. If you want to try normalization on a text without writing code, there's a free Arabic text normalizer (the page is in Arabic).

What rules do you use for Arabic search in your apps? Do you unify teh marbuta and alef maksura, or leave them?

This post covers where the problem comes from, four traps in JavaScript, and then how to normalize, validate and store one canonical form.

Disclosure: I maintain an open-source Arabic text library that has a digit-conversion function; it's mentioned briefly at the end. Every example before that is plain JavaScript.

Three sets of digits

• Western digits 0–9: U+0030 to U+0039.
• Arabic-Indic digits ٠–٩: U+0660 to U+0669. They may be entered by Arabic keyboard layouts or Arabic locale settings.
• Extended Arabic-Indic (Persian/Urdu) digits ۰–۹: U+06F0 to U+06F9. Most look like the Arabic ones, but some are shaped differently, such as ۴, ۵ and ۶ (and ۷ in Urdu), and all ten are separate code points.

Number formatting also has its own marks: the Arabic decimal separator ٫ (U+066B), the Arabic thousands separator ٬ (U+066C) and the Arabic percent sign ٪ (U+066A).

Trap 1: \d doesn't match Arabic digits

/^\d+$/.test('٠٥٠١٢٣٤٥٦٧');  // false
/^\d+$/u.test('٠٥٠١٢٣٤٥٦٧'); // false

In JavaScript, \d means 0–9 only, even with the u flag. Any validation built on \d rejects a number typed with Arabic digits.

Trap 2: Number() and parseInt() return NaN

Number('١٢٣');      // NaN
parseInt('١٢٣');    // NaN
parseFloat('١٢٫٥'); // NaN
Number('12٣');      // NaN

JavaScript doesn't convert Arabic-Indic digits to numbers, and a single Arabic digit inside a Western number is enough to make the whole conversion fail.

Trap 3: \p{Nd} accepts more than you want

\p{Nd} (any Unicode decimal digit) looks like the fix:

/^\p{Nd}+$/u.test('٠٥٠١٢٣٤٥٦٧'); // true
/^\p{Nd}+$/u.test('৫৫৫');        // true (Bengali digits)

It does accept Arabic digits, but also the digits of many other scripts: 770 characters in 77 digit sets in Node 24. And it converts nothing: Number() still returns NaN afterwards. Validation alone isn't enough: normalize first, then validate.

Trap 4: invisible direction marks

Copy a number from an Arabic page, or from Intl output, and invisible bidi control characters can come along. On Node 24.21 / ICU 78.3:

const date = new Intl.DateTimeFormat('ar-SA', { timeZone: 'UTC' }).format(new Date(Date.UTC(2024, 2, 11)));
date;                    // '١١‏/٣‏/٢٠٢٤'
date.includes('‏'); // true: a RIGHT-TO-LEFT MARK (RLM) after the day and the month

const percent = new Intl.NumberFormat('ar-EG', { style: 'percent' }).format(0.25);
percent.includes('؜'); // true: an ARABIC LETTER MARK (ALM) after the percent sign

These can break a strict ^...$ check that expects digits only, even though the text looks fine on screen. In numeric fields you can strip them before validating, or reject them explicitly, depending on your input policy. Don't strip them from general Arabic text: there they control the order of mixed Arabic/Latin words.

The fix: normalize, validate, then store one form

Normalization and validation are different steps: normalization changes the representation; validation decides whether the resulting value is allowed in your application.

Step one is a function that only normalizes: it converts Arabic-Indic and Persian digits to 0–9 and strips bidi marks (for numeric fields only):

// For numeric fields: strips bidi marks and converts ٠–٩ and ۰–۹ to 0–9; touches nothing else.
function normalizeDigits(input) {
  return input
    .replace(/[‎‏؜‪-‮⁦-⁩]/g, '') // bidi marks
    .replace(/[٠-٩]/g, (d) => String(d.charCodeAt(0) - 0x0660))     // ٠–٩ → 0–9
    .replace(/[۰-۹]/g, (d) => String(d.charCodeAt(0) - 0x06f0));    // ۰–۹ → 0–9
}

normalizeDigits('٠٥٠١٢٣٤٥٦٧'); // '0501234567'
normalizeDigits('٠50١٢٣٤٥٦٧'); // '0501234567' (mixed digits)
normalizeDigits('۰۵۰');        // '050'

Don't drop separators without validating, or ١٬٢ silently becomes 12. For amounts and decimals, check the format first:

// An amount like ١٬٢٥٠٫٥ or 1250.5: thousands separators only in valid positions; null otherwise.
function parseAmount(raw) {
  const s = normalizeDigits(raw).replace(/٫/g, '.').replace(/٬/g, ',');
  if (!/^(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?$/.test(s)) return null;
  return Number(s.replace(/,/g, ''));
}

parseAmount('١٬٢٥٠٫٥'); // 1250.5
parseAmount('١٢٫٥');    // 12.5
parseAmount('١٬٢');     // null

For phone numbers, normalizing digits isn't enough: 0501234567, +966501234567 and 00966501234567 are one number in three formats. Convert to one international form (E.164) and store that:

// Saudi mobile in local or international form → '+9665XXXXXXXX', or null if the format doesn't match.
// Spaces and hyphens are allowed because they're only formatting.
function toSaudiE164(raw) {
  const s = normalizeDigits(raw).replace(/[\s-]/g, '');
  if (/^05\d{8}$/.test(s)) return '+966' + s.slice(1);
  if (/^(?:\+|00)9665\d{8}$/.test(s)) return '+966' + s.replace(/^(?:\+|00)966/, '');
  return null;
}

toSaudiE164('٠٥٠١٢٣٤٥٦٧');        // '+966501234567'
toSaudiE164('+٩٦٦ ٥٠ ١٢٣ ٤٥٦٧');   // '+966501234567'
toSaudiE164('00966501234567');    // '+966501234567'
toSaudiE164('0501234567‏');  // '+966501234567'
toSaudiE164('٠٥٠١٢٣٤٥');          // null

This is a simplified example that checks the format only, not whether the number is assigned or active.

Three practical rules:

• Store the canonical form, not what the user typed: Western digits for numbers, E.164 for phone numbers, so the same value never exists in two forms and searches don't miss it.
• Normalize and validate on the server too. Browser validation can be bypassed, and requests may come from other clients.
• Don't rely on inputmode alone. inputmode="numeric" asks for a number keypad; it doesn't guarantee which digits you receive.

Displaying numbers: pick the numbering system explicitly

Display matters too. Don't rely on the default when you want Arabic or Western digits on screen. On Node 24.21 / ICU 78.3, new Intl.NumberFormat(locale).format(1234567.89) gives:

• ar: 1,234,567.89
• ar-SA and ar-EG: ١٬٢٣٤٬٥٦٧٫٨٩
• ar-AE: 1,234,567.89
• ar-MA: 1.234.567,89 (dot for thousands, comma for decimals)

Defaults differ by country and can change between ICU versions, so put the numbering system in the locale:

new Intl.NumberFormat('ar-SA-u-nu-latn').format(1234567.89); // '1,234,567.89'
new Intl.NumberFormat('ar-u-nu-arab').format(1234567.89);    // '١٬٢٣٤٬٥٦٧٫٨٩'

Use this for display only: never parse formatted text back into a number; keep the original numeric value.

Summary

• \d and Number() don't understand Arabic-Indic digits; \p{Nd} accepts too much and converts nothing.
• Normalize digits first, then validate the format, then store one canonical form (E.164 for phones), in the browser and on the server.
• Don't drop separators without validating, and strip bidi marks only from numeric fields.
• When displaying, set -nu-latn or -nu-arab explicitly.

Disclosure: my open-source library @kirnu/arabic-core has a tested toWesternDigits function that converts Arabic-Indic and Persian digits (and separators between digits). For a non-technical explanation of Arabic vs Western digits, there's a short guide on Kirnu (Arabic).

Have you hit this in your apps? Where do you normalize: in the browser, on the server, or in the database?

Disclosure: I maintain an open-source Hijri/Arabic library, mentioned at the end. Everything before that uses only built-in Intl.

Gregorian → Hijri with Intl

const fmt = new Intl.DateTimeFormat('en-u-ca-islamic-umalqura', {
  timeZone: 'UTC', year: 'numeric', month: 'numeric', day: 'numeric',
});

function toHijri(date: Date) {
  const p = Object.fromEntries(fmt.formatToParts(date).map((x) => [x.type, x.value]));
  return { year: parseInt(p.year), month: Number(p.month), day: Number(p.day) };
}

toHijri(new Date(Date.UTC(2024, 2, 11))); // { year: 1445, month: 9, day: 1 }  (1 Ramadan 1445)

Use formatToParts rather than parsing the formatted string: the string's layout changes with the locale (and with locales like ar, so do the digits), while the parts are stable.

That's the easy direction. Here are the four things that go wrong.

Trap 1: "islamic" isn't one calendar

ICU ships several Hijri variants, and they don't always agree. For 11 March 2024:

islamic-civil and islamic-tbla are arithmetic calendars (fixed rules for month lengths); islamic-umalqura uses ICU's data for the Umm al-Qura calendar published in Saudi Arabia. If your users are in Saudi Arabia (or you're matching government documents), ask for islamic-umalqura explicitly.

Trap 2: don't rely on the locale's default calendar

It's tempting to write new Intl.DateTimeFormat('ar-SA') and expect Hijri output. In Node 24 (ICU 78), that formats 11 March 2024 as ١١‏/٣‏/٢٠٢٤, a Gregorian date, and resolvedOptions().calendar is "gregory". Locale defaults are data, and data changes between runtime versions. Always put the calendar in the locale string (-u-ca-islamic-umalqura) or pass calendar: 'islamic-umalqura'.

Trap 3: time zones

A Date is an instant, not a calendar day. Take midnight on 11 March 2024 in Riyadh:

const d = new Date('2024-03-11T00:00:00+03:00');
// formatted with timeZone: 'UTC'          → 29 Sha'ban 1445  (it's still 10 March in UTC)
// formatted with timeZone: 'Asia/Riyadh'  → 1 Ramadan 1445

Pick one convention and stick to it. Either build dates with Date.UTC(...) and always format in UTC (what the snippets here do), or always pass the user's time zone. Mixing the two is where "the date is off by one" reports come from.

Trap 4: the official calendar isn't the announced date

Umm al-Qura is a calendar computed in advance. The start of Ramadan and the Eids, however, is usually decided by an official announcement based on moon sighting, so the observed date can differ from the calendar by a day, and can differ between countries. Your conversion can be correct and still not match the announced date, so say so in the UI wherever it matters (countdowns, Ramadan timetables).

Hijri → Gregorian: the direction Intl can't do

Intl only formats. There's no API that takes "1 Ramadan 1448" and gives you a Date. (The answer you'll often find, "use Intl.DateTimeFormat with an Islamic calendar", only covers the other direction.)

You can still build it on top of Intl: estimate the date, format it with the Hijri calendar, and step until the formatter agrees. The function below is my implementation of that search; Intl does the calendar work, the loop just finds the right day.

// Hijri → Gregorian with Intl alone: estimate, then step until the formatter agrees.
function hijriToGregorianIntl(year: number, month: number, day: number): Date {
  // A rough starting point near the start of the Hijri calendar; the mean Islamic year is ≈ 354.367 days.
  // It's only a starting guess: the loop corrects it using Intl.
  const estimate = Date.UTC(622, 6, 16) + ((year - 1) * 354.367 + (month - 1) * 29.53 + (day - 1)) * 86_400_000;
  let t = Math.floor(estimate / 86_400_000) * 86_400_000; // UTC midnight, so the result is the start of the day
  for (let i = 0; i < 60; i++) {
    const h = toHijri(new Date(t));
    const monthDiff = (year * 12 + month) - (h.year * 12 + h.month); // continuous month index
    const diff = monthDiff * 29.5 + (day - h.day);
    if (h.year === year && h.month === month && h.day === day) return new Date(t);
    t += Math.sign(diff) * Math.max(1, Math.round(Math.abs(diff))) * 86_400_000;
  }
  throw new RangeError('No such Hijri date in this calendar');
}

hijriToGregorianIntl(1448, 9, 1).toISOString(); // '2027-02-08T00:00:00.000Z'
hijriToGregorianIntl(1446, 9, 30); // throws: that Ramadan had 29 days

I checked this function against a table-based implementation on every valid Hijri date from 1356 to 1500 AH (51,383 dates, including every year boundary): all matched, using on average about 2 formatter calls per conversion and never more than 3. (Node 24.21 / ICU 78.3.)

Note the last line: Hijri months have 29 or 30 days, and which one varies by year (Ramadan was 30 days in 1445, 29 in 1446 and 30 in 1447). So validate Hijri input rather than assuming 30-day months.

Runtime support

The islamic-umalqura calendar comes from the runtime's ICU data. Node has shipped full ICU by default since version 13, and current browsers support the Islamic calendars through Intl, but older or stripped-down runtimes may not. Check new Intl.DateTimeFormat('en-u-ca-islamic-umalqura').resolvedOptions().calendar: if it doesn't say islamic-umalqura, you've silently fallen back to another calendar.

When a table beats Intl

The search above works, but a lookup table is better when:

• You convert a lot. In a rough benchmark (Node 24.21 on a Windows laptop, the 51,383 dates above converted in a loop, averaged), the Intl search took about 15 µs per date and a table lookup about 0.3 µs. Your numbers will differ; the gap is the point.

• You need the same answer everywhere. A table gives identical results in every browser, Node version and runtime, independent of the ICU data each one ships.

• You need month lengths, validation or date differences without probing the formatter.

I maintain @kirnu/arabic-core, a zero-dependency TypeScript library that includes the Umm al-Qura table for 1343–1500 AH (2 August 1924 to 16 November 2077). It agrees with Intl's islamic-umalqura on every day from 1937 to 2077 that I checked:

import { gregorianToHijri, hijriToGregorian, hijriMonthLength, HIJRI_RANGE } from '@kirnu/arabic-core';

gregorianToHijri({ year: 2024, month: 3, day: 11 }); // { year: 1445, month: 9, day: 1 }
hijriToGregorian({ year: 1448, month: 9, day: 1 });  // { year: 2027, month: 2, day: 8 }
hijriMonthLength(1446, 9);                            // 29
// Dates outside HIJRI_RANGE throw a HijriRangeError instead of guessing.

It also does Hijri ages and date differences, and (the reason it exists) Arabic number-to-words. If you only need a quick answer rather than code, there's a free online Hijri ↔ Gregorian converter built on the same table (Arabic interface). The library's source and tests are at github.com/getkirnu/arabic-core.

If you've hit a Hijri-date bug that isn't covered here, I'd like to hear about it in the comments.

Writing amounts in words isn't a niche need in the Arab world: cheques, invoices and contracts in Saudi Arabia, the UAE, Egypt and elsewhere write the amount in words, and on a cheque the words usually take precedence over the digits. The practice even has its own name, tafgeet (تفقيط).

This post walks through the rules an Arabic number-to-words engine has to model and what each one means for your code. All examples were generated by @kirnu/arabic-core, an open-source TypeScript library I work on that powers the tools on Kirnu, a free Arabic tools site. The Arabic examples use Modern Standard Arabic; regional spoken Arabic can differ.

Why a lookup table can't work

The correct output depends on information that isn't in the number:

• The gender of the counted noun. "Three books" and "three pages" use different words for three.
• Grammatical case. "Twelve" changes form when it's the object of a verb or follows a preposition.
• The number's range. 3–10, 11–19, the tens and the hundreds each follow different rules.
• The form of the noun. After 3–10 the noun is plural; after 11–99 it's singular; after 100 it's singular again but in a different case.
• The currency. Each currency has its own main and fractional unit, each with its own gender, and they don't all have 100 subunits.
• Fractions and, when needed, cheque format.

So an Arabic numberToWords(n) needs more inputs than n (at least gender and case), and converting amounts needs data about each currency. The library used here covers seven: the Saudi, Qatari and Omani riyal, the UAE dirham, the Egyptian pound, and the Kuwaiti and Bahraini dinar.

Let's go through the rules one at a time.

1. Numbers 3–10 take the opposite gender

The rule people forget most: from three to ten, the number takes the opposite gender of the noun. With a masculine noun it gets the feminine-looking ending -a (ة); with a feminine noun it drops it.

One and two do the opposite and agree with the noun: one book is كتاب واحد, one page is ورقة واحدة. Consequence for the API: your function needs to know the noun's gender, and a sensible default is masculine.

2. 11–19: two words, two rules

Compound numbers combine both behaviours. In fifteen, the "five" part follows the 3–10 rule (opposite gender) while the "ten" part agrees with the noun:

• masculine: خمسة عشر khamsata ʿashara
• feminine: خمس عشرة khamsa ʿashrata

So a single gender flag flips the two words in opposite directions, which means you can't generate each part independently. Eleven and twelve have their own forms: أحد عشر / إحدى عشرة for 11, and اثنا عشر / اثنتا عشرة for 12.

3. Grammatical case changes the word itself

"Twelve" is اثنا عشر in the nominative but اثني عشر in the accusative and genitive. The same goes for "two thousand" (ألفان → ألفين) and "twenty-two" (اثنان وعشرون → اثنين وعشرين). In "I received twelve orders", the nominative form would be a mistake. That's the second input your function needs: case, with nominative as the safe default when the number stands alone.

So far we've only produced the number. Real-world uses like invoices and cheques have a noun after it, and the noun has rules of its own.

4. The noun changes with the number

Even with the number right, the noun (say, Saudi riyal) changes across four ranges:

The adjective ("Saudi") follows the noun's form too. And the range is decided by the last two digits, not the whole number: 1250 ends in fifty, so the noun is singular accusative, giving ألف ومئتان وخمسون ريالاً سعودياً. Your code has to split the number into groups before it can pick the noun form.

5. Hundreds, thousands and spelling

• 200 is مئتان (a dual), 300 is ثلاثمئة, written as one word in modern spelling.
• Thousands follow the counted-noun rules: ألفان (2,000), ثلاثة آلاف (3,000), أحد عشر ألفاً (11,000).
• "Hundred" has a modern spelling (مئة) and a classic one (مائة). Both are in use, so make it an option: 1250 is ألف ومئتان وخمسون or ألف ومائتان وخمسون.
• Parts are joined with wa ("and"): 1,001,011 is مليون وألف وأحد عشر.

6. Currencies and fractions

For amounts, every rule above applies twice: once to the main unit and once to the subunit, including the subunit's gender.

• Saudi riyal: 100 halalas, and halala is feminine, so 0.25 is خمس وعشرون هللة, not the masculine خمسة وعشرون.
• Kuwaiti dinar: 1,000 fils (three decimal places), so 1.250 is دينار كويتي واحد ومئتان وخمسون فلساً.
• Egyptian pound: 100 piastres, so 3.03 is ثلاثة جنيهات مصرية وثلاثة قروش.

Plain fractions are read after the word fāṣila ("point"): 12.5 is اثنا عشر فاصلة خمسة. And cheques wrap the amount in فقط … لا غير ("only … nothing more") so nothing can be added before or after it:

فقط ألف ومئتان وخمسون درهماً إماراتياً وخمسون فلساً لا غير

7. Write the tests before the code

With this many interacting rules, a fix for one case easily breaks ten others. What worked for us: a table of hand-written cases reviewed for grammar (number, gender, case, expected output) that runs on every change, plus dedicated tests for the edge cases: 11 and 12, numbers ending in 01 and 02, dual thousands, zero, and Eastern Arabic digits (١٢٣) alongside Western ones (123).

Using @kirnu/arabic-core in JavaScript and TypeScript

All of the above is packaged as an MIT-licensed TypeScript library with no dependencies. It runs in the browser and in Node:

npm install @kirnu/arabic-core

import { tafgeet, currencyToWords } from '@kirnu/arabic-core';

// masculine noun (the default)
tafgeet(15);                                   // خمسة عشر

// feminine noun
tafgeet(15, { gender: 'feminine' });           // خمس عشرة

// grammatical case
tafgeet(12, { case: 'accusative' });           // اثني عشر

// Eastern Arabic digits with a decimal separator
tafgeet('١٢٫٥');                               // اثنا عشر فاصلة خمسة

// an amount in cheque format
currencyToWords('1250.50', 'SAR', { cheque: true });
// فقط ألف ومئتان وخمسون ريالاً سعودياً وخمسون هللة لا غير

Besides the seven currencies, it also removes Arabic diacritics (tashkeel), normalises Arabic text, and converts between Hijri (Umm al-Qura) and Gregorian dates.

• Source: https://github.com/getkirnu/arabic-core
• npm: https://www.npmjs.com/package/@kirnu/arabic-core
• Try it without code: Kirnu's number-to-words tool (Arabic interface)

If you find a case it gets wrong, or need another currency, please open an issue. Corrections from Arabic speakers are just as welcome.