@digitaldefiance/i18n-lib 1.0.13 → 1.0.14

package/dist/context-manager.js

@@ -18,7 +18,7 @@ class ContextManager {
         }
     }
     notifyChange(property, oldValue, newValue) {
-        this.listeners.forEach(listener => {
+        this.listeners.forEach((listener) => {
             try {
                 listener(property, oldValue, newValue);
             }
@@ -35,7 +35,7 @@ class ContextManager {
                 target[property] = value;
                 manager.notifyChange(property, oldValue, value);
                 return true;
-            }
+            },
         });
     }
 }

package/dist/context.js

@@ -8,7 +8,7 @@ function createContext(defaultLanguage) {
     return {
         language: defaultLanguage,
         adminLanguage: defaultLanguage,
-        currentContext: 'user'
+        currentContext: 'user',
     };
 }
 function setLanguage(context, language) {

package/dist/enum-registry.js

@@ -21,7 +21,7 @@ class EnumTranslationRegistry {
         }
         let result = langTranslations[value];
         if (!result && typeof value === 'number') {
-            const stringKey = Object.keys(enumObj).find(key => enumObj[key] === value);
+            const stringKey = Object.keys(enumObj).find((key) => enumObj[key] === value);
             if (stringKey) {
                 result = langTranslations[stringKey];
             }

package/dist/i18n-engine.d.ts

@@ -1,13 +1,132 @@
-import { I18nConfig, I18nContext, LanguageContext, EnumLanguageTranslation } from './types';
-export declare class I18nEngine<TStringKey extends string, TLanguage extends string, TConstants = Record<string, string | number>, TContext extends string = LanguageContext> {
-    private config;
-    private enumRegistry;
-    constructor(config: I18nConfig<TStringKey, TLanguage, TConstants>);
-    translate(key: TStringKey, context: I18nContext<TLanguage, TContext>, vars?: Record<string, string | number>, language?: TLanguage, fallbackLanguage?: TLanguage): string;
+import { EnumTranslationRegistry } from './enum-registry';
+import { EnumLanguageTranslation, I18nConfig, I18nContext } from './types';
+export declare class I18nEngine<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TContext extends string = string> {
+    /**
+     * Registry for enum translations
+     */
+    protected enumRegistry: EnumTranslationRegistry<TLanguage>;
+    /**
+     * Configuration for the i18n engine
+     */
+    protected config: I18nConfig<TStringKey, TLanguage, TConstants>;
+    /**
+     * Static instances for semi-singleton pattern
+     */
+    private static _instances;
+    /**
+     * Default instance key (first created instance)
+     */
+    private static _defaultKey;
+    /**
+     * Default instance key if none is provided
+     */
+    protected static readonly DefaultInstanceKey = "default";
+    /**
+     * Global context for translations (used if no context is provided) for this instance
+     */
+    private _context;
+    /**
+     * Default template processor instance
+     */
+    readonly t: (key: TStringKey, vars?: Record<string, string | number>, language?: TLanguage) => string;
+    /**
+     * Creates a new I18nEngine instance
+     * @param config The i18n configuration
+     * @param defaultContext The default context for translations
+     * @param key Optional instance key for the semi-singleton pattern
+     * @throws Error if an instance with the same key already exists
+     */
+    constructor(config: I18nConfig<TStringKey, TLanguage, TConstants>, defaultContext: TContext, key?: string);
+    /**
+     * Gets an instance of the I18nEngine by key. If no key is provided, the default instance is returned.
+     * @param key The key of the instance to retrieve
+     * @returns The I18nEngine instance
+     * @throws Error if the instance with the provided key does not exist
+     */
+    static getInstance<T extends I18nEngine<any, any, any, any>>(key?: string): T;
+    /**
+     * Gets a translation for the provided error key using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated error message
+     */
+    static getErrorMessage(errorKey: string, vars?: Record<string, string | number>, instanceKey?: string, language?: string, fallbackLanguage?: string): string;
+    /**
+     * Throws an error with a translated message using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @throws Error with translated message
+     */
+    static throwError(errorKey: string, vars?: Record<string, string | number>, instanceKey?: string): never;
+    /**
+     * Gets the global context for translations
+     * @returns The global context object
+     */
+    get context(): I18nContext<TLanguage, TContext>;
+    /**
+     * Sets the global context for translations (used if no context is provided) for this instance
+     * @param context The context to set
+     */
+    set context(context: Partial<I18nContext<TLanguage, TContext>>);
+    /**
+     * Translates a string key into the specified language, replacing any variables as needed.
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated string
+     */
+    translate(key: TStringKey, vars?: Record<string, string | number>, language?: TLanguage, fallbackLanguage?: TLanguage): string;
+    /**
+     * Translates an enumeration value into the specified language.
+     * @param enumObj The enumeration object
+     * @param value The enumeration value to translate
+     * @param language The language to translate to
+     * @returns The translated enumeration value
+     */
     translateEnum<TEnum extends string | number>(enumObj: Record<string, TEnum>, value: TEnum, language: TLanguage): string;
+    /**
+     * Registers an enumeration and its translations with the engine.
+     * @param enumObj The enumeration object
+     * @param translations The translations for the enumeration
+     * @param enumName The name of the enumeration (for error messages)
+     */
     registerEnum<TEnum extends string | number>(enumObj: Record<string, TEnum> | Record<string | number, string | number>, translations: EnumLanguageTranslation<TEnum, TLanguage>, enumName: string): void;
+    /**
+     * Safe translation that prevents infinite recursion for error messages
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @returns The translated string or the key if translation fails
+     */
+    private safeTranslate;
+    /**
+     * Retrieves the string for the given language and key, throwing an error if not found.
+     * @param language The language to get the string for
+     * @param key The string key to retrieve
+     * @returns The string value
+     * @throws Error if the language or string key is not found
+     */
     private getString;
+    /**
+     * Gets the language code for the specified language.
+     * @param language The language to get the code for
+     * @returns The language code
+     */
     getLanguageCode(language: TLanguage): string;
+    /**
+     * Gets the language for the specified language code.
+     * @param code The language code to look up
+     * @returns The language, or undefined if not found
+     */
     getLanguageFromCode(code: string): TLanguage | undefined;
+    /**
+     * Gets all language codes.
+     * @returns A record of all language codes
+     */
     getAllLanguageCodes(): Record<TLanguage, string>;
 }

package/dist/i18n-engine.js

@@ -2,15 +2,108 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.I18nEngine = void 0;
 const enum_registry_1 = require("./enum-registry");
+const template_1 = require("./template");
 const utils_1 = require("./utils");
 class I18nEngine {
-    constructor(config) {
+    /**
+     * Creates a new I18nEngine instance
+     * @param config The i18n configuration
+     * @param defaultContext The default context for translations
+     * @param key Optional instance key for the semi-singleton pattern
+     * @throws Error if an instance with the same key already exists
+     */
+    constructor(config, defaultContext, key) {
         this.config = config;
         this.enumRegistry = new enum_registry_1.EnumTranslationRegistry();
+        this._context = {
+            language: config.defaultLanguage,
+            adminLanguage: config.defaultLanguage,
+            currentContext: defaultContext,
+        };
+        const instanceKey = key || I18nEngine.DefaultInstanceKey;
+        if (I18nEngine._instances.has(instanceKey)) {
+            const existing = I18nEngine._instances.get(instanceKey);
+            throw new Error(existing.translate('Error_InstanceAlreadyExistsTemplate', {
+                key: instanceKey,
+            }));
+        }
+        I18nEngine._instances.set(instanceKey, this);
+        if (!I18nEngine._defaultKey) {
+            I18nEngine._defaultKey = instanceKey;
+        }
+        // Initialize the default template processor
+        this.t = (0, template_1.createTemplateProcessor)(this.config.enumObj || {}, (key, vars, language) => this.translate(key, vars, language), this.config.enumName || 'StringKey');
+    }
+    /**
+     * Gets an instance of the I18nEngine by key. If no key is provided, the default instance is returned.
+     * @param key The key of the instance to retrieve
+     * @returns The I18nEngine instance
+     * @throws Error if the instance with the provided key does not exist
+     */
+    static getInstance(key) {
+        const instanceKey = key || I18nEngine._defaultKey || I18nEngine.DefaultInstanceKey;
+        if (!instanceKey || !I18nEngine._instances.has(instanceKey)) {
+            throw new Error(I18nEngine.getErrorMessage('Error_InstanceNotFoundTemplate', {
+                key: instanceKey,
+            }));
+        }
+        return I18nEngine._instances.get(instanceKey);
+    }
+    /**
+     * Gets a translation for the provided error key using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated error message
+     */
+    static getErrorMessage(errorKey, vars, instanceKey, language, fallbackLanguage) {
+        try {
+            const instance = I18nEngine.getInstance(instanceKey);
+            return instance.translate(errorKey, vars, language, fallbackLanguage);
+        }
+        catch {
+            return `${errorKey}: ${JSON.stringify(vars || {})}`;
+        }
+    }
+    /**
+     * Throws an error with a translated message using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @throws Error with translated message
+     */
+    static throwError(errorKey, vars, instanceKey) {
+        throw new Error(I18nEngine.getErrorMessage(errorKey, vars, instanceKey));
+    }
+    /**
+     * Gets the global context for translations
+     * @returns The global context object
+     */
+    get context() {
+        return this._context;
     }
-    translate(key, context, vars, language, fallbackLanguage) {
+    /**
+     * Sets the global context for translations (used if no context is provided) for this instance
+     * @param context The context to set
+     */
+    set context(context) {
+        this._context = { ...this._context, ...context };
+    }
+    /**
+     * Translates a string key into the specified language, replacing any variables as needed.
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated string
+     */
+    translate(key, vars, language, fallbackLanguage) {
         const lang = language ??
-            (context.currentContext === 'admin' ? context.adminLanguage : context.language);
+            (this._context.currentContext === 'admin'
+                ? this._context.adminLanguage
+                : this._context.language);
         const fallback = fallbackLanguage ?? this.config.defaultLanguage;
         try {
             const stringValue = this.getString(lang, key);
@@ -33,26 +126,80 @@ class I18nEngine {
             return key;
         }
     }
+    /**
+     * Translates an enumeration value into the specified language.
+     * @param enumObj The enumeration object
+     * @param value The enumeration value to translate
+     * @param language The language to translate to
+     * @returns The translated enumeration value
+     */
     translateEnum(enumObj, value, language) {
         return this.enumRegistry.translate(enumObj, value, language);
     }
+    /**
+     * Registers an enumeration and its translations with the engine.
+     * @param enumObj The enumeration object
+     * @param translations The translations for the enumeration
+     * @param enumName The name of the enumeration (for error messages)
+     */
     registerEnum(enumObj, translations, enumName) {
         this.enumRegistry.register(enumObj, translations, enumName);
     }
+    /**
+     * Safe translation that prevents infinite recursion for error messages
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @returns The translated string or the key if translation fails
+     */
+    safeTranslate(key, vars, language) {
+        try {
+            const lang = language ?? this.config.defaultLanguage;
+            const strings = this.config.strings[lang];
+            if (!strings?.[key])
+                return key;
+            const stringValue = strings[key];
+            return (0, utils_1.isTemplate)(key)
+                ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
+                : stringValue;
+        }
+        catch {
+            return key;
+        }
+    }
+    /**
+     * Retrieves the string for the given language and key, throwing an error if not found.
+     * @param language The language to get the string for
+     * @param key The string key to retrieve
+     * @returns The string value
+     * @throws Error if the language or string key is not found
+     */
     getString(language, key) {
         const strings = this.config.strings[language];
         if (!strings) {
-            throw new Error(`Language not found: ${language}`);
+            throw new Error(this.safeTranslate('Error_LanguageNotFound', { language }) ||
+                `Language not found: ${language}`);
         }
         const value = strings[key];
         if (!value) {
-            throw new Error(`String not found: ${key}`);
+            throw new Error(this.safeTranslate('Error_StringNotFound', { key }) ||
+                `String not found: ${key}`);
         }
         return value;
     }
+    /**
+     * Gets the language code for the specified language.
+     * @param language The language to get the code for
+     * @returns The language code
+     */
     getLanguageCode(language) {
         return this.config.languageCodes[language] || language;
     }
+    /**
+     * Gets the language for the specified language code.
+     * @param code The language code to look up
+     * @returns The language, or undefined if not found
+     */
     getLanguageFromCode(code) {
         for (const [lang, langCode] of Object.entries(this.config.languageCodes)) {
             if (langCode === code) {
@@ -61,8 +208,24 @@ class I18nEngine {
         }
         return undefined;
     }
+    /**
+     * Gets all language codes.
+     * @returns A record of all language codes
+     */
     getAllLanguageCodes() {
         return this.config.languageCodes;
     }
 }
 exports.I18nEngine = I18nEngine;
+/**
+ * Static instances for semi-singleton pattern
+ */
+I18nEngine._instances = new Map();
+/**
+ * Default instance key (first created instance)
+ */
+I18nEngine._defaultKey = null;
+/**
+ * Default instance key if none is provided
+ */
+I18nEngine.DefaultInstanceKey = 'default';

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export * from './types';
-export * from './i18n-engine';
-export * from './enum-registry';
 export * from './context';
-export * from './utils';
-export * from './template';
 export * from './context-manager';
 export * from './currency';
+export * from './enum-registry';
+export * from './i18n-engine';
+export * from './template';
+export * from './types';
+export * from './utils';
 export { I18nEngine as I18n } from './i18n-engine';

package/dist/index.js

@@ -15,14 +15,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.I18n = void 0;
-__exportStar(require("./types"), exports);
-__exportStar(require("./i18n-engine"), exports);
-__exportStar(require("./enum-registry"), exports);
 __exportStar(require("./context"), exports);
-__exportStar(require("./utils"), exports);
-__exportStar(require("./template"), exports);
 __exportStar(require("./context-manager"), exports);
 __exportStar(require("./currency"), exports);
+__exportStar(require("./enum-registry"), exports);
+__exportStar(require("./i18n-engine"), exports);
+__exportStar(require("./template"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);
 // Re-export for convenience
 var i18n_engine_1 = require("./i18n-engine");
 Object.defineProperty(exports, "I18n", { enumerable: true, get: function () { return i18n_engine_1.I18nEngine; } });

package/dist/template.js

@@ -17,7 +17,9 @@ function createTemplateProcessor(enumObj, translateFn, enumName) {
             if (!enumValue) {
                 return match; // Return original if enum key not found
             }
-            const needsVars = enumValue.toLowerCase().endsWith('template');
+            const needsVars = enumValue
+                .toLowerCase()
+                .endsWith('template');
             const vars = needsVars ? otherVars[varIndex++] ?? {} : {};
             return translateFn(enumValue, vars, language);
         });

package/dist/types.d.ts

@@ -4,11 +4,13 @@ export type StringsCollection<TStringKey extends string> = Partial<Record<TStrin
 export type MasterStringsCollection<TStringKey extends string, TLanguage extends string> = Partial<Record<TLanguage, StringsCollection<TStringKey>>>;
 export type LanguageCodeCollection<TLanguage extends string> = Partial<Record<TLanguage, string>>;
 export type EnumTranslationMap<TEnum extends string | number, TLanguage extends string> = Partial<Record<TLanguage, Partial<Record<TEnum, string>>>>;
-export interface I18nConfig<TStringKey extends string, TLanguage extends string, TConstants = Record<string, string | number>> {
+export interface I18nConfig<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>> {
     strings: MasterStringsCollection<TStringKey, TLanguage>;
     defaultLanguage: TLanguage;
     languageCodes: LanguageCodeCollection<TLanguage>;
     constants?: TConstants;
+    enumName?: string;
+    enumObj?: Record<string, TStringKey>;
 }
 export interface I18nContext<TLanguage extends string, TContext extends string = LanguageContext> {
     language: TLanguage;

package/package.json

@@ -1,19 +1,31 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "yarn tsc",
     "test": "yarn jest",
+    "lint": "eslint src/**/*.ts tests/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts tests/**/*.ts --fix",
+    "prettier:check": "prettier --check 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
+    "prettier:fix": "prettier --write 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
+    "format": "yarn prettier:fix && yarn lint:fix",
     "prepublishOnly": "yarn build",
     "publish:public": "npm publish --access public"
   },
   "devDependencies": {
     "@types/jest": "^29.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.31.1",
+    "@typescript-eslint/parser": "^8.31.1",
+    "eslint": "^9.8.0",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-prettier": "^5.3.1",
     "jest": "^29.0.0",
     "jest-util": "^30.0.5",
+    "prettier": "^2.6.2",
+    "prettier-plugin-organize-imports": "^4.1.0",
     "ts-jest": "^29.0.0",
     "typescript": "^5.9.2"
   },