@asafarim/shared-i18n 0.5.0

package/LICENSE

@@ -0,0 +1,23 @@
+# License
+
+This project is licensed under the **Creative Commons Attribution 4.0 International (CC BY 4.0)** license.
+
+You are free to:
+
+- **Share** — copy and redistribute the material in any medium or format  
+- **Adapt** — remix, transform, and build upon the material for any purpose, even commercially
+
+Under the following terms:
+
+- **Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made.  
+  You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+
+## 📌 Attribution Requirement
+
+If you use or modify this project, please include the following attribution:
+
+> Based on work by [Ali Safari](https://github.com/AliSafari-IT/asafarim-dot-be)
+
+## 🔗 Full License Text
+
+For full details, see the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).

package/README.md

@@ -0,0 +1,168 @@
+# @asafarim/shared-i18n
+
+Lightweight, simple translation module for any React + TypeScript app, built on top of i18next and react-i18next. It ships with sensible defaults (English and Dutch) but can support any language by adding JSON files to your locales folder.
+
+## Features
+
+- 🌍 Works in any React + TypeScript project (monorepo or standalone)
+- 🗂️ JSON-based translations per language and namespace
+- 🔄 Cookie-based language persistence (browser) with automatic detection
+- ⚙️ Optional backend sync for user language preferences
+- ⚡ Lazy loading support for app-specific translations
+- 🪝 React hooks for language management (useLanguage) and translations (useTranslation)
+
+## Installation
+
+```bash
+pnpm add @asafarim/shared-i18n
+# or
+npm i @asafarim/shared-i18n
+# or
+yarn add @asafarim/shared-i18n
+```
+
+## Usage
+
+### 1) Initialize i18n in your app
+
+In your app's main entry point (e.g., `main.tsx`):
+
+```tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { initI18n } from '@asafarim/shared-i18n';
+import App from './App';
+
+// Optional: import your app-specific translations
+import enApp from './locales/en/app.json';
+import nlApp from './locales/nl/app.json';
+
+initI18n({
+  defaultNS: 'common',
+  ns: ['common', 'app'],
+  resources: {
+    en: { app: enApp },
+    nl: { app: nlApp }
+  }
+});
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);
+```
+
+### 2) Use translations in components
+
+```tsx
+import { useTranslation } from '@asafarim/shared-i18n';
+
+function MyComponent() {
+  const { t } = useTranslation();
+  return (
+    <div>
+      <h1>{t('welcome')}</h1>
+      <p>{t('app:customKey')}</p>
+    </div>
+  );
+}
+```
+
+### 3) Add a language switcher
+
+If you use @asafarim/shared-ui-react you can leverage its LanguageSwitcher component. Otherwise, call useLanguage directly.
+
+```tsx
+import { useLanguage } from '@asafarim/shared-i18n';
+
+export function LanguageToggle() {
+  const { language, changeLanguage, isChanging } = useLanguage();
+  return (
+    <button onClick={() => changeLanguage(language === 'en' ? 'nl' : 'en')} disabled={isChanging}>
+      Switch language (current: {language})
+    </button>
+  );
+}
+```
+
+## Add more languages
+
+Yes — you can support any language by adding the required JSON files to your locales folder. For example:
+
+```
+your-app/
+  src/
+    locales/
+      en/
+        app.json
+      nl/
+        app.json
+      anotherLang/
+        new.json
+```
+
+Then include them when initializing:
+
+```tsx
+import anotherLang from './locales/anotherLang/new.json';
+
+initI18n({
+  ns: ['common', 'app', 'new'],
+  resources: {
+    anotherLang: { new: anotherLang }
+  },
+  supportedLngs: ['en', 'nl', 'anotherLang'],
+  defaultLanguage: 'en'
+});
+```
+
+Notes:
+- If you pass supportedLngs, it will override the default supported languages.
+- defaultLanguage overrides the default fallback (which is English).
+
+## API Reference
+
+### initI18n(config?: I18nConfig)
+
+Initialize i18next with the shared configuration.
+
+Parameters:
+- config.defaultNS — Default namespace (default: 'common')
+- config.ns — Namespaces to load (default: ['common'])
+- config.resources — App-specific translation resources
+- config.supportedLngs — Optional list of supported language codes to enable
+- config.defaultLanguage — Optional fallback language code
+
+### useLanguage()
+
+Hook for managing language preferences.
+
+Returns:
+- language — Current language code
+- changeLanguage(lang) — Function to change language
+- isChanging — Boolean indicating if language change is in progress
+
+### useTranslation()
+
+Re-exported from react-i18next. See official docs.
+
+## Cookie and backend integration
+
+- A preferredLanguage cookie is used to persist the selected language in the browser.
+- If your environment provides an Identity API, updateUserLanguagePreference can sync the preference server-side. If not, the library still works fully client-side.
+
+To point to a backend, optionally set:
+
+```env
+VITE_IDENTITY_API_URL=https://your-identity.example.com
+```
+
+## Built-in translations
+
+This package ships with default English and Dutch common translations. You can ignore them and supply your own resources if preferred.
+
+## License
+
+MIT © ASafariM
+

package/config/i18n.ts

