@digitaldefiance/i18n-lib 1.0.13 → 1.0.15

package/README.md

@@ -1,14 +1,16 @@
 # @digitaldefiance/i18n-lib
 
-A generic TypeScript i18n library with enum translation support and template variable replacement.
+A comprehensive TypeScript internationalization library with enum translation support, template processing, and context management.
 
 ## Features
 
-- **Generic Design**: Works with any string and language enums
-- **Template Variables**: Replace `{variable}` placeholders in strings
-- **Enum Translation**: Translate enum values with type safety
-- **Context Support**: Admin vs user translation contexts
-- **Fallback Languages**: Graceful degradation when translations missing
+- **Type-Safe Translations**: Full TypeScript support with generic types for strings and languages
+- **Enum Translation Registry**: Translate enum values with complete type safety
+- **Template Processing**: Advanced template system with `{{EnumName.EnumKey}}` patterns and variable replacement
+- **Context Management**: Admin vs user translation contexts with automatic language switching
+- **Singleton Pattern**: Efficient instance management with named instances
+- **Currency Formatting**: Built-in currency formatting utilities with locale support
+- **Fallback System**: Graceful degradation when translations are missing
 - **Zero Dependencies**: Lightweight with no external dependencies
 
 ## Installation
@@ -30,11 +32,12 @@ enum MyStrings {
 
 enum MyLanguages {
   English = 'English',
-  Spanish = 'Español'
+  Spanish = 'Spanish'
 }
 
 // Configure the engine
 const config: I18nConfig<MyStrings, MyLanguages> = {
+  stringNames: Object.values(MyStrings),
   strings: {
     [MyLanguages.English]: {
       [MyStrings.Welcome]: 'Welcome!',
@@ -46,40 +49,52 @@ const config: I18nConfig<MyStrings, MyLanguages> = {
     }
   },
   defaultLanguage: MyLanguages.English,
+  defaultContext: 'user',
   languageCodes: {
     [MyLanguages.English]: 'en',
     [MyLanguages.Spanish]: 'es'
-  }
+  },
+  languages: Object.values(MyLanguages)
 };
 
-// Create engine and context
+// Create engine
 const i18n = new I18nEngine(config);
-const context = createContext(MyLanguages.English);
 
 // Translate strings
-const welcome = i18n.translate(MyStrings.Welcome, context);
+const welcome = i18n.translate(MyStrings.Welcome);
 // "Welcome!"
 
-const greeting = i18n.translate(MyStrings.UserGreetingTemplate, context, { name: 'John' });
+const greeting = i18n.translate(MyStrings.UserGreetingTemplate, { name: 'John' });
 // "Hello, John!"
+
+// Change language
+i18n.context = { language: MyLanguages.Spanish };
+const spanishGreeting = i18n.translate(MyStrings.UserGreetingTemplate, { name: 'Juan' });
+// "¡Hola, Juan!"
 ```
 
-## Enum Translation
+## Advanced Features
+
+### Enum Translation Registry
+
 ```typescript
 enum Status {
   Active = 'active',
-  Inactive = 'inactive'
+  Inactive = 'inactive',
+  Pending = 'pending'
 }
 
-// Register enum translations
+// Register enum translations (requires complete translations)
 i18n.registerEnum(Status, {
   [MyLanguages.English]: {
     [Status.Active]: 'Active',
-    [Status.Inactive]: 'Inactive'
+    [Status.Inactive]: 'Inactive',
+    [Status.Pending]: 'Pending'
   },
   [MyLanguages.Spanish]: {
     [Status.Active]: 'Activo',
-    [Status.Inactive]: 'Inactivo'
+    [Status.Inactive]: 'Inactivo',
+    [Status.Pending]: 'Pendiente'
   }
 }, 'Status');
 
@@ -88,24 +103,203 @@ const statusText = i18n.translateEnum(Status, Status.Active, MyLanguages.Spanish
 // "Activo"
 ```
 
-## API Reference
-### i18nEngine
- - translate(key, context, vars?, language?, fallback?) - Translate string with optional variables
+### Template Processing
+
+```typescript
+enum AppStrings {
+  WelcomeMessage = 'welcomeMessage',
+  UserGreetingTemplate = 'userGreetingTemplate'
+}
 
- - translateEnum(enumObj, value, language) - Translate enum value
+const config: I18nConfig<AppStrings, MyLanguages> = {
+  // ... other config
+  enumName: 'AppStrings',
+  enumObj: AppStrings,
+  strings: {
+    [MyLanguages.English]: {
+      [AppStrings.WelcomeMessage]: 'Welcome to our app!',
+      [AppStrings.UserGreetingTemplate]: 'Hello, {name}!'
+    }
+  }
+};
 
- - registerEnum(enumObj, translations, name) - Register enum translations
+const i18n = new I18nEngine(config);
 
- - getLanguageCode(language) - Get language code for language
+// Use template processor
+const message = i18n.t('{{AppStrings.WelcomeMessage}} {{AppStrings.UserGreetingTemplate}}', 
+  MyLanguages.English, 
+  { name: 'John' }
+);
+// "Welcome to our app! Hello, John!"
+```
 
 ### Context Management
- - createContext(defaultLanguage) - Create new context
 
- - setLanguage(context, language) - Set user language
+```typescript
+import { createContext, setLanguage, setAdminLanguage, setContext } from '@digitaldefiance/i18n-lib';
+
+// Create and manage context
+const context = createContext(MyLanguages.English, 'user');
+
+// Set different languages for user and admin contexts
+setLanguage(context, MyLanguages.Spanish);
+setAdminLanguage(context, MyLanguages.English);
+
+// Switch between contexts
+setContext(context, 'admin'); // Uses admin language
+setContext(context, 'user');  // Uses user language
+
+// Apply context to engine
+i18n.context = context;
+```
+
+### Context Change Monitoring
+
+```typescript
+import { ContextManager } from '@digitaldefiance/i18n-lib';
+
+interface AppContext {
+  language: string;
+  theme: string;
+}
+
+const manager = new ContextManager<AppContext>();
+
+// Add listeners for context changes
+manager.addListener((property, oldValue, newValue) => {
+  console.log(`${property} changed from ${oldValue} to ${newValue}`);
+});
+
+// Create reactive context
+const context = { language: 'en', theme: 'dark' };
+const reactiveContext = manager.createProxy(context);
+
+// Changes are automatically detected
+reactiveContext.language = 'es'; // Triggers listener
+```
+
+### Currency Formatting
+
+```typescript
+import { getCurrencyFormat } from '@digitaldefiance/i18n-lib';
+
+// Get currency formatting information
+const usdFormat = getCurrencyFormat('en-US', 'USD');
+// { symbol: '$', position: 'prefix', groupSeparator: ',', decimalSeparator: '.' }
+
+const eurFormat = getCurrencyFormat('de-DE', 'EUR');
+// { symbol: '€', position: 'postfix', groupSeparator: '.', decimalSeparator: ',' }
+```
+
+### Instance Management
+
+```typescript
+// Create named instances
+const mainI18n = new I18nEngine(config, 'main');
+const adminI18n = new I18nEngine(adminConfig, 'admin');
+
+// Get instances by key
+const instance = I18nEngine.getInstance('main');
+
+// Clean up instances (useful for testing)
+I18nEngine.clearInstances();
+I18nEngine.removeInstance('main');
+```
+
+## API Reference
+
+### I18nEngine
+
+#### Constructor
+- `new I18nEngine<TStringKey, TLanguage>(config, key?)` - Create new engine instance
+
+#### Translation Methods
+- `translate(key, vars?, language?, fallbackLanguage?)` - Translate string with optional variables
+- `translateEnum(enumObj, value, language)` - Translate enum value
+- `t(templateString, language?, ...vars)` - Process template with enum patterns
+
+#### Registration
+- `registerEnum(enumObj, translations, enumName)` - Register enum translations
+
+#### Language Management
+- `getLanguageCode(language)` - Get language code for language
+- `getLanguageFromCode(code)` - Get language from code
+- `getAllLanguageCodes()` - Get all language codes
+- `getAvailableLanguages()` - Get available languages
+- `isLanguageAvailable(language)` - Check if language is available
+
+#### Context Management
+- `get context()` - Get current context
+- `set context(context)` - Set context properties
+
+#### Static Methods
+- `getInstance(key?)` - Get instance by key
+- `clearInstances()` - Clear all instances
+- `removeInstance(key?)` - Remove specific instance
+
+### Context Utilities
+- `createContext(defaultLanguage, defaultContext)` - Create new context
+- `setLanguage(context, language)` - Set user language
+- `setAdminLanguage(context, language)` - Set admin language
+- `setContext(context, contextType)` - Set context type
+
+### ContextManager
+- `addListener(listener)` - Add change listener
+- `removeListener(listener)` - Remove change listener
+- `createProxy(context)` - Create reactive context proxy
+
+### Currency Utilities
+- `getCurrencyFormat(locale, currencyCode)` - Get currency formatting info
+
+### Type Utilities
+- `createTranslations(translations)` - Helper for creating typed translations
+
+## Type Definitions
+
+### Core Types
+```typescript
+type EnumTranslation<T extends string | number> = {
+  [K in T]: string;
+};
+
+type EnumLanguageTranslation<T extends string | number, TLanguage extends string> = Partial<{
+  [L in TLanguage]: EnumTranslation<T>;
+}>;
+
+interface I18nConfig<TStringKey, TLanguage, TConstants?, TContext?> {
+  stringNames: TStringKey[];
+  strings: MasterStringsCollection<TStringKey, TLanguage>;
+  defaultLanguage: TLanguage;
+  defaultContext: TContext;
+  languageCodes: LanguageCodeCollection<TLanguage>;
+  languages: TLanguage[];
+  constants?: TConstants;
+  enumName?: string;
+  enumObj?: Record<string, TStringKey>;
+}
+```
+
+## Testing
+
+The library includes comprehensive test coverage:
+
+```bash
+# Run tests
+yarn test
+
+# Run specific test suites
+yarn test context-manager.spec.ts
+yarn test enum-registry.spec.ts
+yarn test i18n-engine.spec.ts
+```
 
- - setAdminLanguage(context, language) - Set admin language
+## Best Practices
 
- - setContext(context, 'admin' | 'user') - Set context type
+1. **Complete Translations**: EnumTranslation requires all enum values to be translated
+2. **Type Safety**: Use TypeScript enums for string keys and languages
+3. **Context Separation**: Use different contexts for admin and user interfaces
+4. **Instance Management**: Use named instances for different parts of your application
+5. **Error Handling**: Handle missing translations gracefully with fallback languages
 
 ## License
 
@@ -113,4 +307,4 @@ MIT
 
 ## Repository
 
-[https://github.com/Digital-Defiance/i18n-lib](https://github.com/Digital-Defiance/i18n-lib)
+Part of the DigitalBurnbag project - a secure file sharing and automated protocol system.

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.d.ts

@@ -1,5 +1,5 @@
 import { I18nContext, LanguageContext } from './types';
-export declare function createContext<TLanguage extends string>(defaultLanguage: TLanguage): I18nContext<TLanguage>;
-export declare function setLanguage<TLanguage extends string>(context: I18nContext<TLanguage>, language: TLanguage): void;
-export declare function setAdminLanguage<TLanguage extends string>(context: I18nContext<TLanguage>, language: TLanguage): void;
-export declare function setContext<TLanguage extends string>(context: I18nContext<TLanguage>, languageContext: LanguageContext): void;
+export declare function createContext<TLanguage extends string, TContext extends string = LanguageContext>(defaultLanguage: TLanguage, defaultContext: TContext): I18nContext<TLanguage, TContext>;
+export declare function setLanguage<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, language: TLanguage): void;
+export declare function setAdminLanguage<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, language: TLanguage): void;
+export declare function setContext<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, languageContext: TContext): void;

package/dist/context.js

@@ -4,11 +4,11 @@ exports.createContext = createContext;
 exports.setLanguage = setLanguage;
 exports.setAdminLanguage = setAdminLanguage;
 exports.setContext = setContext;
-function createContext(defaultLanguage) {
+function createContext(defaultLanguage, defaultContext) {
     return {
         language: defaultLanguage,
         adminLanguage: defaultLanguage,
-        currentContext: 'user'
+        currentContext: defaultContext,
     };
 }
 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,153 @@
-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
+     */
+    readonly config: I18nConfig<TStringKey, TLanguage, TConstants, TContext>;
+    /**
+     * 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 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, 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>;
+    /**
+     * Gets all available languages.
+     * @returns An array of all available languages
+     */
+    getAvailableLanguages(): TLanguage[];
+    /**
+     * Checks if a language is available.
+     * @param language The language to check
+     * @returns True if the language is available, false otherwise
+     */
+    isLanguageAvailable(language: string): language is TLanguage;
+    /**
+     * Clears all instances (for testing purposes)
+     * @internal
+     */
+    static clearInstances(): void;
+    /**
+     * Removes a specific instance by key
+     * @param key The key of the instance to remove
+     * @internal
+     */
+    static removeInstance(key?: string): void;
 }

package/dist/i18n-engine.js

@@ -2,15 +2,107 @@
 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 key Optional instance key for the semi-singleton pattern
+     * @throws Error if an instance with the same key already exists
+     */
+    constructor(config, key) {
         this.config = config;
         this.enumRegistry = new enum_registry_1.EnumTranslationRegistry();
+        this._context = {
+            language: config.defaultLanguage,
+            adminLanguage: config.defaultLanguage,
+            currentContext: config.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);
     }
-    translate(key, context, vars, language, fallbackLanguage) {
+    /**
+     * 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;
+    }
+    /**
+     * 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 +125,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 +207,60 @@ class I18nEngine {
         }
         return undefined;
     }
+    /**
+     * Gets all language codes.
+     * @returns A record of all language codes
+     */
     getAllLanguageCodes() {
         return this.config.languageCodes;
     }
+    /**
+     * Gets all available languages.
+     * @returns An array of all available languages
+     */
+    getAvailableLanguages() {
+        return Object.keys(this.config.strings);
+    }
+    /**
+     * Checks if a language is available.
+     * @param language The language to check
+     * @returns True if the language is available, false otherwise
+     */
+    isLanguageAvailable(language) {
+        return Object.keys(this.config.strings).includes(language);
+    }
+    /**
+     * Clears all instances (for testing purposes)
+     * @internal
+     */
+    static clearInstances() {
+        I18nEngine._instances.clear();
+        I18nEngine._defaultKey = null;
+    }
+    /**
+     * Removes a specific instance by key
+     * @param key The key of the instance to remove
+     * @internal
+     */
+    static removeInstance(key) {
+        const instanceKey = key || I18nEngine.DefaultInstanceKey;
+        I18nEngine._instances.delete(instanceKey);
+        if (I18nEngine._defaultKey === instanceKey) {
+            const nextKey = I18nEngine._instances.keys().next().value;
+            I18nEngine._defaultKey = I18nEngine._instances.size > 0 && nextKey ? nextKey : null;
+        }
+    }
 }
 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,16 @@ 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>, TContext extends string = LanguageContext> {
+    stringNames: TStringKey[];
     strings: MasterStringsCollection<TStringKey, TLanguage>;
     defaultLanguage: TLanguage;
+    defaultContext: TContext;
     languageCodes: LanguageCodeCollection<TLanguage>;
+    languages: TLanguage[];
     constants?: TConstants;
+    enumName?: string;
+    enumObj?: Record<string, TStringKey>;
 }
 export interface I18nContext<TLanguage extends string, TContext extends string = LanguageContext> {
     language: TLanguage;
@@ -24,9 +29,9 @@ export type EnumTranslation<T extends string | number> = {
 /**
  * Generic language translation type for any enumeration
  */
-export type EnumLanguageTranslation<T extends string | number, TLanguage extends string = string> = {
+export type EnumLanguageTranslation<T extends string | number, TLanguage extends string = string> = Partial<{
     [L in TLanguage]: EnumTranslation<T>;
-};
+}>;
 /**
  * Helper function to create typed translations for an enumeration
  */

package/package.json

@@ -1,19 +1,32 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "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-import": "^2.32.0",
+    "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"
   },