Internationalization (i18n) & Localization Architecture

This document is the authoritative engineering specification for internationalization (i18n), multi-language localization, regional dialect support, and Nigerian currency formatting across the Debelu platform. Grounded directly in [packages/core/src/services/i18n.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/core/src/services/i18n.ts), [I18nContext.tsx](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/core/src/contexts/I18nContext.tsx), and the root i18next framework dependencies, this specification details locale detection strategies, namespace partitioning, and currency representation.

---

1. System Overview & Multi-Language Framework

Debelu serves a diverse student and merchant population across Nigerian federal, state, and private university campuses. The internationalization architecture utilizes i18next and react-i18next with modular namespace loading, dynamic browser language detection, and native Right-to-Left (RTL) support.

graph TD
    UserClient[Client Browser / Mobile App] --> Detector[i18next Language Detector]
    
    Detector -->|Resolution Hierarchy| P1[1. Member Profile Saved Locale]
    P1 -->|Fallback| P2[2. Browser LocalStorage: debelu_locale]
    P2 -->|Fallback| P3[3. HTTP Accept-Language Header / Navigator]
    P3 -->|Fallback| P4[4. Default Locale: en (English)]
    
    Detector --> Engine[i18n Service Engine: i18n.ts]
    Engine --> NSLoader[HttpBackend Namespace Loader]
    
    NSLoader --> NS_Common[(common.json)]
    NSLoader --> NS_Orders[(orders.json)]
    NSLoader --> NS_Buyer[(buyer.json)]
    NSLoader --> NS_Vendor[(vendor.json)]
    
    Engine --> I18nProvider[I18nProvider React Context]
    I18nProvider --> useTranslation[useTranslation Hook in Components]

---

2. Supported Campus Locales

Debelu natively supports seven languages reflecting Nigerian regional diversity, Islamic student communities, and Pan-African exchange networks:

Locale Code (SupportedLocale)	Language Name	Native Name	Script Direction	Regional Scope / Target Universities
en (Default)	English	English	LTR	Universal across all Nigerian universities and official banking interfaces.
ha	Hausa	Hausa	LTR	Northern campuses (ABU Zaria, BUK Kano, UDUS Sokoto).
yo	Yoruba	Yorùbá	LTR	Southwestern campuses (UNILAG, UI Ibadan, OAU Ile-Ife).
ig	Igbo	Asụsụ Igbo	LTR	Southeastern campuses (UNN Nsukka, UNIZIK Awka, FUTO Owerri).
ar	Arabic	العربية	RTL	Islamic student societies and regional bilingual scholars.
fr	French	Français	LTR	International students from Francophone ECOWAS neighboring states (Benin, Togo, Cameroon).
sw	Swahili	Kiswahili	LTR	Pan-African collegiate exchange programs.

---

3. Translation Namespace Architecture

To prevent large translation bundle downloads on cellular connections, translations are partitioned across 16 lazy-loaded JSON namespaces (TranslationNamespace):

packages/core/src/locales/<locale>/
├── common.json                             # Global buttons, navigation labels, search placeholders
├── auth.json                               # Sign-in, sign-up, OTP, and session handoff strings
├── buyer.json                              # Storefront discovery, filters, and campus selection
├── vendor.json                             # Store setup, KYC upload, and inventory dashboard
├── admin.json                              # Operations console, approvals, and reconciliation
├── errors.json                             # RFC 7807 localized human-readable error descriptions
├── validation.json                         # Zod schema validation error messages
├── notifications.json                      # In-app push notifications and alert bodies
├── chat.json                               # Buyer-vendor messaging and ChatGuard warnings
├── orders.json                             # Order tracking, PIN delivery dialogs, and escrow states
├── products.json                           # Product card attributes, conditions, and stock alerts
├── wallet.json                             # Payout balances, bank verification, and statements
├── settings.json                           # Profile preferences, delivery addresses, and security
├── legal.json                              # Terms of Service and Privacy Policy summaries
├── marketing.json                          # Brand landing pages and student ambassador perks
└── pwa.json                                # Offline notices and PWA install prompts

3.1 Lazy Namespace Consumption in Components

Components request only the namespaces required for their active view:

import { useTranslation } from 'react-i18next';

export function DeliveryPinModal() {
  const { t } = useTranslation(['orders', 'common']);

  return (
    <div>
      <h2>{t('orders:delivery_pin_title')}</h2>
      <p>{t('orders:delivery_pin_instructions')}</p>
      <button>{t('common:confirm')}</button>
    </div>
  );
}

---

4. Currency, Number & Date Formatting Standards

All financial values on Debelu are calculated and stored in Nigerian Kobo (bigint) and formatted for display via the centralized formatter utilities in @debelu/ui/lib/formatters.ts.

4.1 Naira Currency Formatting

$$\text{Display Amount} = \frac{\text{Amount in Kobo}}{100.00}$$

// @debelu/ui/lib/formatters.ts
export function formatCurrency(amountKobo: number | bigint, locale: SupportedLocale = 'en'): string {
  const naira = Number(amountKobo) / 100;
  return new Intl.NumberFormat(locale === 'ha' || locale === 'yo' || locale === 'ig' ? 'en-NG' : locale, {
    style: 'currency',
    currency: 'NGN',
    currencyDisplay: 'narrowSymbol', // Renders '₦'
    minimumFractionDigits: 0,
    maximumFractionDigits: 2,
  }).format(naira);
}

4.2 Numeric Typography (tabular-nums)

All monetary displays and balance tables apply the CSS class tabular-nums (font-variant-numeric: tabular-nums). This guarantees fixed-width digit alignment, preventing visual horizontal jitter when order prices or wallet balances update in real-time.

---

5. Right-to-Left (RTL) Layout Adaptation

When the active locale is Arabic (ar), the application automatically toggles document directionality:

1. document.documentElement.dir = 'rtl' and document.documentElement.lang = 'ar' are set dynamically.
2. Tailwind CSS logical properties (ms-*, me-*, ps-*, pe-*, start-*, end-*) automatically invert margins, paddings, and absolute positioning without custom CSS overrides.
3. Radix UI sheet drawers and mobile navigation menus slide out from the right rather than the left.

---

6. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Localization Engineer	Complete enterprise internationalization specification covering 7 campus languages, 16 lazy namespaces, Naira currency formatting, and RTL support.	Active Living Standard