@xxanderwp/translate-module 1.0.4 → 1.0.6

package/README.md

@@ -17,6 +17,7 @@ A lightweight, type-safe TypeScript module for managing multi-language translati
 - Full TypeScript generic type safety — language keys and translation keys are statically inferred
 - Runtime language switching via a simple setter
 - String interpolation with indexed placeholders (`{0}`, `{1}`, ...)
+- Language change listeners with automatic unregister support
 - Zero runtime dependencies
 
 ## Installation
@@ -78,7 +79,7 @@ Throws if `data` is empty or `defaultLanguage` is not a key of `data`.
 
 Returns the translated string for `key` in the current language, with `{0}`, `{1}`, ... placeholders replaced by the provided `args`.
 
-Returns `null` if the key does not exist or no language is set.
+Returns the key itself as a string if the translation is missing.
 
 ---
 
@@ -102,7 +103,22 @@ Returns the full translations object passed to the constructor.
 
 ### `currentLanguageData`
 
-Returns the translation dictionary for the currently active language, or `null` if none is set.
+Returns the translation dictionary for the currently active language.
+
+---
+
+### `onChangeLanguage(cb)`
+
+Registers a callback to be invoked whenever the active language changes. Returns an unregister function — call it to remove the listener.
+
+```ts
+const unregister = lang.onChangeLanguage(() => {
+  console.log("Language changed to:", lang.currentLanguage);
+});
+
+// Later, to stop listening:
+unregister();
+```
 
 ## Development
 

package/dist/index.d.ts

@@ -20,6 +20,11 @@
  * lc.translate("greeting", "Mundo"); // "¡Hola, Mundo!"
  */
 export declare class LanguageCore<T extends Record<string, Record<string, string>>, LangKey extends keyof T = keyof T> {
+    private _onChangeLanguage;
+    /** Registers a callback to be invoked whenever the active language changes.
+     * Returns a function to unregister the callback.
+     */
+    onChangeLanguage(cb: (newLang: LangKey) => void): () => void;
     /**
      * The immutable translations dataset provided at construction time.
      * Contains all language entries keyed by their language identifier.
@@ -114,12 +119,12 @@ export declare class LanguageCore<T extends Record<string, Record<string, string
      * @param args - Zero or more values to interpolate into the translated string.
      *   Each value is coerced to a string and replaces the matching `{n}` token.
      *
-     * @returns The translated (and interpolated) string, or `null` if the resolved translation is an empty string.
+     * @returns The translated (and interpolated) string, or the key itself if the translation is missing.
      *
      * @example
      * lc.translate("greeting", "Alice");       // "Hello, Alice!"
      * lc.translate("score", "Alice", 42);      // "Alice scored 42 points."
      */
-    translate<K extends keyof T[LangKey]>(key: K, ...args: (string | number)[]): string | null;
+    translate<K extends keyof T[LangKey]>(key: K, ...args: (string | number)[]): string;
 }
 export default LanguageCore;

package/dist/index.js

@@ -23,6 +23,16 @@ exports.LanguageCore = void 0;
  * lc.translate("greeting", "Mundo"); // "¡Hola, Mundo!"
  */
 class LanguageCore {
+    /** Registers a callback to be invoked whenever the active language changes.
+     * Returns a function to unregister the callback.
+     */
+    onChangeLanguage(cb) {
+        const id = Math.random();
+        this._onChangeLanguage.push({ id, cb });
+        return () => {
+            this._onChangeLanguage = this._onChangeLanguage.filter(item => item.id !== id);
+        };
+    }
     /**
      * Creates a new `LanguageCore` instance.
      *
@@ -41,6 +51,7 @@ class LanguageCore {
      * @throws {Error} If the supplied `defaultLanguage` is not a key of `data`.
      */
     constructor(data, defaultLanguage) {
+        this._onChangeLanguage = [];
         this.validateLanguageData(data);
         this._languages_data = data;
         if (defaultLanguage) {
@@ -116,7 +127,11 @@ class LanguageCore {
         if (!this.langKeys.includes(lang)) {
             throw new Error(`Language ${String(lang)} is not supported.`);
         }
+        if (lang === this._currentLanguage) {
+            return;
+        }
         this._currentLanguage = lang;
+        this._onChangeLanguage.forEach(item => item.cb(lang));
     }
     /**
      * Returns all language keys available in the translations dataset.
@@ -149,7 +164,7 @@ class LanguageCore {
      * @param args - Zero or more values to interpolate into the translated string.
      *   Each value is coerced to a string and replaces the matching `{n}` token.
      *
-     * @returns The translated (and interpolated) string, or `null` if the resolved translation is an empty string.
+     * @returns The translated (and interpolated) string, or the key itself if the translation is missing.
      *
      * @example
      * lc.translate("greeting", "Alice");       // "Hello, Alice!"
@@ -161,7 +176,7 @@ class LanguageCore {
         args.forEach((arg, index) => {
             res = res.replace(new RegExp(`\\{${index}\\}`, "g"), String(arg));
         });
-        return res || null;
+        return res || String(key);
     }
 }
 exports.LanguageCore = LanguageCore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xxanderwp/translate-module",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "",
   "main": "dist/index.js",
   "directories": {