Skip to main content

Localize Native Digits Without Hard-Coded Western Numerals

2026-11-19

Localize Native Digits Without Hard-Coded Western Numerals

An Arabic build shows "١٥ عنصر" in the sidebar and "15 items" in the catalog. Both counts came from the same product. One path ran a hand-written arabicDigits map; the other called Intl.NumberFormat with default options and got Western digits. Reviewers catch the mismatch in screenshots. Users type ٠-٩ into search boxes that only parse 0-9. A product that wants Western digits inside an Arabic UI reaches for string replace instead of the Unicode nu extension. Native digits are not a cosmetic replace. They are a locale numbering system, and display policy, input acceptance, and parsing have to agree.

This guide is for mobile and web engineers and localization leads who already format numbers with locale-aware APIs, as covered in localizing app dates, times, and numbers, and who need the digit repertoire itself to be correct. It does not reopen compact suffixes, decimal separators, or currency symbols; those sit on top of the numbering system you choose here.

The short answer

  1. Treat digit shape as a numbering system (latn, arab, arabext, deva, and the rest of CLDR), not as a table of character swaps.
  2. Format with the platform API (Intl.NumberFormat numberingSystem, ICU NumberingSystem, Apple Locale.NumberingSystem) using the app's selected locale and product policy.
  3. Normalize every accepted digit set to a locale-invariant number on input, then format again on output. Do not parse display strings back.
  4. Keep shell, screens, exports, and accessibility labels on one system for a given locale and preference.
  5. When Western digits are required inside an Arabic product, set nu / numberingSystem (ar-u-nu-latn) instead of replacing glyphs after the fact.

Why hard-coded digits fail

CLDR defines numbering systems as first-class locale data. Unicode's LDML Part 3 describes numeric systems with an explicit digit sequence and algorithmic systems such as traditional Hebrew or Chinese spellout. For Arabic that should keep Western digits, the same document shows the locale ID ar-u-nu-latn. ICU's NumberingSystem class is the runtime face of that data: it covers simple alternate digits such as Thai and Devanagari as well as algorithmic systems, and it exposes a convenience LATIN instance for ASCII 0-9.

The web API is the same idea under a shorter name. MDN's Intl.NumberFormat constructor accepts a numberingSystem option (arab, hanidec, mathsans, and others) and the Unicode extension key nu. When both are set, the options property wins. Intl.Locale.prototype.getNumberingSystems() returns the numbering systems commonly used for a locale. Apple documents Locale.NumberingSystem as the Foundation equivalent.

A character map cannot keep up with that. It usually knows one Arabic block, forgets Extended Arabic-Indic (Persian/Urdu) digits, ignores Devanagari, and never learns that some products want arab while others want latn under the same ar language tag. LegendApp's legend-spark #328 is a concrete author report: the Kitchen Sink shell converted numbers with a hand-written arabicDigits helper while screens used JavaScript defaults, so Arabic captures mixed digit systems until reviewers flagged them. Replace hand-rolled arabicDigits maps with the shared formatter; they drift from Intl.NumberFormat and produce mixed digit systems between shell chrome and screen content. The fix they sketched matches that: pick one system per locale (what Intl.NumberFormat("ar") returns, or the system default) and use that formatter everywhere, including the shell.

Separate display policy from input normalization

Two different failures hide under "support Arabic digits."

Display policy answers which glyphs the product shows. Some Arabic products follow the locale default and show Arabic-Indic digits. Others keep Western digits for prices, analytics, or brand reasons while the surrounding copy is Arabic. That is a product decision, not a keyboard accident. Encode it as a locale with an explicit numbering system, for example ar-u-nu-arab or ar-u-nu-latn, or as new Intl.NumberFormat(appLocale, { numberingSystem: "latn" }).

Input normalization answers which glyphs the user may type. Keyboards and pasteboards will still produce ٠-٩ and ۰-۹ even when you display Western digits. Yabish expert-ai #220 states the acceptance criteria clearly: normalize Arabic-Indic and Eastern Arabic-Indic digits in questions and filters before the agent sees them, and apply an output digit preference in UI and exports. Separate input normalization from output digit preference: accept ٠-٩ and ۰-۹ on the way in even when the product prints Western 0-9, and apply the preference only through the shared formatter on the way out. Collapsing them into one "Arabic mode" boolean is how shell and content drift apart.

Stack Overflow threads show the same split from the other direction. Question 31439604 (score 120) asks how to convert Persian/Farsi ۰-۹ and Arabic-Indic ٠-٩ to English 0-9. Question 11766726 (score 70) asks for the same conversion. Those are author reports about inbound text. They are not a license to format outbound UI with the same replace tables.

Format with the platform numbering system

Web

function formatCount(value, appLocale, numberingSystem) {
  const options = { maximumFractionDigits: 0 };
  if (numberingSystem) options.numberingSystem = numberingSystem;
  return new Intl.NumberFormat(appLocale, options).format(value);
}

// Product wants Western digits in Arabic UI:
formatCount(15, "ar", "latn"); // "15"

