@digitaldefiance/i18n-lib 1.3.12 → 1.3.13

package/src/plugin-i18n-engine.ts

@@ -0,0 +1,520 @@
+/**
+ * Plugin-based internationalization engine with component and language registration
+ */
+
+import { ComponentDefinition } from './component-definition';
+import { ComponentRegistration } from './component-registration';
+import { ComponentRegistry } from './component-registry';
+import { CurrencyCode } from './currency-code';
+import { EnumTranslationRegistry } from './enum-registry';
+import { GlobalActiveContext } from './global-active-context';
+import { IActiveContext } from './active-context';
+import { LanguageDefinition } from './language-definition';
+import { LanguageRegistry } from './language-registry';
+import { RegistryConfig } from './registry-config';
+import { RegistryError } from './registry-error';
+import { RegistryErrorType } from './registry-error-type';
+import { Timezone } from './timezone';
+import { TranslationRequest } from './translation-request';
+import { TranslationResponse } from './translation-response';
+import { EnumLanguageTranslation } from './types';
+
+/**
+ * Plugin-based I18n Engine with registration capabilities
+ */
+export class PluginI18nEngine<TLanguages extends string> {
+  private readonly componentRegistry: ComponentRegistry<TLanguages>;
+  private readonly enumRegistry: EnumTranslationRegistry<string, TLanguages>;
+  private readonly config: RegistryConfig<TLanguages>;
+  private contextKey: string;
+
+  /**
+   * Default template processor instance
+   */
+  public readonly t: (
+    str: string,
+    language?: TLanguages,
+    ...otherVars: Record<string, string | number>[]
+  ) => string;
+
+
+
+  /**
+   * Static instances for semi-singleton pattern
+   */
+  private static _instances = new Map<string, PluginI18nEngine<any>>();
+  private static _defaultKey: string | null = null;
+  protected static readonly DefaultInstanceKey = 'default';
+
+  constructor(
+    initialLanguages: readonly LanguageDefinition[],
+    config: Partial<RegistryConfig<TLanguages>> = {},
+  ) {
+    // Find default language from initialLanguages or use the first one
+    const defaultLang =
+      initialLanguages.find((l) => l.isDefault) || initialLanguages[0];
+    if (!defaultLang) {
+      throw new Error('At least one language must be provided');
+    }
+
+    // Set up configuration with defaults
+    this.config = {
+      defaultLanguage: defaultLang.id as TLanguages,
+      fallbackLanguage: defaultLang.id as TLanguages,
+      defaultCurrencyCode: new CurrencyCode('USD'),
+      timezone: new Timezone('UTC'),
+      adminTimezone: new Timezone('UTC'),
+      validation: {
+        requireCompleteStrings: false,
+        allowPartialRegistration: true,
+        fallbackLanguageId: defaultLang.id,
+      },
+      ...config,
+    };
+
+    // Register initial languages in static registry (skip if already registered)
+    for (const lang of initialLanguages) {
+      if (!LanguageRegistry.hasLanguage(lang.id)) {
+        LanguageRegistry.registerLanguage(lang);
+      }
+    }
+
+    // Initialize component registry (per-instance)
+    this.componentRegistry = new ComponentRegistry<TLanguages>(
+      initialLanguages.map((l) => l.id as TLanguages),
+      this.config.validation,
+    );
+    this.enumRegistry = new EnumTranslationRegistry<string, TLanguages>(
+      initialLanguages.map((l) => l.id as TLanguages),
+      (key: string, vars?: Record<string, any>) =>
+        this.safeTranslate('core', key, vars),
+    );
+
+    // Initialize context key for this engine instance
+    this.contextKey = PluginI18nEngine.DefaultInstanceKey;
+    
+    // Create or get the global context for this engine
+    const globalContext = GlobalActiveContext.getInstance<TLanguages, IActiveContext<TLanguages>>();
+    
+    // Always create/update the context for this engine
+    globalContext.createContext(
+      this.config.defaultLanguage,
+      this.config.defaultLanguage,
+      this.contextKey
+    );
+    globalContext.setCurrencyCode(this.config.defaultCurrencyCode, this.contextKey);
+    globalContext.setUserTimezone(this.config.timezone, this.contextKey);
+    globalContext.setAdminTimezone(this.config.adminTimezone, this.contextKey);
+
+    // Initialize the default template processor for component-based patterns
+    this.t = (str: string, language?: TLanguages, ...otherVars: Record<string, string | number>[]) => {
+      // Step 1: Replace component-based patterns like {{componentId.stringKey}}
+      let result = str.replace(/\{\{([^}]+)\}\}/g, (match, pattern) => {
+        const parts = pattern.split('.');
+        if (parts.length === 2) {
+          const [componentId, stringKey] = parts;
+          // For template strings, use the first variable object if available
+          const isTemplate = stringKey.toLowerCase().endsWith('template');
+          const vars = isTemplate && otherVars.length > 0 ? otherVars[0] : {};
+          return this.safeTranslate(componentId.trim(), stringKey.trim(), vars, language);
+        }
+        return match; // Return original if pattern doesn't match expected format
+      });
+      
+      // Step 2: Replace remaining variable patterns like {varName} with merged variables
+      const allVars = otherVars.reduce((acc, vars) => ({ ...acc, ...vars }), {});
+      result = result.replace(/\{(\w+)\}/g, (match, varName) => {
+        return allVars[varName] !== undefined ? String(allVars[varName]) : match;
+      });
+      
+      return result;
+    };
+
+    // Auto-register as default instance if none exists
+    if (!PluginI18nEngine._defaultKey) {
+      PluginI18nEngine._instances.set(
+        PluginI18nEngine.DefaultInstanceKey,
+        this,
+      );
+      PluginI18nEngine._defaultKey = PluginI18nEngine.DefaultInstanceKey;
+    }
+  }
+
+  /**
+   * Create a new instance with a specific key
+   */
+  public static createInstance<TLangs extends string>(
+    key: string,
+    initialLanguages: readonly LanguageDefinition[],
+    config?: Partial<RegistryConfig<TLangs>>,
+  ): PluginI18nEngine<TLangs> {
+    if (PluginI18nEngine._instances.has(key)) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.DuplicateComponent,
+        `I18n instance with key '${key}' already exists`,
+        { key },
+      );
+    }
+
+    const instance = new PluginI18nEngine<TLangs>(initialLanguages, config);
+    instance.contextKey = key;
+    
+    // Create context for this specific instance
+    const globalContext = GlobalActiveContext.getInstance();
+    globalContext.createContext(
+      instance.config.defaultLanguage,
+      instance.config.defaultLanguage,
+      key
+    );
+    globalContext.setCurrencyCode(instance.config.defaultCurrencyCode, key);
+    globalContext.setUserTimezone(instance.config.timezone, key);
+    globalContext.setAdminTimezone(instance.config.adminTimezone, key);
+    
+    PluginI18nEngine._instances.set(key, instance);
+
+    if (!PluginI18nEngine._defaultKey) {
+      PluginI18nEngine._defaultKey = key;
+    }
+
+    return instance;
+  }
+
+  /**
+   * Get an existing instance by key
+   */
+  public static getInstance<TLangs extends string>(
+    key?: string,
+  ): PluginI18nEngine<TLangs> {
+    const instanceKey =
+      key ||
+      PluginI18nEngine._defaultKey ||
+      PluginI18nEngine.DefaultInstanceKey;
+    const instance = PluginI18nEngine._instances.get(instanceKey);
+
+    if (!instance) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.ComponentNotFound,
+        `I18n instance with key '${instanceKey}' not found`,
+        { key: instanceKey },
+      );
+    }
+
+    return instance as PluginI18nEngine<TLangs>;
+  }
+
+  /**
+   * Register a new language (updates static registry)
+   */
+  public registerLanguage(language: LanguageDefinition): void {
+    LanguageRegistry.registerLanguage(language);
+
+    // Update component registry with new language
+    const newLanguages = LanguageRegistry.getLanguageIds();
+    this.componentRegistry.updateRegisteredLanguages(
+      newLanguages as TLanguages[],
+    );
+  }
+
+  /**
+   * Register multiple languages (updates static registry)
+   */
+  public registerLanguages(languages: readonly LanguageDefinition[]): void {
+    for (const language of languages) {
+      this.registerLanguage(language);
+    }
+  }
+
+  /**
+   * Register a component with its translations
+   */
+  public registerComponent<TStringKeys extends string>(
+    registration: ComponentRegistration<TStringKeys, TLanguages>,
+  ) {
+    return this.componentRegistry.registerComponent(registration);
+  }
+
+  /**
+   * Update strings for an existing component
+   */
+  public updateComponentStrings<TStringKeys extends string>(
+    componentId: string,
+    strings: Parameters<
+      ComponentRegistry<TLanguages>['updateComponentStrings']
+    >[1],
+  ) {
+    return this.componentRegistry.updateComponentStrings(componentId, strings);
+  }
+
+  /**
+   * Register an enum with translations
+   */
+  public registerEnum<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    translations: EnumLanguageTranslation<TEnum, TLanguages>,
+    enumName: string,
+  ): void {
+    this.enumRegistry.register(enumObj, translations, enumName);
+  }
+
+  /**
+   * Translate a string for a component
+   */
+  public translate<TStringKeys extends string>(
+    componentId: string,
+    stringKey: TStringKeys,
+    variables?: Record<string, string | number>,
+    language?: TLanguages,
+  ): string {
+    const request: TranslationRequest<TStringKeys, TLanguages> = {
+      componentId,
+      stringKey,
+      language: language || this.getCurrentLanguage(),
+      variables,
+    };
+
+    const response = this.componentRegistry.getTranslation(request);
+    return response.translation;
+  }
+
+  /**
+   * Safe translate that returns a placeholder if translation fails
+   */
+  public safeTranslate(
+    componentId: string,
+    stringKey: string,
+    variables?: Record<string, string | number>,
+    language?: TLanguages,
+  ): string {
+    try {
+      return this.translate(componentId, stringKey, variables, language);
+    } catch (error) {
+      // Return a placeholder if translation fails
+      return `[${componentId}.${stringKey}]`;
+    }
+  }
+
+  /**
+   * Translate an enum value
+   */
+  public translateEnum<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    value: TEnum,
+    language?: TLanguages,
+  ): string {
+    return this.enumRegistry.translate(
+      enumObj,
+      value,
+      language || this.getCurrentLanguage(),
+    );
+  }
+
+  /**
+   * Get detailed translation response
+   */
+  public getTranslationDetails<TStringKeys extends string>(
+    componentId: string,
+    stringKey: TStringKeys,
+    variables?: Record<string, string | number>,
+    language?: TLanguages,
+  ): TranslationResponse {
+    const request: TranslationRequest<TStringKeys, TLanguages> = {
+      componentId,
+      stringKey,
+      language: language || this.getCurrentLanguage(),
+      variables,
+    };
+
+    return this.componentRegistry.getTranslation(request);
+  }
+
+  /**
+   * Get current context
+   */
+  public getContext(): IActiveContext<TLanguages> {
+    const globalContext = GlobalActiveContext.getInstance<TLanguages, IActiveContext<TLanguages>>();
+    return globalContext.getContext(this.contextKey);
+  }
+
+  /**
+   * Update context
+   */
+  public updateContext(updates: Partial<IActiveContext<TLanguages>>): void {
+    const globalContext = GlobalActiveContext.getInstance<TLanguages, IActiveContext<TLanguages>>();
+    
+    if (updates.language) globalContext.setUserLanguage(updates.language, this.contextKey);
+    if (updates.adminLanguage) globalContext.setAdminLanguage(updates.adminLanguage, this.contextKey);
+    if (updates.currencyCode) globalContext.setCurrencyCode(updates.currencyCode, this.contextKey);
+    if (updates.currentContext) globalContext.setLanguageContextSpace(updates.currentContext, this.contextKey);
+    if (updates.timezone) globalContext.setUserTimezone(updates.timezone, this.contextKey);
+    if (updates.adminTimezone) globalContext.setAdminTimezone(updates.adminTimezone, this.contextKey);
+  }
+
+  /**
+   * Get current language from global context
+   * Respects language context space (admin vs user)
+   */
+  private getCurrentLanguage(): TLanguages {
+    const globalContext = GlobalActiveContext.getInstance<TLanguages, IActiveContext<TLanguages>>();
+    const context = globalContext.getContext(this.contextKey);
+    return context.currentContext === 'admin' ? context.adminLanguage : context.language;
+  }
+
+  /**
+   * Set current language
+   */
+  public setLanguage(language: TLanguages): void {
+    if (!LanguageRegistry.hasLanguage(language)) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.LanguageNotFound,
+        `Language '${language}' is not registered`,
+        { language },
+      );
+    }
+    const globalContext = GlobalActiveContext.getInstance<TLanguages, IActiveContext<TLanguages>>();
+    globalContext.setUserLanguage(language, this.contextKey);
+  }
+
+  /**
+   * Get available languages from static registry
+   */
+  public getLanguages(): readonly LanguageDefinition[] {
+    return LanguageRegistry.getAllLanguages();
+  }
+
+  /**
+   * Get registered components
+   */
+  public getComponents(): ReadonlyArray<ComponentDefinition<any>> {
+    return this.componentRegistry.getComponents();
+  }
+
+  /**
+   * Check if a component is registered
+   */
+  public hasComponent(componentId: string): boolean {
+    return this.componentRegistry.hasComponent(componentId);
+  }
+
+  /**
+   * Check if a language is registered in static registry
+   */
+  public hasLanguage(language: TLanguages): boolean {
+    return LanguageRegistry.hasLanguage(language);
+  }
+
+  /**
+   * Get language by code from static registry
+   */
+  public getLanguageByCode(code: string): LanguageDefinition | undefined {
+    return LanguageRegistry.getLanguageByCode(code);
+  }
+
+  /**
+   * Get component registry for direct access
+   */
+  public getComponentRegistry(): ComponentRegistry<TLanguages> {
+    return this.componentRegistry;
+  }
+
+  /**
+   * Get enum registry for direct access
+   */
+  public getEnumRegistry(): EnumTranslationRegistry<string, TLanguages> {
+    return this.enumRegistry;
+  }
+
+  /**
+   * Validate that all components have complete translations
+   */
+  public validateAllComponents(): {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+  } {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+    let isValid = true;
+
+    const components = this.getComponents();
+    const languages = LanguageRegistry.getLanguageIds();
+
+    for (const component of components) {
+      const componentStrings = this.componentRegistry.getComponentStrings(
+        component.id,
+      );
+
+      if (!componentStrings) {
+        errors.push(`Component '${component.id}' has no registered strings`);
+        isValid = false;
+        continue;
+      }
+
+      for (const language of languages) {
+        const languageStrings = componentStrings[language as TLanguages];
+
+        if (!languageStrings) {
+          errors.push(
+            `Component '${component.id}' missing strings for language '${language}'`,
+          );
+          isValid = false;
+          continue;
+        }
+
+        for (const stringKey of component.stringKeys) {
+          if (!languageStrings[stringKey]) {
+            warnings.push(
+              `Component '${component.id}' missing key '${stringKey}' for language '${language}'`,
+            );
+          }
+        }
+      }
+    }
+
+    return { isValid, errors, warnings };
+  }
+
+  /**
+   * Clear all component registrations for this instance (useful for testing)
+   */
+  public clearAllComponents(): void {
+    this.componentRegistry.clearAllComponents();
+  }
+
+  /**
+   * Remove a specific named instance
+   */
+  public static removeInstance(key?: string): boolean {
+    const instanceKey = key || PluginI18nEngine.DefaultInstanceKey;
+    const removed = PluginI18nEngine._instances.delete(instanceKey);
+
+    // If we removed the default instance, clear the default key
+    if (removed && PluginI18nEngine._defaultKey === instanceKey) {
+      PluginI18nEngine._defaultKey = null;
+    }
+
+    return removed;
+  }
+
+  /**
+   * Check if an instance exists
+   */
+  public static hasInstance(key?: string): boolean {
+    const instanceKey = key || PluginI18nEngine.DefaultInstanceKey;
+    return PluginI18nEngine._instances.has(instanceKey);
+  }
+
+  /**
+   * Reset all plugin engines and clear component registrations
+   * Useful for test cleanup
+   */
+  public static resetAll(): void {
+    // Clear component registrations for each engine BEFORE clearing instances
+    for (const engine of PluginI18nEngine._instances.values()) {
+      engine.clearAllComponents();
+    }
+    PluginI18nEngine._instances.clear();
+    PluginI18nEngine._defaultKey = null;
+    LanguageRegistry.clear();
+    GlobalActiveContext.clearAll();
+  }
+}