@@ -0,0 +1,89 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+
+// Import common translations
+import enCommon from '../locales/en/common.json';
+import nlCommon from '../locales/nl/common.json';
+
+// Import web app translations
+import enWeb from '../locales/en/web.json';
+import nlWeb from '../locales/nl/web.json';
+
+// Import identity-portal translations
+import enIdentityPortal from '../locales/en/identity-portal.json';
+import nlIdentityPortal from '../locales/nl/identity-portal.json';
+
+export const SUPPORTED_LANGUAGES = ['en', 'nl'] as const;
+export type SupportedLanguage = typeof SUPPORTED_LANGUAGES[number];
+
+export const LANGUAGE_NAMES: Record<SupportedLanguage, string> = {
+  en: 'English',
+  nl: 'Nederlands'
+};
+
+export const DEFAULT_LANGUAGE: SupportedLanguage = 'en';
+export const LANGUAGE_COOKIE_NAME = 'preferredLanguage';
+
+export interface I18nConfig {
+  defaultNS?: string;
+  ns?: string[];
+  resources?: Record<string, Record<string, any>>;
+  supportedLngs?: string[];
+  defaultLanguage?: string;
+}
+
+export const initI18n = (config?: I18nConfig) => {
+  const {
+    defaultNS = 'common',
+    ns = ['common', 'web', 'identityPortal'],
+    resources = {},
+    supportedLngs,
+    defaultLanguage,
+  } = config || {};
+
+  // Merge common translations with app-specific resources
+  const mergedResources: Record<string, Record<string, any>> = { ...resources };
+
+  mergedResources.en = {
+    common: enCommon,
+    web: enWeb,
+    identityPortal: enIdentityPortal,
+    ...(resources.en || {}),
+  };
+  mergedResources.nl = {
+    common: nlCommon,
+    web: nlWeb,
+    identityPortal: nlIdentityPortal,
+    ...(resources.nl || {}),
+  };
+
+  const finalSupportedLngs = supportedLngs ?? Object.keys(mergedResources);
+  const fallbackLng = defaultLanguage ?? DEFAULT_LANGUAGE;
+
+  i18n
+    .use(initReactI18next)
+    .use(LanguageDetector)
+    .init({
+      resources: mergedResources,
+      fallbackLng,
+      defaultNS,
+      ns,
+      supportedLngs: finalSupportedLngs,
+      detection: {
+        order: ['cookie', 'navigator'],
+        caches: ['cookie'],
+        lookupCookie: LANGUAGE_COOKIE_NAME
+      },
+      interpolation: {
+        escapeValue: false // React already escapes
+      },
+      react: {
+        useSuspense: false
+      }
+    });
+
+  return i18n;
+};
+
+export default i18n;

package/hooks/useLanguage.ts

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { 
+  setLanguageCookie, 
+  updateUserLanguagePreference, 
+  fetchUserLanguagePreference,
+  isSupportedLanguage
+} from '../utils/languageUtils';
+import type { SupportedLanguage } from '../config/i18n';
+
+export interface UseLanguageReturn {
+  language: SupportedLanguage;
+  changeLanguage: (lang: SupportedLanguage) => Promise<void>;
+  isChanging: boolean;
+}
+
+/**
+ * Hook for managing language preferences
+ * Handles both frontend (cookie) and backend (API) synchronization
+ */
+export const useLanguage = (): UseLanguageReturn => {
+  const { i18n } = useTranslation();
+  const [isChanging, setIsChanging] = useState(false);
+
+  // Safely get current language with fallback
+  const currentLanguage = (i18n?.language && isSupportedLanguage(i18n.language) 
+    ? i18n.language 
+    : 'en') as SupportedLanguage;
+
+  // Sync with backend on mount (for authenticated users)
+  useEffect(() => {
+    const syncLanguageWithBackend = async () => {
+      if (!i18n?.changeLanguage) return;
+      
+      const backendLang = await fetchUserLanguagePreference();
+      if (backendLang && backendLang !== currentLanguage) {
+        await i18n.changeLanguage(backendLang);
+        setLanguageCookie(backendLang);
+      }
+    };
+
+    syncLanguageWithBackend();
+  }, []); // Only run once on mount
+
+  const changeLanguage = useCallback(async (lang: SupportedLanguage) => {
+    if (lang === currentLanguage) return;
+
+    setIsChanging(true);
+    try {
+      // Check if i18n is properly initialized
+      if (!i18n || typeof i18n.changeLanguage !== 'function') {
+        console.error('i18n is not properly initialized');
+        // Still update cookie even if i18n fails
+        setLanguageCookie(lang);
+        return;
+      }
+
+      // Update i18next
+      await i18n.changeLanguage(lang);
+      
+      // Update cookie immediately
+      setLanguageCookie(lang);
+      
+      // Update backend (fire and forget for better UX)
+      updateUserLanguagePreference(lang).catch(err => {
+        console.warn('Failed to sync language preference with backend:', err);
+      });
+    } catch (error) {
+      console.error('Failed to change language:', error);
+    } finally {
+      setIsChanging(false);
+    }
+  }, [currentLanguage]);
+
+  return {
+    language: currentLanguage,
+    changeLanguage,
+    isChanging
+  };
+};

