MAGIK-922: i18n Foundation — Translation Framework & Locale Detection #101
Description
Story 1 — i18n Foundation: Translation Framework & Locale Detection
Epic: EPIC-010 — Global Internationalization & Multi-Language Support (GitHub #100)
Priority: P0
User Story
As a MagikTap developer, I want a centralized translation framework with automatic locale detection, so all UI strings can be rendered in the user's preferred language.
Requirements
CodeIgniter 4 Language Integration
- Configure CI4
Languageservice with supported locales:en,es,ar,am,ti - Set default locale to
eninApp.phpconfig - Create language namespace structure:
Language/{locale}/{group}.php - Groups:
common,auth,dashboard,cards,profile,notifications,leads,tickets,finance,admin
Locale Detection & Persistence
- Check priority order: (1)
?lang=xxquery param → (2) sessionlocale→ (3) cookiemagiktap_locale→ (4)Accept-Languageheader → (5) defaulten - Store selected locale in session AND cookie (30-day expiry)
- Create
LocaleFilter(CI4 Before filter) to set locale on every request - Register filter globally in
Filters.php
Base Controller Integration
- Add
$localeproperty toBaseController - Pass
$localeto all views automatically via$this->data[locale] - Set HTML
langattribute dynamically inlayouts/main.php
Helper Function
- Create
i18n_helper.phpwith:t(string $key, array $params = []): string— shorthand forlang()format_number(float $n, string $locale): string— locale-aware number formattingformat_date(string $date, string $locale, string $format = 'medium'): string— locale-aware date formattingformat_currency(float $amount, string $currency, string $locale): string— locale-aware currency display
Acceptance Criteria
| # | Criteria | Priority |
|---|---|---|
| 1 | CI4 Language service configured with 5 locales | P0 |
| 2 | LocaleFilter sets locale from session/cookie/header |
P0 |
| 3 | ?lang=xx query param overrides and persists locale |
P0 |
| 4 | All views receive $locale variable |
P0 |
| 5 | <html lang="xx"> renders dynamically |
P0 |
| 6 | t() helper resolves translation keys |
P0 |
| 7 | Fallback to English for missing translations | P1 |
| 8 | Number/date/currency formatting respects locale | P1 |
Files to Create
app/app.portalv2/app/Filters/LocaleFilter.phpapp/app.portalv2/app/Helpers/i18n_helper.phpapp/app.portalv2/app/Language/en/(directory structure)
Files to Modify
app/app.portalv2/app/Config/App.php— supported localesapp/app.portalv2/app/Config/Filters.php— register LocaleFilterapp/app.portalv2/app/Controllers/BaseController.php— locale property + view dataapp/app.portalv2/app/Views/layouts/main.php— dynamiclangattribute