package/src/plugin-translatable-generic-error.ts

@@ -0,0 +1,106 @@
+import { PluginI18nEngine } from './plugin-i18n-engine';
+
+/**
+ * Generic translatable error that works with any plugin engine and component
+ */
+export class PluginTranslatableGenericError<
+  TStringKey extends string = string,
+  TLanguage extends string = string,
+> extends Error {
+  public readonly stringKey: TStringKey;
+  public readonly componentId: string;
+  public readonly language?: TLanguage;
+  public readonly variables?: Record<string, string | number>;
+  public readonly metadata?: Record<string, any>;
+
+  /**
+   * Create a translatable error
+   * @param componentId - The component ID to translate from
+   * @param stringKey - The translation key
+   * @param variables - Variables for interpolation
+   * @param language - Optional language override
+   * @param metadata - Additional error metadata
+   * @param instanceKey - Optional engine instance key
+   */
+  constructor(
+    componentId: string,
+    stringKey: TStringKey,
+    variables?: Record<string, string | number>,
+    language?: TLanguage,
+    metadata?: Record<string, any>,
+    instanceKey?: string,
+  ) {
+    let translatedMessage: string;
+
+    try {
+      const engine = PluginI18nEngine.getInstance<TLanguage>(instanceKey);
+      translatedMessage = engine.safeTranslate(
+        componentId,
+        stringKey,
+        variables,
+        language,
+      );
+    } catch (error) {
+      // If engine not found or translation fails, use fallback format
+      translatedMessage = `[${componentId}.${stringKey}]`;
+    }
+
+    super(translatedMessage);
+    this.name = 'TranslatableGenericError';
+    this.stringKey = stringKey;
+    this.componentId = componentId;
+    this.language = language;
+    this.variables = variables;
+    this.metadata = metadata;
+
+    // Ensure proper prototype chain for instanceof checks across transpiled targets
+  }
+
+  /**
+   * Create error with explicit engine instance
+   */
+  static withEngine<TStringKey extends string, TLanguage extends string>(
+    engine: PluginI18nEngine<TLanguage>,
+    componentId: string,
+    stringKey: TStringKey,
+    variables?: Record<string, string | number>,
+    language?: TLanguage,
+    metadata?: Record<string, any>,
+  ): PluginTranslatableGenericError<TStringKey, TLanguage> {
+    const translatedMessage = engine.safeTranslate(
+      componentId,
+      stringKey,
+      variables,
+      language,
+    );
+
+    const error = Object.create(PluginTranslatableGenericError.prototype);
+    Error.call(error, translatedMessage);
+    error.name = 'TranslatableGenericError';
+    error.stringKey = stringKey;
+    error.componentId = componentId;
+    error.language = language;
+    error.variables = variables;
+    error.metadata = metadata;
+    error.message = translatedMessage;
+
+    return error;
+  }
+
+  /**
+   * Retranslate the error message in a different language
+   */
+  retranslate(language: TLanguage, instanceKey?: string): string {
+    try {
+      const engine = PluginI18nEngine.getInstance<TLanguage>(instanceKey);
+      return engine.safeTranslate(
+        this.componentId,
+        this.stringKey,
+        this.variables,
+        language,
+      );
+    } catch (error) {
+      return `[${this.componentId}.${this.stringKey}]`;
+    }
+  }
+}

