@gaurav_bhandari/common-frontend-services 1.0.0

package/src/services/i18n-Service/docs/WhatIsI18nService.md

@@ -0,0 +1,108 @@
+# I18nService
+
+The `I18nService` provides a lightweight, framework-agnostic solution for managing translations and multiple languages in your application.
+
+## Overview
+
+This service handles loading translation files (JSON), managing the active locale, and interpolating dynamic values into translated strings.
+
+### Key Features
+
+- **Lazy Loading**: Translation files are only loaded when needed.
+- **Nested Keys**: Support for dot notation (e.g., `dashboard.title`).
+- **Interpolation**: Simple value replacement (e.g., `Hello {name}`).
+- **Framework Agnostice**: Can be used with any UI library.
+
+## How to Use
+
+### 1. Structure
+
+Place your translation files in the `locales/` directory.
+
+```
+/i18n-Service/locales/
+  ├── en.json
+  ├── es.json
+  └── fr.json
+```
+
+**Example `en.json`**:
+
+```json
+{
+  "welcome": "Welcome, {name}!",
+  "buttons": {
+    "save": "Save Changes"
+  }
+}
+```
+
+### 2. Initialization
+
+Initialize the service at your application entry point.
+
+```typescript
+import { i18nService } from "@/i18n-Service/i18nService";
+
+async function initApp() {
+  await i18nService.init("en"); // Sets default language
+  // mount app...
+}
+```
+
+### 3. Usage
+
+Use the `t()` method to translate keys.
+
+```typescript
+import { i18nService } from "@/i18n-Service/i18nService";
+
+// Simple key
+const buttonLabel = i18nService.t("buttons.save"); // "Save Changes"
+
+// With parameters
+const welcomeMsg = i18nService.t("welcome", { name: "Alice" }); // "Welcome, Alice!"
+```
+
+### 4. Changing Language
+
+```typescript
+async function switchLanguage(lang: string) {
+  await i18nService.setLocale(lang);
+  // You might need to trigger a re-render in your framework
+}
+```
+
+## Framework Integration
+
+### Vue Plugin (Example)
+
+```typescript
+// plugins/i18n.ts
+import { i18nService } from "@/i18n-Service/i18nService";
+
+export default {
+  install: (app) => {
+    app.config.globalProperties.$t = (key, params) =>
+      i18nService.t(key, params);
+  },
+};
+```
+
+### React Hook (Example)
+
+```tsx
+// hooks/useI18n.ts
+import { useState, useEffect } from "react";
+import { i18nService } from "@/i18n-Service/i18nService";
+
+export function useI18n() {
+  const [locale, setLocale] = useState(i18nService.getLocale());
+
+  const t = (key, params) => i18nService.t(key, params);
+
+  // Logic to listen for locale changes would go here
+
+  return { t, locale };
+}
+```

package/src/services/i18n-Service/i18nService.ts

@@ -0,0 +1,127 @@
+export type Locale = string;
+export type Translations = Record<string, any>;
+
+export class I18nService {
+  private static instance: I18nService;
+  private currentLocale: Locale = "en";
+  private translations: Record<Locale, Translations> = {};
+  private isInitialized = false;
+  private fallbackLocale: Locale = "en";
+
+  private constructor() {}
+
+  public static getInstance(): I18nService {
+    if (!I18nService.instance) {
+      I18nService.instance = new I18nService();
+    }
+    return I18nService.instance;
+  }
+
+  /**
+   * Initialize the service.
+   * @param defaultLocale The default language to start with.
+   */
+  public async init(defaultLocale: Locale = "en"): Promise<void> {
+    if (this.isInitialized) return;
+
+    this.currentLocale = defaultLocale;
+    await this.loadLocale(defaultLocale);
+
+    if (defaultLocale !== this.fallbackLocale) {
+      // Optimistically load fallback just in case
+      this.loadLocale(this.fallbackLocale).catch(console.error);
+    }
+
+    this.isInitialized = true;
+  }
+
+  /**
+   * Change the current language.
+   * Fetches the file if not already loaded.
+   */
+  public async setLocale(locale: Locale): Promise<void> {
+    if (this.currentLocale === locale) return;
+
+    if (!this.translations[locale]) {
+      await this.loadLocale(locale);
+    }
+    this.currentLocale = locale;
+
+    // Persist preference if needed (e.g. localStorage)
+    // localStorage.setItem('user-locale', locale);
+  }
+
+  public getLocale(): Locale {
+    return this.currentLocale;
+  }
+
+  /**
+   * Translate a key with optional dynamic parameters.
+   * Supports nested keys via dot notation: 'common.welcome'
+   * @param key The translation key
+   * @param params Object containing values to replace {name: 'John'}
+   */
+  public t(key: string, params?: Record<string, string | number>): string {
+    const translation = this.getValue(
+      key,
+      this.translations[this.currentLocale],
+    );
+
+    if (translation === undefined) {
+      // Try fallback
+      const fallback = this.getValue(
+        key,
+        this.translations[this.fallbackLocale],
+      );
+      if (fallback !== undefined) {
+        return this.interpolate(fallback, params);
+      }
+      console.warn(`[i18n] Missing translation for key: ${key}`);
+      return key;
+    }
+
+    return this.interpolate(translation, params);
+  }
+
+  /**
+   * Helper to retrieve nested values
+   */
+  private getValue(key: string, data: Translations): string | undefined {
+    if (!data) return undefined;
+    return key.split(".").reduce((obj, i) => obj?.[i], data);
+  }
+
+  /**
+   * Interpolate values into the string.
+   * "Hello {name}" + {name: "John"} => "Hello John"
+   */
+  private interpolate(
+    text: string,
+    params?: Record<string, string | number>,
+  ): string {
+    if (!params) return text;
+
+    return text.replace(/{(\w+)}/g, (match, paramName) => {
+      const value = params[paramName];
+      return value !== undefined ? String(value) : match;
+    });
+  }
+
+  /**
+   * Load a locale file.
+   * You might need to adjust the import path pattern for your bundler (Vite/Webpack).
+   */
+  private async loadLocale(locale: Locale): Promise<void> {
+    try {
+      // Vite glob import or dynamic import
+      // Note: Dynamic imports with variables often require a specific structure for bundlers to analyze
+      const messages = await import(`./locales/${locale}.json`);
+      this.translations[locale] = messages.default || messages;
+    } catch (error) {
+      console.error(`[i18n] Failed to load locale: ${locale}`, error);
+      throw error;
+    }
+  }
+}
+
+export const i18nService = I18nService.getInstance();

package/src/services/i18n-Service/locales/en.json

@@ -0,0 +1,17 @@
+{
+  "common": {
+    "welcome": "Welcome, {name}!",
+    "login": "Login",
+    "logout": "Logout",
+    "save": "Save",
+    "cancel": "Cancel"
+  },
+  "dashboard": {
+    "title": "Dashboard",
+    "stats": "Statistics"
+  },
+  "errors": {
+    "network": "Network error occurred.",
+    "required": "{field} is required."
+  }
+}