@digitaldefiance/i18n-lib 1.0.14 → 1.0.16

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

@@ -1,5 +1,6 @@
+import { Timezone } from './timezone';
 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, defaultTimezone?: Timezone, defaultAdminTimezone?: Timezone): 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,14 @@ exports.createContext = createContext;
 exports.setLanguage = setLanguage;
 exports.setAdminLanguage = setAdminLanguage;
 exports.setContext = setContext;
-function createContext(defaultLanguage) {
+const timezone_1 = require("./timezone");
+function createContext(defaultLanguage, defaultContext, defaultTimezone = new timezone_1.Timezone('UTC'), defaultAdminTimezone = new timezone_1.Timezone('UTC')) {
     return {
         language: defaultLanguage,
         adminLanguage: defaultLanguage,
-        currentContext: 'user',
+        currentContext: defaultContext,
+        timezone: defaultTimezone,
+        adminTimezone: defaultAdminTimezone,
     };
 }
 function setLanguage(context, language) {

package/dist/i18n-engine.d.ts

@@ -8,7 +8,7 @@ export declare class I18nEngine<TStringKey extends string, TLanguage extends str
     /**
      * Configuration for the i18n engine
      */
-    protected config: I18nConfig<TStringKey, TLanguage, TConstants>;
+    readonly config: I18nConfig<TStringKey, TLanguage, TConstants, TContext>;
     /**
      * Static instances for semi-singleton pattern
      */
@@ -32,11 +32,10 @@ export declare class I18nEngine<TStringKey extends string, TLanguage extends str
     /**
      * 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);
+    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
@@ -129,4 +128,26 @@ export declare class I18nEngine<TStringKey extends string, TLanguage extends str
      * @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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.I18nEngine = void 0;
+const context_1 = require("./context");
 const enum_registry_1 = require("./enum-registry");
 const template_1 = require("./template");
 const utils_1 = require("./utils");
@@ -8,18 +9,13 @@ class I18nEngine {
     /**
      * 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) {
+    constructor(config, key) {
         this.config = config;
         this.enumRegistry = new enum_registry_1.EnumTranslationRegistry();
-        this._context = {
-            language: config.defaultLanguage,
-            adminLanguage: config.defaultLanguage,
-            currentContext: defaultContext,
-        };
+        this._context = (0, context_1.createContext)(config.defaultLanguage, config.defaultContext, config.timezone, config.adminTimezone);
         const instanceKey = key || I18nEngine.DefaultInstanceKey;
         if (I18nEngine._instances.has(instanceKey)) {
             const existing = I18nEngine._instances.get(instanceKey);
@@ -215,6 +211,42 @@ class I18nEngine {
     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;
 /**

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './currency';
 export * from './enum-registry';
 export * from './i18n-engine';
 export * from './template';
+export * from './timezone';
 export * from './types';
 export * from './utils';
 export { I18nEngine as I18n } from './i18n-engine';

package/dist/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./currency"), exports);
 __exportStar(require("./enum-registry"), exports);
 __exportStar(require("./i18n-engine"), exports);
 __exportStar(require("./template"), exports);
+__exportStar(require("./timezone"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./utils"), exports);
 // Re-export for convenience

package/dist/timezone.d.ts

@@ -0,0 +1,5 @@
+export declare class Timezone {
+    private readonly _timezone;
+    constructor(timezone: string);
+    get value(): string;
+}

package/dist/timezone.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Timezone = void 0;
+const utils_1 = require("./utils");
+class Timezone {
+    constructor(timezone) {
+        if (!(0, utils_1.isValidTimezone)(timezone)) {
+            throw new Error(`Invalid timezone: ${timezone}`);
+        }
+        this._timezone = timezone;
+    }
+    get value() {
+        return this._timezone;
+    }
+}
+exports.Timezone = Timezone;

package/dist/types.d.ts

@@ -1,21 +1,29 @@
+import { Timezone } from './timezone';
 export type LanguageContext = 'admin' | 'user';
 export type CustomLanguageContext<T extends string = LanguageContext> = T;
 export type StringsCollection<TStringKey extends string> = Partial<Record<TStringKey, string>>;
 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 extends Record<string, any> = Record<string, any>> {
+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>;
+    timezone: Timezone;
+    adminTimezone: Timezone;
 }
 export interface I18nContext<TLanguage extends string, TContext extends string = LanguageContext> {
     language: TLanguage;
     adminLanguage: TLanguage;
     currentContext: TContext;
+    timezone: Timezone;
+    adminTimezone: Timezone;
 }
 /**
  * Generic translation type for any enumeration
@@ -26,9 +34,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/dist/utils.d.ts

@@ -1,2 +1,3 @@
 export declare function replaceVariables(str: string, vars?: Record<string, string | number>, constants?: any): string;
 export declare function isTemplate(key: string): boolean;
+export declare function isValidTimezone(timezone: string): boolean;

package/dist/utils.js

@@ -1,7 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.replaceVariables = replaceVariables;
 exports.isTemplate = isTemplate;
+exports.isValidTimezone = isValidTimezone;
+const moment_timezone_1 = __importDefault(require("moment-timezone"));
 function replaceVariables(str, vars, constants) {
     const variables = str.match(/\{(.+?)\}/g);
     if (!variables)
@@ -25,3 +30,6 @@ function replaceVariables(str, vars, constants) {
 function isTemplate(key) {
     return key.toLowerCase().endsWith('template');
 }
+function isValidTimezone(timezone) {
+    return moment_timezone_1.default.tz.zone(timezone) !== null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +21,7 @@
     "@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",
@@ -42,5 +43,9 @@
   ],
   "author": "Digital Defiance",
   "license": "MIT",
-  "packageManager": "yarn@4.10.3"
+  "packageManager": "yarn@4.10.3",
+  "dependencies": {
+    "moment": "^2.30.1",
+    "moment-timezone": "^0.6.0"
+  }
 }