@asafarim/shared-i18n 0.5.2 → 0.6.1

package/README.md

@@ -1,168 +1,170 @@
-# @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
-
+# @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/demo/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="./public/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>@asafarim/shared-i18n Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./src/main.tsx"></script>
+  </body>
+</html>

package/demo/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/demo/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/demo/node_modules/.bin/vite

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vite/bin/vite.js" "$@"
+else
+  exec node  "$basedir/../vite/bin/vite.js" "$@"
+fi

package/demo/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "shared-i18n-demo",
+  "version": "0.6.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@asafarim/shared-i18n": "workspace:*",
+    "@asafarim/design-tokens": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "typescript": "~5.8.3",
+    "vite": "^6.0.0"
+  }
+}

package/demo/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" fill="#4F46E5"/>
+  <text x="50" y="65" font-size="60" font-weight="bold" text-anchor="middle" fill="white">i18n</text>
+</svg>

package/demo/public/logo.svg

@@ -0,0 +1,24 @@
+<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#3A5AFE" />
+      <stop offset="100%" stop-color="#14B8A6" />
+    </linearGradient>
+    <linearGradient id="accent" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#FFFFFF" stop-opacity="0.9" />
+      <stop offset="100%" stop-color="#FFFFFF" stop-opacity="0.2" />
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#0B1220" flood-opacity="0.28" />
+    </filter>
+  </defs>
+  <rect width="180" height="180" rx="32" fill="url(#bg)" filter="url(#shadow)" />
+  <g transform="translate(45 45)">
+    <path d="M45 0C20.147 0 0 20.147 0 45C0 69.853 20.147 90 45 90C69.853 90 90 69.853 90 45C90 20.147 69.853 0 45 0ZM45 72C29.088 72 15.75 58.662 15.75 42.75C15.75 26.838 29.088 13.5 45 13.5C60.912 13.5 74.25 26.838 74.25 42.75C74.25 58.662 60.912 72 45 72Z" fill="white" opacity="0.2" />
+    <path d="M24 27H66C70.971 27 75 31.029 75 36V54C75 58.971 70.971 63 66 63H24C19.029 63 15 58.971 15 54V36C15 31.029 19.029 27 24 27Z" fill="url(#accent)" />
+    <path d="M36 54V45C36 40.029 40.029 36 45 36C49.971 36 54 40.029 54 45V54" stroke="#0B1220" stroke-width="4" stroke-linecap="round" />
+    <circle cx="45" cy="21" r="6" fill="white" />
+    <path d="M33 69H57" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.7" />
+    <path d="M27 15H63" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.4" />
+  </g>
+</svg>

package/demo/src/App.tsx

