@je-es/client 0.1.7 → 0.1.9

package/README.md

@@ -8,11 +8,11 @@
 </div>
 
 <div align="center">
-    <img src="https://img.shields.io/badge/v-0.1.7-black"/>
+    <img src="https://img.shields.io/badge/v-0.1.9-black"/>
     <img src="https://img.shields.io/badge/🔥-@je--es-black"/>
     <br>
     <img src="https://github.com/je-es/client/actions/workflows/ci.yml/badge.svg" alt="CI" />
-    <img src="https://img.shields.io/badge/coverage-90%25-brightgreen" alt="Test Coverage" />
+    <!-- <img src="https://img.shields.io/badge/coverage-70%25-brightgreen" alt="Test Coverage" /> -->
     <img src="https://img.shields.io/github/issues/je-es/client?style=flat" alt="Github Repo Issues" />
     <img src="https://img.shields.io/github/stars/je-es/client?style=social" alt="GitHub Repo stars" />
 </div>
@@ -143,6 +143,8 @@
         }
         ```
 
+        > **_Components that manage their own DOM directly (like Notifications and ItemsLoader) shouldn't use @state decorators for properties that trigger re-renders. The @state decorator is designed for components that rely on virtual DOM patching. When you manage DOM directly with appendChild/remove, re-renders destroy your manual DOM changes._**
+
         <div align="center"> <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/> <br> </div>
 
     - ### SCSS Styling System
@@ -413,6 +415,153 @@
 
         <div align="center"> <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/> <br> </div>
 
+    - ### Internationalization (i18n)
+
+        **Setup in App Initialization:**
+
+        ```typescript
+        import { setupI18n, t } from '@je-es/client';
+
+        // In your app initialization (browser.ts or similar)
+        async function initializeApp() {
+            // 1. Setup i18n - loads the currently selected language
+            //    (from localStorage if user visited before, otherwise default)
+            await setupI18n({
+                defaultLanguage: 'en',
+                supportedLanguages: ['en', 'ar'],
+                staticPath: 'static/i18n'
+            });
+
+            // 2. Now safe to use t() and render components
+            const app = new MyApp();
+            await app.init();
+        }
+
+        // Call when DOM is ready
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', initializeApp);
+        } else {
+            initializeApp();
+        }
+        ```
+
+        **Use `t()` Anywhere:**
+
+        ```typescript
+        import { t, setLanguage, loadLanguageFile, getCurrentLanguage } from '@je-es/client';
+
+        // After setupI18n() resolves, you can use t() directly everywhere!
+        console.log(t('hello')); // Works in current language!
+        console.log(t('welcome', { app_name: 'MyApp' }));
+
+        // Switch language with lazy-loading (loads file only when needed)
+        async function selectLanguage(lang: string) {
+            await loadLanguageFile(lang);  // Load language on-demand
+            setLanguage(lang);
+            console.log(getCurrentLanguage()); // New language
+        }
+        ```
+
+        **Lazy-Loading Languages for Performance:**
+
+        `setupI18n()` loads the **currently selected language** on page load:
+        - **First visit**: Loads default language (e.g., en.json)
+        - **After switching**: Loads new language on-demand
+        - **Returning user**: Loads their previously selected language from localStorage
+
+        ```typescript
+        // Returning user who previously selected Arabic
+        // Page loads with ar.json (their choice) - fast! ⚡
+        await setupI18n({
+            defaultLanguage: 'en',
+            supportedLanguages: ['en', 'ar', 'fr'],
+            staticPath: 'static/i18n'
+        });
+        
+        // User clicks to switch language
+        await loadLanguageFile('fr');  // Load only when needed
+        setLanguage('fr');
+        ```
+
+        **In Components:**
+
+        ```typescript
+        import { Component, html } from '@je-es/client';
+        import { t, setLanguage, loadLanguageFile, createTranslator } from '@je-es/client';
+
+        class MultiLanguageComponent extends Component {
+            render() {
+                return html`
+                    <div>
+                        <h1>${t('welcome', { app_name: 'JE-ES' })}</h1>
+                        <button onclick=${() => this.switchLang('en')}>
+                            English
+                        </button>
+                        <button onclick=${() => this.switchLang('ar')}>
+                            العربية
+                        </button>
+                    </div>
+                `;
+            }
+
+            async switchLang(lang: string) {
+                await loadLanguageFile(lang);
+                setLanguage(lang);
+                this.refresh();
+            }
+
+            connectedCallback() {
+                super.connectedCallback();
+                // Subscribe to language changes
+                this.unsubscribe = createTranslator(() => this.refresh());
+            }
+
+            disconnectedCallback() {
+                super.disconnectedCallback();
+                if (this.unsubscribe) {
+                    this.unsubscribe();
+                }
+            }
+        }
+        ```
+
+        **Advanced Usage:**
+
+        ```typescript
+        import { t, tLang, loadLanguage, getSupportedLanguages, hasKey } from '@je-es/client';
+
+        // Translate with specific language temporarily
+        console.log(t('hello')); // Current language
+        console.log(tLang('hello', 'en')); // Temporarily use English
+
+        // Load specific language dynamically
+        loadLanguage('fr', {
+            hello: 'Bonjour',
+            welcome: 'Bienvenue dans {app_name}'
+        });
+
+        // Check supported languages
+        console.log(getSupportedLanguages()); // ['en', 'ar', 'fr']
+
+        // Check if key exists
+        if (hasKey('custom_key')) {
+            console.log(t('custom_key'));
+        }
+        ```
+
+        > **_Features:_**
+        > - **Lazy-loaded languages**: Default language loads on init, others load on-demand
+        > - **Fast page load**: Only default language file is downloaded initially
+        > - **localStorage support**: Automatically saves language preference
+        > - **Parameter replacement**: Replace placeholders with dynamic values
+        > - **Nested translations**: Use translation keys as parameter values
+        > - **Reactive updates**: Listen to language changes with `createTranslator()`
+        > - **Fallback language**: Falls back to configured default language if translation is missing
+        > - **Multiple languages**: Support for unlimited languages
+        > - **URL loading**: Load translations from remote JSON files or manually with `loadLanguageFile()`
+
+        <div align="center"> <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/> <br> </div>
+
     - ### API Integration
 
         ```typescript
@@ -514,6 +663,8 @@
         }
         ```
 
+        > **_Note:_** i18n is now configured directly in your app initialization via `setupI18n()` instead of in the client config. See the [Internationalization section](#internationalization-i18n) for details.
+
         <div align="center"> <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/> <br> </div>
 
     - ### Build Commands