// Locale default digits for ar (often Arabic-Indic on full ICU):
formatCount(15, "ar"); // locale-dependent, commonly "١٥"

Prefer passing numberingSystem (or a locale string that already carries -u-nu-...) into one shared formatter factory. Do not keep a parallel toArabicDigits(str) helper for chrome and a raw NumberFormat for screens. That is the legend-spark failure mode.

Force Western digits inside an Arabic UI with numberingSystem or the nu Unicode extension (ar-u-nu-latn), not with post-format character replacement.

Resolve the system once per session

function resolveNumberingSystem(appLocale, productPreference) {
  if (productPreference) return productPreference; // "latn" | "arab" | ...
  const loc = new Intl.Locale(appLocale);
  if (typeof loc.numberingSystem === "string" && loc.numberingSystem) {
    return loc.numberingSystem;
  }
  if (typeof loc.getNumberingSystems === "function") {
    return loc.getNumberingSystems()[0];
  }
  return undefined; // let NumberFormat choose
}

Call that once when the app locale or user preference changes, then inject the result into every number, currency, unit, and compact formatter. Compact notation and currency style still sit on top of the same numbering system; they do not replace it.

Apple and ICU

On Apple platforms, read and set numbering through Locale.NumberingSystem and format with NumberFormatter / FormatStyle using a locale that carries the system you want. On Android and other ICU hosts, construct or select an ICU NumberingSystem and apply it to the formatter rather than mapping code points after format() returns. ICU's number formatting guide also points at legacy NumberFormat parsing for localized digit strings when you must accept inbound text; prefer parsing into a binary numeric type once, then format outbound with the chosen system.

Normalize input without trusting display strings

Users will type native digits even when your UI prints Western ones. Accept the sets you claim to support, map them to 0-9 (or directly to an integer), and reject anything else with a clear error.

const DIGIT_RANGES = [
  [0x0660, 0x0669], // Arabic-Indic
  [0x06F0, 0x06F9], // Extended Arabic-Indic (Persian)
  [0x0966, 0x096F], // Devanagari
  [0x0030, 0x0039], // Latin
];

function normalizeDigits(raw) {
  let out = "";
  for (const ch of raw) {
    const cp = ch.codePointAt(0);
    let mapped = null;
    for (const [start, end] of DIGIT_RANGES) {
      if (cp >= start && cp <= end) {
        mapped = String(cp - start);
        break;
      }
    }
    if (mapped === null) {
      if (/\s|[,._]/.test(ch)) continue; // handle separators elsewhere
      throw new Error("unsupported character in number");
    }
    out += mapped;
  }
  return out;
}

Use a tested library or ICU parse when you can; the sketch above is a recommendation for the contract, not a claim that a ten-line map is complete. Question 13780391 shows QString.toInt and a broad QLocale failing on U+0662, which is exactly the production bug you get when parse and format disagree.

Never round-trip through the display string. Store the numeric value (or a plain ASCII decimal in a wire format), format for the current preference on the way out, and keep the exact value available for accessibility labels and exports that need Western digits.

Keep every surface on one system

Mixed digits are a review failure even when each widget is localized on its own. Apply one resolved numbering system to:

  • Navigation chrome and badge counts
  • In-list metrics and empty states
  • Charts, CSV/PDF exports, and share sheets
  • Push payloads and in-app messages that embed numbers
  • VoiceOver / TalkBack strings that speak the value

If export consumers require Western digits, that is an output preference for that channel, not a reason to leave the UI mixed. Expert-ai #220's split between normalized input and preferred output is the pattern: one preference per channel, applied through the same formatter factory.

Verification checklist

  1. For each supported locale, print 0, 15, 1500, and a decimal with the shared factory; confirm the digit repertoire matches the product policy.
  2. Paste Arabic-Indic, Extended Arabic-Indic, and Latin digits into every numeric field; confirm parse succeeds and the stored value is identical.
  3. Flip the output preference (or nu override) and confirm shell, screens, and export samples change together.
  4. Snapshot Arabic (and Persian, Hindi if you ship them) screens at the same count; fail the test if two digit systems appear in one capture.
  5. Confirm accessibility labels expose the numeric value, not only a pre-shaped string from a one-off map.

Common mistakes

  • Replacing digits after format(). You fight currency symbols, minus signs, and compact suffixes. Set numberingSystem / nu instead.
  • One boolean for "Arabic digits." Display policy and input acceptance are different. A user can type ١٥ while the product prints 15.
  • Parsing only Latin digits. Search, filters, and OTP fields will fail for real keyboards.
  • Per-screen helpers. The legend-spark report exists because the shell and the screens disagreed. One factory.
  • Assuming ar always means Arabic-Indic. Many hosts honor ar-u-nu-latn, and some default differently across OS versions. Resolve and test.

What to do next

Pick one screen that already shows a count in Arabic or Persian. Route that count through a shared NumberFormat factory with an explicit numbering system, add input normalization on its field, and add a screenshot test that fails if Western and Arabic-Indic digits both appear. Then delete the local arabicDigits helper. Once that path is clean, apply the same factory to compact numbers, currencies, and the rest of the formatting stack so digit shape stops being a special case.