@digitaldefiance/i18n-lib 1.0.33 → 1.1.1

package/README.md

@@ -1,10 +1,24 @@
 # @digitaldefiance/i18n-lib
 
-A comprehensive TypeScript internationalization library with enum translation support, template processing, and context management.
+A comprehensive TypeScript internationalization library with plugin-based component registration, enum translation support, template processing, and context management.
+
+## 🚀 New Plugin-Based Architecture
+
+**Version 1.1.0** introduces a revolutionary plugin-based architecture with component registration and rigid compile-time type safety:
+
+- **Component Registration System**: Register translation components with their own string keys
+- **Language Plugin Support**: Add new languages dynamically with validation
+- **Compile-Time Type Safety**: TypeScript ensures all strings are complete for all languages
+- **Automatic Validation**: Comprehensive validation with detailed error reporting
+- **Fallback System**: Intelligent fallback to default languages with missing translation detection
+- **Multi-Instance Support**: Named instances for different application contexts
 
 ## Features
 
+### Core Features
+
 - **Type-Safe Translations**: Full TypeScript support with generic types for strings and languages
+- **Plugin Architecture**: Register components and languages dynamically with full type safety
 - **Configuration Validation**: Automatic validation ensures all languages have complete string collections
 - **Localized Error Messages**: Error messages can be translated using the engine's own translation system
 - **Enum Translation Registry**: Translate enum values with complete type safety
@@ -14,7 +28,15 @@ A comprehensive TypeScript internationalization library with enum translation su
 - **Currency Formatting**: Built-in currency formatting utilities with locale support
 - **Fallback System**: Graceful degradation when translations are missing
 - **Extensible Configuration**: Module augmentation support for layered library extension
-- **Zero Dependencies**: Lightweight with no external dependencies
+- **Backward Compatibility**: Legacy I18nEngine remains fully supported
+
+### New Plugin Features
+
+- **Component Registry**: Manage translation components with validation
+- **Language Registry**: Dynamic language registration with metadata
+- **Type-Safe Registration**: Compile-time guarantees for translation completeness
+- **Validation Reporting**: Detailed missing translation reports
+- **Plugin System**: Modular component architecture
 
 ## Installation
 