package/index.ts

@@ -0,0 +1,21 @@
+// Main exports
+export { initI18n, SUPPORTED_LANGUAGES, LANGUAGE_NAMES, DEFAULT_LANGUAGE, LANGUAGE_COOKIE_NAME } from './config/i18n';
+export type { SupportedLanguage, I18nConfig } from './config/i18n';
+
+// Hooks
+export { useLanguage } from './hooks/useLanguage';
+export type { UseLanguageReturn } from './hooks/useLanguage';
+
+// Utils
+export {
+  getLanguageFromCookie,
+  setLanguageCookie,
+  isSupportedLanguage,
+  getBrowserLanguage,
+  getInitialLanguage,
+  updateUserLanguagePreference,
+  fetchUserLanguagePreference
+} from './utils/languageUtils';
+
+// Re-export react-i18next for convenience
+export { useTranslation, Trans, Translation } from 'react-i18next';

package/locales/en/common.json

@@ -0,0 +1,66 @@
+{
+  "welcome": "Welcome",
+  "language": "Language",
+  "settings": "Settings",
+  "profile": "Profile",
+  "logout": "Logout",
+  "login": "Login",
+  "register": "Register",
+  "email": "Email",
+  "password": "Password",
+  "confirmPassword": "Confirm Password",
+  "forgotPassword": "Forgot Password?",
+  "rememberMe": "Remember Me",
+  "submit": "Submit",
+  "cancel": "Cancel",
+  "save": "Save",
+  "delete": "Delete",
+  "edit": "Edit",
+  "close": "Close",
+  "search": "Search",
+  "loading": "Loading...",
+  "error": "Error",
+  "success": "Success",
+  "warning": "Warning",
+  "info": "Information",
+  "yes": "Yes",
+  "no": "No",
+  "back": "Back",
+  "next": "Next",
+  "previous": "Previous",
+  "home": "Home",
+  "about": "About",
+  "contact": "Contact",
+  "services": "Services",
+  "blog": "Blog",
+  "careers": "Careers",
+  "privacy": "Privacy Policy",
+  "terms": "Terms of Service",
+  "copyright": " ASafariM. All rights reserved.",
+  "languageChanged": "Language changed successfully",
+  "preferencesSaved": "Preferences saved successfully",
+  "apps": {
+    "appName": {
+      "web": "ASafariM web",
+      "blog": "Blog & documentation",
+      "ai": "AI Tools",
+      "core": "Core App",
+      "jobs": "Job Applications",
+      "identity": "Identity Portal",
+      "testora": "Testora",
+      "taskmanagement": "Task Management",
+      "smartops": "SmartOps"
+    },
+    "description": {
+      "web": "ASafariM web portal",
+      "blog": "Documentation and blog",
+      "ai": "AI-powered tools and services",
+      "core": "Core application features",
+      "jobs": "Job application tracking",
+      "identity": "User management and authentication",
+      "testora": "Test Automation System - Testora",
+      "taskmanagement": "Task Management",
+      "smartops": "SmartOps"
+    }
+  }
+}

package/locales/en/identity-portal.json

@@ -0,0 +1,69 @@
+{
+    "toast": {
+        "notAuthorized": "You do not have permission to access this page",
+        "notAdmin": "You do not have permission to access this page",
+        "loading": "Loading..."
+    },
+    "admin-area": {
+        "dashboard": {
+            "title": "Admin Dashboard",
+            "description": "Manage Identity Portal entities",
+            "actions": {
+                "open": "Open"
+            },
+            "user-management": {
+                "title": "User Management",
+                "description": "Manage platform users and their permissions.",
+                "icon": "👥",
+                "link": "/admin-area/users"
+            },
+            "role-management": {
+                "title": "Role Management",
+                "description": "Define and update system roles and privileges.",
+                "icon": "🛡️",
+                "link": "/admin-area/roles"
+            }
+        }
+    },
+    "navbar": {
+        "admin-area": "Admin Area",
+        "me": "My Profile",
+        "contact": "Contact",
+        "about": "About",
+        "auth": {
+            "notSignedIn": "Not signed in!",
+            "signIn": "Sign In",
+            "signOut": "Sign Out",
+            "welcome": "Welcome, {{userName}}!"
+        }
+    },
+    "dashboard": {
+        "title": "Dashboard",
+        "description": "Manage Identity Portal entities",
+        "actions": {
+            "title": "Actions",
+            "open": "Open",
+            "editProfile": "Edit profile",
+            "changePassword": "Change password",
+            "manageUsers": "Manage users"
+        },
+        "user-management": {
+            "title": "User Management",
+            "description": "Manage platform users and their permissions.",
+            "icon": "👥",
+            "link": "/admin-area/users",
+            "email": "Email",
+            "username": "Username"
+        },
+        "role-management": {
+            "title": "Role Management",
+            "description": "Define and update system roles and privileges.",
+            "icon": "🛡️",
+            "link": "/admin-area/roles"
+        },
+        "access": {
+            "title": "Access",
+            "roles": "Roles"
+        }
+    }
+}