feat: implement core-i18n package with decentralized namespace support and integrate into landing and web apps

2026-05-22 23:30:41 +07:00
parent 255704f867
commit 4655362ff4
25 changed files with 932 additions and 13 deletions
@@ -0,0 +1,183 @@
+# Enterprise i18n Architecture (`@repo/core-i18n`)
+
+A highly decoupled, type-safe internationalization engine for the Eigen Monorepo. 
+
+It uses a **Hybrid Namespace Strategy**:
+1. **Centralized Engine**: Setup, local persistence (`@repo/core-storage`), and global words (`common`).
+2. **Decentralized Dictionaries**: Feature-specific translations (`booking`, `billing`) live inside the application modules and are lazy-loaded.
+
+This architecture strictly adheres to **Inversion of Control (IoC)**. The core engine handles local state and performance, but leaves API and networking decisions entirely to the consuming applications.
+
+---
+
+## 1. App-Level Setup (Bootstrap)
+
+Initialize the engine *before* your React application mounts to prevent UI flashing.
+
+```tsx
+// apps/web/src/main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { setupI18n } from '@repo/core-i18n';
+import App from './app';
+
+async function bootstrap() {
+  // Synchronously reads preferred language from storage & inits i18next
+  await setupI18n();
+
+  createRoot(document.getElementById('app')!).render(
+    <StrictMode><App /></StrictMode>,
+  );
+}
+bootstrap();
+```
+
+---
+
+## 2. Module-Level Setup (Decentralized Dictionaries)
+
+Dictionaries live right next to the UI components that use them.
+
+### Folder Structure
+```text
+apps/web/src/apps/modules/booking/
+├── presentation/BookingTable.tsx
+└── locales/
+    ├── id/booking.json
+    └── en/booking.json
+```
+
+### Lazy Loading & Type Safety
+Register the namespace when the component mounts. To get native TypeScript autocomplete for nested keys (e.g., `header.title`), augment the global `react-i18next` types.
+
+**1. Augment Types:**
+```ts
+// apps/web/src/types/i18next.d.ts
+import 'react-i18next';
+import type { resources as coreResources } from '@repo/core-i18n/src/setup';
+import bookingEn from '../apps/modules/booking/locales/en/booking.json';
+
+declare module 'react-i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'common';
+    resources: typeof coreResources['en'] & { booking: typeof bookingEn };
+  }
+}
+```
+
+**2. Use in Component:**
+```tsx
+import { useEffect } from 'react';
+import { i18n, useTranslation } from '@repo/core-i18n';
+import bookingId from '../locales/id/booking.json';
+import bookingEn from '../locales/en/booking.json';
+
+export default function BookingFeature() {
+  const { t } = useTranslation(['common', 'booking']);
+
+  useEffect(() => {
+    i18n.addResourceBundle('id', 'booking', bookingId, true, false);
+    i18n.addResourceBundle('en', 'booking', bookingEn, true, false);
+  }, []);
+
+  return <h1>{t('booking:header.title')}</h1>; // Autocomplete works!
+}
+```
+
+---
+
+## 3. Real-World Implementation Flow
+
+The engine supports robust flows for authenticated apps, including Tenant Vocabulary Overrides and Backend Synchronization. 
+
+### A. The Tenant Override Flow (After Login)
+
+If "Company A" calls "Purchasing" -> "Procurement", they shouldn't need a custom build. The backend returns an override config, and the frontend dynamically merges it using `applyTenantOverrides`.
+
+```tsx
+// Example inside an AuthProvider or Post-Login useEffect
+import { useEffect } from 'react';
+import { applyTenantOverrides } from '@repo/core-i18n';
+import { api } from '@/api';
+
+export function AuthProvider({ children }) {
+  useEffect(() => {
+    async function fetchTenantConfig() {
+      try {
+        // 1. Fetch tenant-specific overrides from the API
+        const response = await api.get('/v1/tenant/i18n-config');
+        
+        // 2. Inject into the engine. 
+        // `deep: true` ensures only provided keys are overridden.
+        applyTenantOverrides(
+          response.data.namespace, 
+          response.data.overrides
+        );
+      } catch (err) {
+        console.error("Failed to fetch tenant configuration", err);
+      }
+    }
+    
+    fetchTenantConfig();
+  }, []);
+
+  return <>{children}</>;
+}
+```
+
+### B. User Preference Sync (With Rollback)
+
+When a logged-in user changes their language, we update the UI instantly, save it locally, and sync it to the backend. If the backend fails, the engine automatically rolls back.
+
+```tsx
+import { changeLanguage } from '@repo/core-i18n';
+import { api } from '@/api';
+
+const handleSwitch = async (newLng: string) => {
+  try {
+    await changeLanguage(newLng, async (lng) => {
+      // The core engine waits for this Promise. 
+      // If it throws, the UI reverts to the previous language automatically.
+      await api.patch('/v1/user/profile', { language: lng });
+    });
+    toast.success('Language saved!');
+  } catch (err) {
+    toast.error('Sync failed. Reverted to previous language.');
+  }
+};
+```
+> [!NOTE]
+> For public pages (like `apps/landing`), simply call `changeLanguage('en')` without the callback function. It will update the UI and local storage instantly without hitting the network.
+
+---
+
+## 4. Backend API Contract (For Backend Engineers)
+
+To support Dynamic Tenant Overrides, the backend must expose an endpoint (e.g., `GET /v1/tenant/i18n-config`).
+
+### Identification
+The backend **MUST identify the tenant via the `Authorization` (JWT) header**. The frontend will not send `tenantId` in the query payload to prevent spoofing.
+
+### Expected JSON Response Format
+The response must match the structural shape of the frontend dictionary. Because the frontend uses a **Deep Merge** strategy, the backend **only needs to return the specific keys the tenant wishes to override**. 
+
+If the frontend dictionary has `header.title` and `header.subtitle`, and the backend only sends `header.title`, the `subtitle` will safely remain intact.
+
+**Example Request:**
+`GET /v1/tenant/i18n-config`
+*(Authorization: Bearer eyJhbG...)*
+
+**Expected Response (200 OK):**
+```json
+{
+  "data": {
+    "namespace": "booking",
+    "overrides": {
+      "module_name": "Procurement",
+      "header": {
+        "title": "Procurement List"
+      }
+    }
+  }
+}
+```
@@ -0,0 +1,26 @@
+{
+  "name": "@repo/core-i18n",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./react-i18next": "./src/react-i18next.d.ts"
+  },
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@repo/core-storage": "workspace:*",
+    "@repo/utils": "workspace:*",
+    "i18next": "^24.2.2",
+    "react-i18next": "^15.4.0"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@types/react": "^19.0.8",
+    "typescript": "5.5.4"
+  }
+}
@@ -0,0 +1,4 @@
+export { setupI18n, type SupportedLanguage } from './setup';
+export { changeLanguage, applyTenantOverrides } from './manager';
+export { useTranslation, Trans } from 'react-i18next';
+export { default as i18n } from 'i18next';
@@ -0,0 +1,12 @@
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "success": "Success",
+    "error": "Error",
+    "settings": "Settings",
+    "loading": "Loading...",
+    "delete": "Delete",
+    "edit": "Edit"
+  }
+}
@@ -0,0 +1,12 @@
+{
+  "common": {
+    "save": "Simpan",
+    "cancel": "Batal",
+    "success": "Sukses",
+    "error": "Galat",
+    "settings": "Pengaturan",
+    "loading": "Memuat...",
+    "delete": "Hapus",
+    "edit": "Ubah"
+  }
+}
@@ -0,0 +1,56 @@
+import i18n from 'i18next';
+import { demoSecureStorage, StorageKey } from '@repo/core-storage';
+
+/**
+ * Changes the active language, saves the preference locally, and optionally syncs with the backend.
+ *
+ * @param newLng The new language code (e.g., 'en', 'id')
+ * @param syncCallback An optional callback to sync the preference to the backend. It receives the new language and the previous language.
+ */
+export async function changeLanguage(
+  newLng: string,
+  syncCallback?: (newLng: string, prevLng: string) => Promise<void>
+): Promise<void> {
+  const prevLng = i18n.language;
+  
+  if (prevLng === newLng) return;
+
+  // 1. Update local storage & i18next optimistically
+  await demoSecureStorage.setItem(StorageKey.LOCALE, newLng);
+  await i18n.changeLanguage(newLng);
+
+  // 2. Trigger optional backend sync
+  if (syncCallback) {
+    try {
+      await syncCallback(newLng, prevLng);
+    } catch (error) {
+      console.error('[i18n] Backend sync failed, rolling back language', error);
+      // Rollback on failure
+      await demoSecureStorage.setItem(StorageKey.LOCALE, prevLng);
+      await i18n.changeLanguage(prevLng);
+      throw error; // Rethrow so the caller can show an error toast
+    }
+  }
+}
+
+/**
+ * Injects tenant-specific vocabulary overrides dynamically at runtime.
+ *
+ * Uses a deep-merge strategy. Overrides are applied to the currently active language,
+ * or across all loaded languages if needed.
+ *
+ * @param namespace The i18n namespace to override (e.g., 'common', 'booking')
+ * @param overrides A deeply nested object containing the overridden string keys and values.
+ * @param lng Specific language to override. Defaults to currently active language.
+ */
+export function applyTenantOverrides(
+  namespace: string,
+  overrides: Record<string, unknown>,
+  lng?: string
+): void {
+  const targetLng = lng || i18n.language;
+  
+  // deep: true -> merges with existing keys rather than replacing the whole namespace
+  // overwrite: true -> allows replacing existing specific keys
+  i18n.addResourceBundle(targetLng, namespace, overrides, true, true);
+}
@@ -0,0 +1,9 @@
+import 'react-i18next';
+import type { resources } from './setup';
+
+declare module 'react-i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'common';
+    resources: typeof resources['en'];
+  }
+}
@@ -0,0 +1,57 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import { demoSecureStorage, StorageKey } from '@repo/core-storage';
+import commonEn from './locales/en/common.json';
+import commonId from './locales/id/common.json';
+
+const DEFAULT_LANGUAGE = 'id';
+const SUPPORTED_LANGUAGES = ['en', 'id'] as const;
+
+export type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
+
+export const resources = {
+  en: { common: commonEn.common },
+  id: { common: commonId.common },
+} as const;
+
+/**
+ * Bootstraps the central i18n engine.
+ * 
+ * This reads the preferred locale from secureStorage and initializes
+ * i18next synchronously before React renders.
+ */
+export async function setupI18n(): Promise<void> {
+  let initialLng = DEFAULT_LANGUAGE;
+  try {
+    const storedLng = await demoSecureStorage.getItem<string>(StorageKey.LOCALE);
+    if (storedLng && SUPPORTED_LANGUAGES.includes(storedLng as SupportedLanguage)) {
+      initialLng = storedLng;
+    }
+  } catch (err) {
+    console.warn('[i18n] Failed to read locale from storage', err);
+  }
+
+  await i18n
+    .use(initReactI18next)
+    .init({
+      resources,
+      lng: initialLng,
+      fallbackLng: DEFAULT_LANGUAGE,
+      defaultNS: 'common',
+      interpolation: {
+        escapeValue: false, // React already escapes values
+      },
+    });
+
+  // Apply initial language to the DOM for SEO/Accessibility
+  if (typeof document !== 'undefined') {
+    document.documentElement.lang = i18n.language;
+  }
+
+  // Ensure DOM updates whenever the language changes later
+  i18n.on('languageChanged', (lng) => {
+    if (typeof document !== 'undefined') {
+      document.documentElement.lang = lng;
+    }
+  });
+}
@@ -0,0 +1,9 @@
+{
+  "extends": "@repo/typescript-config/library.json",
+  "include": ["src"],
+  "compilerOptions": {
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}