@@ -79,6 +101,326 @@ const spanishGreeting = i18n.translate(MyStrings.UserGreetingTemplate, { name: '
 // "¡Hola, Juan!"
 ```
 
+## 🆕 Plugin-Based Architecture (New in v1.1.0)
+
+The new plugin-based architecture provides a component registration system with rigid compile-time type safety.
+
+### Quick Start with Plugin Architecture
+
+```typescript
+import { 
+  createCoreI18nEngine, 
+  CoreStringKey, 
+  CoreLanguage,
+  ComponentDefinition,
+  ComponentRegistration
+} from '@digitaldefiance/i18n-lib';
+
+// Create engine with default languages and core strings
+const i18n = createCoreI18nEngine('myapp');
+
+// Use core translations
+const welcomeMessage = i18n.translate('core', CoreStringKey.System_Welcome);
+const errorMessage = i18n.translate('core', CoreStringKey.Error_ValidationFailed);
+
+// Define your own component with type safety
+enum MyComponentStringKey {
+  Welcome = 'welcome',
+  Goodbye = 'goodbye',
+  UserGreetingTemplate = 'userGreetingTemplate'
+}
+
+const MyComponent: ComponentDefinition<MyComponentStringKey> = {
+  id: 'my-component',
+  name: 'My Custom Component',
+  stringKeys: Object.values(MyComponentStringKey)
+};
+
+// Define translations for all supported languages
+const myComponentStrings = {
+  [CoreLanguage.EnglishUS]: {
+    [MyComponentStringKey.Welcome]: 'Welcome to my component!',
+    [MyComponentStringKey.Goodbye]: 'Goodbye from my component!',
+    [MyComponentStringKey.UserGreetingTemplate]: 'Hello, {name}!'
+  },
+  [CoreLanguage.French]: {
+    [MyComponentStringKey.Welcome]: 'Bienvenue dans mon composant !',
+    [MyComponentStringKey.Goodbye]: 'Au revoir de mon composant !',
+    [MyComponentStringKey.UserGreetingTemplate]: 'Bonjour, {name} !'
+  },
+  [CoreLanguage.Spanish]: {
+    [MyComponentStringKey.Welcome]: '¡Bienvenido a mi componente!',
+    [MyComponentStringKey.Goodbye]: '¡Adiós desde mi componente!',
+    [MyComponentStringKey.UserGreetingTemplate]: '¡Hola, {name}!'
+  }
+  // TypeScript ensures all CoreLanguages are handled
+};
+
+// Register component (with validation)
+const registration: ComponentRegistration<MyComponentStringKey, CoreLanguage> = {
+  component: MyComponent,
+  strings: myComponentStrings
+};
+
+const validationResult = i18n.registerComponent(registration);
+if (!validationResult.isValid) {
+  console.warn('Missing translations:', validationResult.missingKeys);
+}
+
+// Use your component's translations
+const welcome = i18n.translate('my-component', MyComponentStringKey.Welcome);
+const greeting = i18n.translate('my-component', MyComponentStringKey.UserGreetingTemplate, {
+  name: 'John'
+});
+
+// Change language - affects all components
+i18n.setLanguage(CoreLanguage.French);
+const frenchWelcome = i18n.translate('my-component', MyComponentStringKey.Welcome);
+// "Bienvenue dans mon composant !"
+```
+
+### Key Plugin Architecture Benefits
+
+1. **Compile-Time Type Safety**: TypeScript ensures all string keys exist for all languages
+2. **Component Isolation**: Each component manages its own strings independently  
+3. **Flexible Language Support**: Components can support different subsets of system languages
+4. **Comprehensive Validation**: Automatic detection of missing translations with detailed reporting
+5. **Fallback System**: Intelligent fallback to default language when translations are missing
+6. **Dynamic Language Addition**: Add new languages at runtime with automatic validation updates
+7. **Extensibility**: Easy to add new languages and components dynamically
+
+### Pre-built Components
+
+The library includes several pre-built components:
+
+#### Core I18n Component
+
+Provides essential system strings in 8 languages:
+
+- English (US/UK), French, Spanish, German, Chinese (Simplified), Japanese, Ukrainian
+
+```typescript
+import { createCoreI18nEngine, CoreStringKey } from '@digitaldefiance/i18n-lib';
+
+const i18n = createCoreI18nEngine();
+const saveText = i18n.translate('core', CoreStringKey.Common_Save);
+const errorMsg = i18n.translate('core', CoreStringKey.Error_ValidationFailed);
+```
+
+#### User System Component (Example)
+
+Demonstrates user management strings:
+
+```typescript
+import { 
+  registerUserSystemComponent, 
+  getUserTranslation, 
+  UserStringKey 
+} from '@digitaldefiance/i18n-lib';
+
+// Register user system with existing engine
+registerUserSystemComponent(i18n);
+
+// Use user system translations
+const loginText = getUserTranslation(UserStringKey.Auth_Login);
+const userNotFound = getUserTranslation(
+  UserStringKey.Error_UserNotFoundTemplate, 
+  { username: 'john_doe' }
+);
+```
+
+### Advanced Plugin Usage
+
+#### Compile-Time Completeness Enforcement (Strict Mode)
+
+By default the plugin engine performs runtime validation and provides fallbacks. If you want **compile-time** enforcement that every language mapping contains every string key, use the helper in `strict-types`:
+
+```typescript
+import { createCompleteComponentStrings } from '@digitaldefiance/i18n-lib';
+
+enum MyStrings {
+  Welcome = 'welcome',
+  Farewell = 'farewell'
+}
+
+type AppLang = 'en' | 'fr';
+
+// This will only compile if BOTH languages contain BOTH keys.
+const myStrictStrings = createCompleteComponentStrings<MyStrings, AppLang>({
+  en: {
+    [MyStrings.Welcome]: 'Welcome',
+    [MyStrings.Farewell]: 'Goodbye'
+  },
+  fr: {
+    [MyStrings.Welcome]: 'Bienvenue',
+    [MyStrings.Farewell]: 'Au revoir'
+  }
+});
+
+// If any key is missing, TypeScript reports an error before runtime.
+```
+
+The core library itself uses this helper for the core component (`createCoreComponentStrings`) to guarantee internal completeness. For partial / iterative authoring you can still start with normal objects and later switch to the strict helper when translations stabilize.
+
+#### Adding New Languages
+
+```typescript
+import { createLanguageDefinition } from '@digitaldefiance/i18n-lib';
+
+// Add Italian support
+const italian = createLanguageDefinition('it', 'Italiano', 'it');
+i18n.registerLanguage(italian);
+
+// Update existing components with Italian translations
+i18n.updateComponentStrings('my-component', {
+  it: {
+    [MyComponentStringKey.Welcome]: 'Benvenuto nel mio componente!',
+    [MyComponentStringKey.Goodbye]: 'Arrivederci dal mio componente!',
+    [MyComponentStringKey.UserGreetingTemplate]: 'Ciao, {name}!'
+  }
+});
+```
+
+#### Component Registration Validation
+
+The plugin engine provides comprehensive validation to ensure translation completeness:
+
+```typescript
+// Each component is validated against ALL system languages
+enum MyStrings {
+  Welcome = 'welcome',
+  Goodbye = 'goodbye'
+}
+
+const myComponent: ComponentDefinition<MyStrings> = {
+  id: 'my-component',
+  name: 'My Component',
+  stringKeys: Object.values(MyStrings)
+};
+
+// System has EN, FR, ES languages - component must provide translations for all three
+const registration: ComponentRegistration<MyStrings, CoreLanguage> = {
+  component: myComponent,
+  strings: {
+    [CoreLanguage.EnglishUS]: {
+      [MyStrings.Welcome]: 'Welcome',
+      [MyStrings.Goodbye]: 'Goodbye'
+    },
+    [CoreLanguage.French]: {
+      [MyStrings.Welcome]: 'Bienvenue',
+      [MyStrings.Goodbye]: 'Au revoir'
+    },
+    [CoreLanguage.Spanish]: {
+      [MyStrings.Welcome]: 'Bienvenido', 
+      [MyStrings.Goodbye]: 'Adiós'
+    }
+  }
+};
+
+const result = i18n.registerComponent(registration);
+if (!result.isValid) {
+  console.log('Missing translations:', result.missingKeys);
+  // Shows exactly which string keys are missing for which languages
+}
+```
+
+#### Flexible Language Support
+
+Components can support different subsets of system languages:
+
+```typescript
+// Component A supports EN, FR, ES
+const componentA = {
+  component: { id: 'comp-a', name: 'Component A', stringKeys: ['hello'] },
+  strings: {
+    en: { hello: 'Hello' },
+    fr: { hello: 'Bonjour' },
+    es: { hello: 'Hola' }
+  }
+};
+
+// Component B only supports EN and DE (added later)
+const componentB = {
+  component: { id: 'comp-b', name: 'Component B', stringKeys: ['save'] },
+  strings: {
+    en: { save: 'Save' },
+    de: { save: 'Speichern' }
+  }
+};
+
+// Both components can coexist - missing translations use fallback
+i18n.registerComponent(componentA); // ✓ Complete
+i18n.registerComponent(componentB); // ⚠ Missing FR, ES - uses fallback
+
+// Usage automatically handles fallbacks
+i18n.translate('comp-b', 'save', {}, 'fr'); // Returns 'Save' (EN fallback)
+```
+
+#### Dynamic Language Addition
+
+```typescript
+// Add new language to system
+const germanLang = { id: 'de', name: 'German', code: 'de' };
+i18n.registerLanguage(germanLang);
+
+// New component registrations now require German translations
+const newRegistration = {
+  component: { id: 'new-comp', name: 'New Component', stringKeys: ['test'] },
+  strings: {
+    en: { test: 'Test' },
+    fr: { test: 'Test' },
+    es: { test: 'Prueba' }
+    // Missing 'de' - validation will flag this
+  }
+};
+
+const result = i18n.registerComponent(newRegistration);
+console.log(result.missingKeys); // Shows missing German translations
+```
+
+#### Validation and Error Handling
+
+```typescript
+// Comprehensive validation
+const globalValidation = i18n.validateAllComponents();
+if (!globalValidation.isValid) {
+  console.error('Validation errors:', globalValidation.errors);
+  console.warn('Warnings:', globalValidation.warnings);
+}
+
+// Handle registration errors
+try {
+  i18n.registerComponent(incompleteRegistration);
+} catch (error) {
+  if (error instanceof RegistryError) {
+    console.error(`Registry error: ${error.type}`, error.metadata);
+  }
+}
+
+// Strict validation mode (rejects incomplete registrations)
+const strictEngine = new PluginI18nEngine(languages, {
+  validation: {
+    requireCompleteStrings: true,
+    allowPartialRegistration: false,
+    fallbackLanguageId: 'en'
+  }
+});
+```
+
+#### Multi-Instance Support
+
+```typescript
+// Create separate instances for different contexts
+const adminI18n = PluginI18nEngine.createInstance('admin', languages);
+const userI18n = PluginI18nEngine.createInstance('user', languages);
+
+// Register different components for each
+adminI18n.registerComponent(adminComponentRegistration);
+userI18n.registerComponent(userComponentRegistration);
+```
+
+For complete documentation on the plugin architecture, see [PLUGIN_ARCHITECTURE.md](./PLUGIN_ARCHITECTURE.md).
+
 ## Advanced Features
 
 ### Enum Translation Registry
@@ -214,20 +556,90 @@ I18nEngine.removeInstance('main');
 
 ## API Reference
 
-### I18nEngine
+### Plugin Architecture API
+
+#### PluginI18nEngine
+
+**Constructor**
+
+- `new PluginI18nEngine<TLanguages>(languages, config?)` - Create new plugin engine
+- `PluginI18nEngine.createInstance<TLanguages>(key, languages, config?)` - Create named instance
+- `PluginI18nEngine.getInstance<TLanguages>(key?)` - Get existing instance
+
+**Component Management**
+
+- `registerComponent<TStringKeys>(registration)` - Register component with translations
+- `updateComponentStrings<TStringKeys>(componentId, strings)` - Update existing component strings
+- `getComponents()` - Get all registered components
+- `hasComponent(componentId)` - Check if component exists
+
+**Translation Methods**
+
+- `translate<TStringKeys>(componentId, stringKey, variables?, language?)` - Translate component string
+- `safeTranslate(componentId, stringKey, variables?, language?)` - Safe translate with fallback
+- `getTranslationDetails<TStringKeys>(componentId, stringKey, variables?, language?)` - Get detailed translation response
+
+**Language Management**
+
+- `registerLanguage(language)` - Register new language
+- `registerLanguages(languages)` - Register multiple languages
+- `getLanguages()` - Get all registered languages
+- `hasLanguage(language)` - Check if language exists
+- `setLanguage(language)` - Set current language
+- `getLanguageByCode(code)` - Get language by ISO code
+
+**Validation**
+
+- `validateAllComponents()` - Validate all registered components
+- `getLanguageRegistry()` - Access language registry directly
+- `getComponentRegistry()` - Access component registry directly
+
+#### Core I18n Functions
+
+- `createCoreI18nEngine(instanceKey?)` - Create engine with core components
+- `getCoreTranslation(stringKey, variables?, language?, instanceKey?)` - Get core translation
+- `safeCoreTranslation(stringKey, variables?, language?, instanceKey?)` - Safe core translation
+
+#### Component Registration Types
+
+```typescript
+interface ComponentDefinition<TStringKeys extends string> {
+  readonly id: string;
+  readonly name: string;
+  readonly stringKeys: readonly TStringKeys[];
+}
+
+interface ComponentRegistration<TStringKeys extends string, TLanguages extends string> {
+  readonly component: ComponentDefinition<TStringKeys>;
+  readonly strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>;
+}
+
+interface LanguageDefinition {
+  readonly id: string;
+  readonly name: string;
+  readonly code: string;
+  readonly isDefault?: boolean;
+}
+```
+
+### Legacy I18nEngine (Still Supported)
 
 #### 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 string with `{{EnumName.EnumKey}}` 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
@@ -235,34 +647,41 @@ I18nEngine.removeInstance('main');
 - `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;
@@ -422,6 +841,20 @@ If localized error messages aren't provided, the engine falls back to English te
 
 ## Best Practices
 
+### Plugin Architecture (Recommended for New Projects)
+
+1. **Use Component Registration**: Organize translations into logical components with `PluginI18nEngine`
+2. **Define String Key Enums**: Always use TypeScript enums for string keys to ensure compile-time type safety
+3. **Complete Component Translations**: Provide translations for all supported languages in each component
+4. **Validate Registrations**: Check validation results and handle missing translations appropriately
+5. **Use Core Components**: Start with `createCoreI18nEngine()` for built-in system strings
+6. **Fallback Strategy**: Configure appropriate fallback languages for missing translations
+7. **Component Isolation**: Keep related strings together in the same component
+8. **Template Variables**: Use template strings with variables for dynamic content
+9. **Multi-Instance Architecture**: Use named instances for different application contexts (admin, user, etc.)
+
+### Legacy System (Still Supported)
+
 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
@@ -430,10 +863,50 @@ If localized error messages aren't provided, the engine falls back to English te
 6. **Layered Extension**: Use union types when extending configurations across libraries
 7. **Default Configuration**: Use `getDefaultI18nEngine()` for standard setups
 
+### Migration Strategy
+
+When migrating from legacy to plugin architecture:
+
+```typescript
+// Legacy approach
+const legacy = new I18nEngine(config);
+const text = legacy.translate(MyStrings.Welcome);
+
+// New plugin approach  
+const modern = createCoreI18nEngine();
+modern.registerComponent(myComponentRegistration);
+const text = modern.translate('my-component', MyStrings.Welcome);
+```
+
+Both systems can coexist in the same application during migration.
+
 ## License
 
 MIT
 
 ## Repository
 
-Part of the DigitalBurnbag project - a secure file sharing and automated protocol system.
+Part of the DigitalBurnbag project - a secure file sharing and automated protocol system.
+
+## ChangeLog
+
+### Version 1.1.1
+
+- Sat Oct 11 2025 17:47:00 GMT-0700 (Pacific Daylight Time)
+  - Improved type checking for completeness of component translations during registration
+  - Updated README/Migration guide for clarity.
+
+### Version 1.1.0
+
+- Sat Oct 11 2025 16:49:00 GMT-0700 (Pacific Daylight Time)
+  - Introduced plugin-based architecture with component registration and compile-time type safety
+  - Added `PluginI18nEngine` with comprehensive validation and fallback system
+  - Maintained full support for legacy `I18nEngine`
+  - Added pre-built core and user system components
+  - Enhanced template processing and context management features
+  - Improved documentation and examples for both architectures
+
+### Version 1.0.33
+
+- Wed Sep 24 2025 15:20:07 GMT-0700 (Pacific Daylight Time)
+  - Initial release of the TypeScript internationalization library with enum translation, template processing, context management, and currency formatting.

package/dist/component-definition.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Component definition with its string keys
+ */
+export interface ComponentDefinition<TStringKeys extends string> {
+    /** Unique identifier for the component */
+    readonly id: string;
+    /** Human-readable name for the component */
+    readonly name: string;
+    /** Array of all string keys this component requires */
+    readonly stringKeys: readonly TStringKeys[];
+}

package/dist/component-definition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/component-registration.d.ts

@@ -0,0 +1,9 @@
+import { ComponentDefinition } from './component-definition';
+import { PartialComponentLanguageStrings } from './types';
+/**
+ * Registration payload for a component with its strings
+ */
+export interface ComponentRegistration<TStringKeys extends string, TLanguages extends string> {
+    readonly component: ComponentDefinition<TStringKeys>;
+    readonly strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>;
+}

package/dist/component-registration.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/component-registry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Component registry for managing internationalization components and their string translations
+ */
+import { ComponentDefinition } from './component-definition';
+import { ComponentRegistration } from './component-registration';
+import { TranslationRequest } from './translation-request';
+import { TranslationResponse } from './translation-response';
+import { ComponentLanguageStrings, PartialComponentLanguageStrings } from './types';
+import { ValidationConfig } from './validation-config';
+import { ValidationResult } from './validation-result';
+/**
+ * Registry for managing components and their translations
+ */
+export declare class ComponentRegistry<TLanguages extends string> {
+    private readonly components;
+    private readonly componentStrings;
+    private readonly validationConfig;
+    private readonly registeredLanguages;
+    constructor(languages: readonly TLanguages[], validationConfig: ValidationConfig);
+    /**
+     * Update the set of registered languages (for dynamic language addition)
+     */
+    updateRegisteredLanguages(languages: readonly TLanguages[]): void;
+    /**
+     * Register a new component with its translations
+     */
+    registerComponent<TStringKeys extends string>(registration: ComponentRegistration<TStringKeys, TLanguages>): ValidationResult;
+    /**
+     * Update strings for an existing component
+     */
+    updateComponentStrings<TStringKeys extends string>(componentId: string, strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>): ValidationResult;
+    /**
+     * Get a translation for a specific component, string key, and language
+     */
+    getTranslation<TStringKeys extends string>(request: TranslationRequest<TStringKeys, TLanguages>): TranslationResponse;
+    /**
+     * Get all registered components
+     */
+    getComponents(): ReadonlyArray<ComponentDefinition<any>>;
+    /**
+     * Get a specific component by ID
+     */
+    getComponent<TStringKeys extends string>(componentId: string): ComponentDefinition<TStringKeys> | undefined;
+    /**
+     * Check if a component is registered
+     */
+    hasComponent(componentId: string): boolean;
+    /**
+     * Get all strings for a component in all languages
+     */
+    getComponentStrings<TStringKeys extends string>(componentId: string): ComponentLanguageStrings<TStringKeys, TLanguages> | undefined;
+    /**
+     * Validate a component registration
+     */
+    private validateComponentRegistration;
+    /**
+     * Complete missing strings with fallbacks
+     */
+    private completeStringsWithFallbacks;
+    /**
+     * Merge existing strings with new strings
+     */
+    private mergeStrings;
+}