0007 — i18n from day one — externalise strings, RTL-ready CSS · decision

Context

offplan.online targets EN at launch, AR (UAE) in Stage 2, and broader EU/APAC languages in Stage 3. Languages can be added in two ways: (a) build code English-only, retrofit i18n later when AR is needed; (b) build i18n-shaped from the first commit, ship English-only at launch. The retrofit path means touching ~500+ files across the codebase to extract hardcoded strings and audit CSS for RTL — costly and error-prone. The day-one path adds ~zero overhead because the discipline is identical to writing any UI string.

Decision

Build i18n-shaped from day one. Specifically:

Use i18next (React) — all UI strings live in src/i18n/en.json; no hardcoded text in components
Locale switcher infrastructure exists from launch — returns only "en" initially, but plumbing is in place
CSS uses logical properties (padding-inline-*, margin-block-*) — never -left / -right
Intl.NumberFormat and Intl.DateTimeFormat wrapped in shared helpers — no hardcoded date / number formats
IBM Plex Arabic loaded lazily on AR locale activation; fallback Noto Naskh Arabic → system
<html dir="..."> set programmatically based on selected locale

Codified in launch plan Phase 1.1.4 and brandbook v1.3 § Internationalisation.

Alternatives Considered

Retrofit later — build EN-only, add i18next when AR is needed. Rejected: ~500+ file touches, high regression risk, no time savings (work just shifts to a worse moment).
Skip locale switcher infrastructure at launch — set up i18next, but no UI to switch locales. Rejected: adding it later requires routing/state changes, not a simple JSON drop-in.
Use react-intl — also a solid choice. Rejected: i18next has a larger ecosystem, simpler nested key structure, better tooling (e.g. Lokalise integration).

Consequences

Small upfront discipline cost in Phase 1.1 (the foundation phase) — bundled with visual redesign work, minimal added time.
Adding Arabic in Stage 2 is a JSON drop-in plus font load, not a code refactor. Hours, not weeks.
Tech team needs to enforce the discipline in code review — every PR with hardcoded strings or -left/-right CSS gets bounced. Should be in the team's contributing guide.
IBM Plex Arabic is on Google Fonts; one extra <link> in <head>, no licensing cost.
CSS logical properties are widely supported (95%+ browsers); for any older support requirement, a PostCSS plugin auto-generates -left/-right fallbacks.

Revisit trigger

If tech team's i18next version becomes unmaintained — switch to react-intl or formatjs (data is portable, format is largely compatible).
If Arabic launches and translation quality reveals i18next's Trans component limitations for complex pluralisation/RTL bidi — evaluate ICU MessageFormat fallback.