package/src/plugin-translatable-handleable-generic.ts

@@ -0,0 +1,60 @@
+import { IHandleable } from './i-handleable';
+import { PluginTranslatableGenericError } from './plugin-translatable-generic-error';
+
+/**
+ * Generic translatable error that works with any plugin engine and component
+ */
+export class PluginTranslatableHandleableGenericError<
+    TStringKey extends string = string,
+    TLanguage extends string = string,
+  >
+  extends PluginTranslatableGenericError<TStringKey, TLanguage>
+  implements IHandleable
+{
+  private _handled = false;
+  public override readonly cause?: Error;
+  public readonly statusCode: number;
+  public readonly sourceData?: unknown;
+
+  /**
+   * Create a translatable error
+   * @param componentId - The component ID to translate from
+   * @param stringKey - The translation key
+   * @param variables - Variables for interpolation
+   * @param language - Optional language override
+   * @param metadata - Additional error metadata
+   * @param instanceKey - Optional engine instance key
+   */
+  constructor(
+    componentId: string,
+    stringKey: TStringKey,
+    variables?: Record<string, string | number>,
+    language?: TLanguage,
+    metadata?: Record<string, any>,
+    instanceKey?: string,
+    handleableOptions?: {
+      statusCode?: number;
+      cause?: Error;
+      sourceData?: unknown;
+    },
+  ) {
+    super(componentId, stringKey, variables, language, metadata, instanceKey);
+    this.statusCode = handleableOptions?.statusCode ?? 500;
+    this.cause = handleableOptions?.cause;
+    this.sourceData = handleableOptions?.sourceData;
+  }
+  public get handled(): boolean {
+    return this._handled;
+  }
+  public set handled(value: boolean) {
+    this._handled = value;
+  }
+  toJSON(): Record<string, unknown> {
+    return {
+      statusCode: this.statusCode,
+      message: this.message,
+      cause: this.cause,
+      sourceData: this.sourceData,
+    };
+  }
+}