@@ -0,0 +1,112 @@
+import { useState } from 'react'
+import { useTranslation } from '@asafarim/shared-i18n'
+import LanguageBar from './components/LanguageBar'
+import Panel from './components/Panel'
+import KeyTable from './components/KeyTable'
+import StatusCard from './components/StatusCard'
+import OverviewSection from './components/OverviewSection'
+import GetStartedSection from './components/GetStartedSection'
+import LanguageSwitcherDemo from './components/LanguageSwitcherDemo'
+
+type TabType = 'overview' | 'getStarted' | 'demo'
+
+export default function App() {
+  const { t } = useTranslation('demo')
+  const [activeTab, setActiveTab] = useState<TabType>('overview')
+
+  return (
+    <div className="app-container">
+      <header className="app-header">
+        <div className="header-content">
+          <h1>{t('title')}</h1>
+          <p className="subtitle">{t('subtitle')}</p>
+        </div>
+        <LanguageBar />
+      </header>
+
+      <main className="app-main">
+        <div className="nav-tabs">
+          <button
+            className={`nav-tab ${activeTab === 'overview' ? 'active' : ''}`}
+            onClick={() => setActiveTab('overview')}
+          >
+            Overview
+          </button>
+          <button
+            className={`nav-tab ${activeTab === 'getStarted' ? 'active' : ''}`}
+            onClick={() => setActiveTab('getStarted')}
+          >
+            Get Started
+          </button>
+          <button
+            className={`nav-tab ${activeTab === 'demo' ? 'active' : ''}`}
+            onClick={() => setActiveTab('demo')}
+          >
+            Demo
+          </button>
+        </div>
+
+        {activeTab === 'overview' && <OverviewSection />}
+
+        {activeTab === 'getStarted' && <GetStartedSection />}
+
+        {activeTab === 'demo' && (
+          <>
+            <Panel title="LanguageSwitcher Component">
+              <LanguageSwitcherDemo />
+            </Panel>
+
+            <Panel title="Translations">
+              <div className="panel-grid">
+                <div>
+                  <h3>Common Namespace</h3>
+                  <KeyTable
+                    namespace="common"
+                    keys={['welcome', 'language', 'apps.appName.identity', 'apps.description.identity']}
+                  />
+                </div>
+                <div>
+                  <h3>Identity Portal Namespace</h3>
+                  <KeyTable
+                    namespace="identityPortal"
+                    keys={[
+                      'navbar.admin-area',
+                      'navbar.auth.signIn',
+                      'navbar.auth.signOut',
+                      'dashboard.title',
+                      'dashboard.user-management.title'
+                    ]}
+                  />
+                </div>
+              </div>
+            </Panel>
+
+            <Panel title="Interpolation & Trans Component">
+              <InterpolationDemo />
+            </Panel>
+
+            <StatusCard />
+          </>
+        )}
+      </main>
+    </div>
+  )
+}
+
+function InterpolationDemo() {
+  const { t, i18n } = useTranslation('identityPortal')
+
+  return (
+    <div className="interpolation-demo">
+      <div className="demo-item">
+        <h4>navbar.auth.welcome with interpolation</h4>
+        <p className="demo-output">
+          {t('navbar.auth.welcome', { userName: 'Ali' })}
+        </p>
+      </div>
+      <div className="demo-item">
+        <h4>Current language: {i18n.language}</h4>
+      </div>
+    </div>
+  )
+}

package/demo/src/components/GetStartedSection.tsx

@@ -0,0 +1,56 @@
+import { useState } from 'react'
+import { useTranslation } from '@asafarim/shared-i18n'
+
+export default function GetStartedSection() {
+  const { t } = useTranslation('demo')
+  const [expandedStep, setExpandedStep] = useState<number>(0)
+  const getStarted = t('getStarted', { returnObjects: true }) as any
+
+  return (
+    <div className="get-started-section">
+      <div className="gs-header">
+        <h2 className="gs-title">{getStarted.heading}</h2>
+        <p className="gs-intro">{getStarted.intro}</p>
+      </div>
+
+      <div className="steps-container">
+        {getStarted.steps.map((step: any, idx: number) => (
+          <div key={idx} className="step-item">
+            <button
+              className={`step-header ${expandedStep === idx ? 'expanded' : ''}`}
+              onClick={() => setExpandedStep(expandedStep === idx ? -1 : idx)}
+            >
+              <div className="step-number">{idx + 1}</div>
+              <div className="step-info">
+                <h3>{step.title}</h3>
+                <p>{step.description}</p>
+              </div>
+              <div className="step-toggle">
+                {expandedStep === idx ? '−' : '+'}
+              </div>
+            </button>
+            {expandedStep === idx && (
+              <div className="step-content">
+                <pre className="code-block">
+                  <code>{step.code}</code>
+                </pre>
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+
+      <div className="tips-section">
+        <div className="tips-icon">💡</div>
+        <div className="tips-content">
+          <h3>{getStarted.tips.title}</h3>
+          <ul className="tips-list">
+            {getStarted.tips.items.map((tip: string, idx: number) => (
+              <li key={idx}>{tip}</li>
+            ))}
+          </ul>
+        </div>
+      </div>
+    </div>
+  )
+}