[FEAT] Multi-Lingual Dynamic i18n Localization Engine & RTL Layout Support

[jotel-dev]

telegram link : t.me/nullifiersystem

---

1. Summary & Core Promise

Velo's mobile application currently has static translation files in mobile/frontend/src/i18n and a basic language toggle in mobile/frontend/src/components/LanguageSwitcher.tsx. However, the app lacks right-to-left (RTL) layout switching (e.g. for Arabic/Hebrew), localized currency formatting, missing-key fallback handlers, and real-time locale change persistence.

This feature implements a Multi-Lingual Dynamic i18n Localization Engine & RTL Layout Support System. It adds automatic document direction switching (dir="rtl" vs dir="ltr"), dynamic currency/number formatting for cash claim values, missing translation fallback logging, and local storage persistence in mobile/frontend/src/components/LanguageSwitcher.tsx.

---

2. Background & Architectural Risks

• UI Layout Distortion: Switching to RTL languages without dynamic CSS flexbox/grid direction flipping causes misaligned cash request buttons and Claim QR cards.
• Missing Translation Keys: Undefined translation keys rendering as raw string IDs (claim.trancheProgress) confuse non-English users during cash claims.

---

3. Database Layer Specifications

Migration SQL (033_add_user_locale_preferences.sql)

ALTER TABLE provider_profiles 
ADD COLUMN IF NOT EXISTS preferred_locale VARCHAR(10) NOT NULL DEFAULT 'en',
ADD COLUMN IF NOT EXISTS preferred_currency VARCHAR(5) NOT NULL DEFAULT 'USD';

---

4. Backend Route & Service Layer Specifications

Route: POST /api/v1/user/preferences

1. Updates preferred user locale and currency format settings.
2. Returns localized response payloads based on Accept-Language headers.

---

5. Background Processors / Workers

(Client-Side i18next Engine & Dynamic Locale Bundle Chunk Loader)

---

6. Frontend / UI Component Specifications

Component: mobile/frontend/src/components/LanguageSwitcher.tsx

• Language Selector Dropdown: Supports English, Spanish, French, Arabic (RTL), and Portuguese.
• Dynamic RTL Flipping: Automatically updates document.documentElement.dir to rtl when Arabic is selected.
• Currency Formatter: Formats cash amounts dynamically (e.g. $50.00 USD vs 50,00 €).

---

7. Rigor & Test Plan

1. Unit Tests (mobile/frontend/src/i18n/__tests__/i18n.test.ts): Verify translation key fallbacks and RTL document attribute toggles.
2. UI Layout Test (LanguageSwitcher.test.tsx): Render claim card under RTL locale; assert layout elements adjust text-align and flex direction.

---

8. Relevant Files Inventory

New Files to Create

• apps/api/src/db/migrations/033_add_user_locale_preferences.sql
• mobile/frontend/src/i18n/__tests__/i18n.test.ts
• mobile/frontend/src/components/__tests__/LanguageSwitcher.test.tsx

Existing Files to Modify

• mobile/frontend/src/components/LanguageSwitcher.tsx
• mobile/frontend/src/main.tsx
• mobile/frontend/src/index.css
• mobile/frontend/src/pages/ClaimQR.tsx
• apps/api/src/lib/i18n.ts

---

9. Acceptance Criteria

• Selecting Arabic dynamically switches application layout to RTL mode (dir="rtl").
• Missing translation keys fall back to English gracefully without rendering raw keys.
• User locale preferences persist across page reloads and API sessions.

---

10. Contributor Notes

• ⚠️ CSS Rule: ALWAYS use logical CSS properties (margin-inline-start, padding-inline-end) instead of fixed margin-left to support RTL layouts cleanly.

[Trovic1]

Kindly assign

[grantfox-oss]

🦊 GrantFox — @Trovic1 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #435)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.