i18n-rtl-l10n

i18n, RTL & Localization

One contract: store canonical, localize at render. Every conversion and formatting lives in one l10n layer; feature widgets receive value objects and already-localized strings, never raw formatting logic. RTL is a layout discipline, not a translation task — author with logical geometry so it mirrors by construction. Applies to any app that ships more than one locale or any RTL locale (Arabic, Persian, Hebrew, Sorani Kurdish, Urdu).

Read the reference for the task at hand:

• references/arb-and-icu.md — the ARB add/translate workflow, l10n.yaml, ICU plural/select, placeholder typing.
• references/rtl-and-bidi.md — the directional-geometry allow/ban table, icon mirroring, bidi isolation, CustomPainter pinned LTR, RTL charts.
• references/numerals-and-calendars.md — digit systems, separator traps, format/parse, calendar projection.
• references/unsupported-locales.md — shipping a locale flutter_localizations has no data for: the probe, the vendored delegate trio, delegate ordering, font coverage.

Run scripts/check_arb_parity.sh and scripts/check_i18n_bans.sh before a PR.

Non-negotiable rules

1. Every user-facing string goes through gen-l10n. Add the key to the template app_en.arb first, then read it via AppLocalizations.of(context). Set nullable-getter: false in l10n.yaml so the getter is non-null and a missing/typo key is a compile error, not a silent empty widget. Never hardcode a literal in Text, tooltip:, label:, hint:, or semanticsLabel:. Never call AppLocalizations.of above the Localizations scope (e.g. in main() before runApp).
2. Key + placeholder parity across all locales. A key present in the template but missing in a locale silently ships the template language; a renamed placeholder breaks that translation at runtime. Keep every key and every {placeholder} name identical — check_arb_parity.sh gates it.
3. Build sentences and plurals with ICU, never concatenation. Use {count, plural, ...} and {x, select, ...} in the ARB. Word order and plural categories differ per language (Arabic has six CLDR forms: zero/one/two/few/many/other). Concatenation produces grammatically wrong output and can't survive RTL reordering.
4. Direction is a locale consequence, never hardcoded. Wire localizationsDelegates + supportedLocales on MaterialApp and drive the active locale from state. A root Directionality(TextDirection.rtl) hides physical-side bugs and breaks LTR islands. RTL follows the resolved locale via GlobalWidgetsLocalizations with zero per-widget code — but only for locales flutter_localizations actually ships (rule 10). For any other, direction silently falls back to LTR. Assert Directionality.of per locale rather than assuming.
5. Directional-only geometry from the first commit. Use EdgeInsetsDirectional, AlignmentDirectional, PositionedDirectional, TextAlign.start/end, MainAxisAlignment.start/end, BorderRadiusDirectional, Icons.adaptive.*. Never EdgeInsets.only(left/right), Alignment.centerLeft/Right, Positioned(left/right:), TextAlign.left/right, or Icons.arrow_back. A grep gate rejects the PR.
6. Store canonical: UTC epoch + ASCII digits. Persist dateTime.toUtc().millisecondsSinceEpoch and Western/Latin digits. Calendars and numeral systems are pure display projections. Schedule off the epoch/DateTime, never off Jalali/Hijri arithmetic — leap/month-length quirks stay calendar-independent.
7. Normalize every numeric input to ASCII before parse or storage — digits AND separators. Use double.parse(normalizeToAscii(text)); never int.parse(text) on raw input (a Persian/Arabic soft keyboard yields ۱۲۳ / ١٢٣ and 1٫5).
8. Isolate strong-LTR technical runs (account/order/reference numbers, phone, email, URL, product codes) with one FSI/PDI helper at the view layer only. Never let isolate characters (U+2066–U+2069) reach storage, search, or export — strip at the boundary.
9. Bundle fonts that cover your scripts, with fallback; no runtime font fetch. Set a theme fontFamily plus fontFamilyFallback so Arabic/Persian glyphs never tofu. Avoid google_fonts in an offline/no-telemetry app — it fetches at runtime. Prove coverage from the font's own cmap, not a specimen: script coverage is not language coverage — a face that draws Persian can be missing the seven letters Sorani adds, and a specimen set in Arabic never shows it.
10. A locale flutter_localizations does not ship needs three vendored delegates, ordered first. gen-l10n localizes your strings; Flutter's own chrome and the ambient TextDirection come from a different catalog. Vendor MaterialLocalizations, CupertinoLocalizations and WidgetsLocalizations borrowing a script neighbour, each claiming only that language code, and place them ahead of the Global* delegates — which AppLocalizations.localizationsDelegates already contains. WHY: the missing Material delegate asserts on the first Tooltip, and the Widgets fallback claims every locale while hardcoding TextDirection.ltr, so fixing only the Material half yields an RTL app that reads backwards and never crashes. See references/unsupported-locales.md.