@digitaldefiance/i18n-lib 3.8.2 → 3.8.4

package/src/core-plugin-factory.ts

@@ -1,111 +0,0 @@
-/**
- * Factory for creating core plugin I18n engine instances
- * This file breaks the circular dependency between core-i18n.ts and plugin-i18n-engine.ts
- */
-
-import {
-  createCoreComponentRegistration,
-  createDefaultLanguages,
-} from './core-i18n';
-import { PluginI18nEngine } from './plugin-i18n-engine';
-import { RegistryConfig } from './registry-config';
-
-const DefaultInstanceKey = 'default';
-
-/**
- * Create a pre-configured I18n engine with core components
- * Returns engine with string type - use registry for language validation
- */
-export function createCorePluginI18nEngine(
-  instanceKey: string = DefaultInstanceKey,
-  config?: Partial<RegistryConfig<string>>,
-): PluginI18nEngine<string> {
-  const languages = createDefaultLanguages();
-  const engine = PluginI18nEngine.createInstance<string>(
-    instanceKey,
-    languages,
-    config,
-  );
-  engine.registerComponent(createCoreComponentRegistration());
-  return engine;
-}
-
-// Note: Lazy initialization to avoid circular dependency issues
-// Tests should call resetCorePluginI18nEngine() after PluginI18nEngine.resetAll()
-let _corePluginI18nEngine: PluginI18nEngine<string> | undefined;
-
-export function getCorePluginI18nEngine(): PluginI18nEngine<string> {
-  // Lazy initialization on first access
-  if (!_corePluginI18nEngine) {
-    _corePluginI18nEngine = createCorePluginI18nEngine();
-    return _corePluginI18nEngine;
-  }
-
-  // Lazy re-initialization if instance was cleared
-  try {
-    PluginI18nEngine.getInstance<string>(DefaultInstanceKey);
-    return _corePluginI18nEngine;
-  } catch {
-    _corePluginI18nEngine = createCorePluginI18nEngine();
-    return _corePluginI18nEngine;
-  }
-}
-
-// Getter for direct reference - lazily initialized
-export const corePluginI18nEngine = new Proxy({} as PluginI18nEngine<string>, {
-  get(_target, prop) {
-    const engine = getCorePluginI18nEngine();
-    return engine[prop as keyof PluginI18nEngine<string>];
-  },
-});
-
-// Reset function for tests
-export function resetCorePluginI18nEngine(): void {
-  _corePluginI18nEngine = undefined;
-}
-
-/**
- * Type alias for easier usage
- */
-export type CorePluginI18nEngine = PluginI18nEngine<string>;
-
-/**
- * Helper function to get core translation
- * Uses the core engine instance to ensure core strings are available
- */
-export function getCorePluginTranslation(
-  stringKey: string,
-  variables?: Record<string, string | number>,
-  language?: string,
-  instanceKey?: string,
-): string {
-  // Use string literal to avoid circular dependency
-  const coreComponentId = 'core';
-
-  // Use core engine if no instance key specified, otherwise use specified instance
-  const engine = instanceKey
-    ? PluginI18nEngine.getInstance<string>(instanceKey)
-    : getCorePluginI18nEngine();
-  return engine.translate(coreComponentId, stringKey, variables, language);
-}
-
-/**
- * Helper function to safely get core translation with fallback
- */
-export function safeCorePluginTranslation(
-  stringKey: string,
-  variables?: Record<string, string | number>,
-  language?: string,
-  instanceKey?: string,
-): string {
-  try {
-    return getCorePluginTranslation(
-      stringKey,
-      variables,
-      language,
-      instanceKey,
-    );
-  } catch {
-    return `[CoreStringKey.${stringKey}]`;
-  }
-}

package/src/core-string-key.ts

@@ -1,59 +0,0 @@
-/**
- * Core system string keys
- */
-export enum CoreStringKey {
-  // Common/General
-  Common_Yes = 'common_yes',
-  Common_No = 'common_no',
-  Common_Cancel = 'common_cancel',
-  Common_OK = 'common_ok',
-  Common_Save = 'common_save',
-  Common_Delete = 'common_delete',
-  Common_Edit = 'common_edit',
-  Common_Create = 'common_create',
-  Common_Update = 'common_update',
-  Common_Loading = 'common_loading',
-  Common_Error = 'common_error',
-  Common_Success = 'common_success',
-  Common_Warning = 'common_warning',
-  Common_Info = 'common_info',
-  Common_Disposed = 'common_disposed',
-  Common_Test = 'common_test',
-  // Error Messages
-  Error_InvalidInput = 'error_invalidInput',
-  Error_NetworkError = 'error_networkError',
-  Error_NotFound = 'error_notFound',
-  Error_AccessDenied = 'error_accessDenied',
-  Error_InternalServer = 'error_internalServer',
-  Error_ValidationFailed = 'error_validationFailed',
-  Error_RequiredField = 'error_requiredField',
-  Error_InvalidContext = 'error_invalidContext',
-  Error_InvalidContextTemplate = 'error_invalidContextTemplate',
-  Error_InvalidCurrencyCodeTemplate = 'error_invalidCurrencyCodeTemplate',
-
-  // Registry Errors (templates support variables)
-  Error_ComponentNotFoundTemplate = 'error_componentNotFoundTemplate',
-  Error_LanguageNotFoundTemplate = 'error_languageNotFoundTemplate',
-  Error_StringKeyNotFoundTemplate = 'error_stringKeyNotFoundTemplate',
-  Error_IncompleteRegistrationTemplate = 'error_incompleteRegistrationTemplate',
-  Error_DuplicateComponentTemplate = 'error_duplicateComponentTemplate',
-  Error_DuplicateLanguageTemplate = 'error_duplicateLanguageTemplate',
-  Error_ValidationFailedTemplate = 'error_validationFailedTemplate',
-  Error_MissingTranslationKeyTemplate = 'error_missingTranslationKeyTemplate',
-
-  // System Messages
-  System_Welcome = 'system_welcome',
-  System_Goodbye = 'system_goodbye',
-  System_PleaseWait = 'system_pleaseWait',
-  System_ProcessingRequest = 'system_processingRequest',
-  System_OperationComplete = 'system_operationComplete',
-  System_NoDataAvailable = 'system_noDataAvailable',
-
-  // DefaultStringKey
-  Error_InstanceAlreadyExistsTemplate = 'error_instanceAlreadyExistsTemplate',
-  Error_InstanceNotFoundTemplate = 'error_instanceNotFoundTemplate',
-  Error_MissingStringCollectionTemplate = 'error_missingStringCollectionTemplate',
-  Error_MissingTranslationTemplate = 'error_missingTranslationTemplate',
-  Error_DefaultLanguageNoCollectionTemplate = 'error_defaultLanguageNoCollectionTemplate',
-  Error_MissingTranslationKeyForTypeTemplate = 'error_missingTranslationKeyForTypeTemplate',
-}

package/src/create-translation-adapter.ts

@@ -1,93 +0,0 @@
-import { PluginI18nEngine } from './plugin-i18n-engine';
-import { TranslationEngine } from './translation-engine';
-
-/**
- * Creates a TranslationEngine adapter from a PluginI18nEngine for a specific component.
- * This allows PluginI18nEngine to be used where TranslationEngine interface is expected.
- * 
- * The adapter supports both calling conventions:
- * - Full TranslationEngine interface: `translate(componentId, key, vars, lang)`
- * - Simplified interface: `translate(key, vars, lang)` (componentId is bound)
- *
- * @param pluginEngine - The PluginI18nEngine instance to wrap
- * @param componentId - The component ID to use for translations
- * @returns A TranslationEngine that delegates to the PluginI18nEngine
- *
- * @example
- * ```typescript
- * const pluginEngine = getMyPluginI18nEngine();
- * const adapter = createTranslationAdapter(pluginEngine, 'my-component');
- *
- * // Simplified interface (componentId is bound)
- * const text1 = adapter.translate('key');
- * const text2 = adapter.translate('key', { var: 'value' });
- * const text3 = adapter.translate('key', { var: 'value' }, 'fr');
- *
- * // Full TranslationEngine interface
- * const text4 = adapter.translate('other-component', 'key', { var: 'value' }, 'fr');
- * ```
- */
-export function createTranslationAdapter<
-  TStringKey extends string,
-  TLanguage extends string,
->(
-  pluginEngine: PluginI18nEngine<TLanguage>,
-  componentId: string,
-): TranslationEngine<TStringKey> & {
-  translate(key: TStringKey, vars?: Record<string, string | number>, lang?: TLanguage): string;
-  safeTranslate(key: TStringKey, vars?: Record<string, string | number>, lang?: TLanguage): string;
-} {
-  const adapter: any = {
-    translate: (
-      keyOrComponentId: string | TStringKey,
-      varsOrKey?: TStringKey | Record<string, string | number>,
-      langOrVars?: TLanguage | Record<string, string | number>,
-      maybeLang?: TLanguage,
-    ): string => {
-      let actualKey: TStringKey;
-      let actualVars: Record<string, string | number> | undefined;
-      let actualLang: TLanguage | undefined;
-
-      if (arguments.length >= 4 || (typeof varsOrKey === 'string')) {
-        actualKey = varsOrKey as TStringKey;
-        actualVars = langOrVars as Record<string, string | number> | undefined;
-        actualLang = maybeLang;
-      } else {
-        actualKey = keyOrComponentId as TStringKey;
-        actualVars = varsOrKey as Record<string, string | number> | undefined;
-        actualLang = langOrVars as TLanguage | undefined;
-      }
-
-      try {
-        return pluginEngine.translate(componentId, actualKey, actualVars, actualLang);
-      } catch (error) {
-        return String(actualKey);
-      }
-    },
-
-    safeTranslate: (
-      keyOrComponentId: string | TStringKey,
-      varsOrKey?: TStringKey | Record<string, string | number>,
-      langOrVars?: TLanguage | Record<string, string | number>,
-      maybeLang?: TLanguage,
-    ): string => {
-      let actualKey: TStringKey;
-      let actualVars: Record<string, string | number> | undefined;
-      let actualLang: TLanguage | undefined;
-
-      if (arguments.length >= 4 || (typeof varsOrKey === 'string')) {
-        actualKey = varsOrKey as TStringKey;
-        actualVars = langOrVars as Record<string, string | number> | undefined;
-        actualLang = maybeLang;
-      } else {
-        actualKey = keyOrComponentId as TStringKey;
-        actualVars = varsOrKey as Record<string, string | number> | undefined;
-        actualLang = langOrVars as TLanguage | undefined;
-      }
-
-      return pluginEngine.safeTranslate(componentId, actualKey, actualVars, actualLang);
-    },
-  };
-
-  return adapter;
-}

package/src/enum-registry.ts

@@ -1,152 +0,0 @@
-import { EnumLanguageTranslation } from './types';
-
-/**
- * Registry for managing translations of enum values across multiple languages.
- *
- * @template TStringKey Type of translation key used in error messages.
- * @template TLanguage Type of supported language codes.
- */
-export class EnumTranslationRegistry<
-  TStringKey extends string,
-  TLanguage extends string,
-> {
-  protected translations = new Map<any, EnumLanguageTranslation<any, TLanguage>>();
-  protected enumNames = new WeakMap<any, string>();
-  protected availableLanguages: Set<TLanguage>;
-  protected translateFn?: (key: TStringKey, vars?: Record<string, any>) => string;
-
-  /**
-   * Creates a new EnumTranslationRegistry.
-   *
-   * @param availableLanguages Array of supported language codes.
-   * @param translateFn Optional translation function for error templates.
-   */
-  constructor(
-    availableLanguages: TLanguage[],
-    translateFn?: (key: TStringKey, vars?: Record<string, any>) => string,
-  ) {
-    this.availableLanguages = new Set(availableLanguages);
-    this.translateFn = translateFn;
-  }
-
-  /**
-   * Registers an enum and its language-specific translations.
-   *
-   * @template TEnum Enum value type (string or number).
-   * @param enumObj The enum object to register.
-   * @param translations Mapping of language codes to value-to-string translations.
-   * @param enumName Human-readable name of the enum (used in errors).
-   * @throws {Error} If translations contain languages not in availableLanguages.
-   */
-  public register<TEnum extends string | number>(
-    enumObj: Record<string, TEnum>,
-    translations: EnumLanguageTranslation<TEnum, TLanguage>,
-    enumName: string,
-  ): void {
-    this.validateTranslations(translations, enumName);
-    this.translations.set(enumObj, translations);
-    this.enumNames.set(enumObj, enumName);
-  }
-
-  /**
-   * Translates a specific enum value into the target language.
-   *
-   * @template TEnum Enum value type.
-   * @param enumObj The enum object registered previously.
-   * @param value The enum value to translate.
-   * @param language The target language code.
-   * @returns The translated string.
-   * @throws {Error} If the enum or language or value is not found.
-   */
-  public translate<TEnum extends string | number>(
-    enumObj: Record<string, TEnum>,
-    value: TEnum,
-    language: TLanguage,
-  ): string {
-    const translations = this.translations.get(enumObj);
-    if (!translations) {
-      const message = this.translateFn
-        ? this.translateFn('Error_EnumNotFoundTemplate' as TStringKey, {
-            enumName: this.getEnumName(enumObj),
-          })
-        : `No translations found for enum: ${this.getEnumName(enumObj)}`;
-      throw new Error(message);
-    }
-
-    const langTranslations = translations[language];
-    if (!langTranslations) {
-      const message = this.translateFn
-        ? this.translateFn('Error_EnumLanguageNotFoundTemplate' as TStringKey, {
-            language,
-          })
-        : `No translations found for language: ${language}`;
-      throw new Error(message);
-    }
-
-    let result = langTranslations[value];
-    if (!result && typeof value === 'number') {
-      const stringKey = Object.keys(enumObj).find(
-        (key) => enumObj[key] === value,
-      );
-      if (stringKey) {
-        result = langTranslations[stringKey as TEnum];
-      }
-    }
-
-    if (!result) {
-      const message = this.translateFn
-        ? this.translateFn('Error_EnumValueNotFoundTemplate' as TStringKey, {
-            value: String(value),
-          })
-        : `No translation found for value: ${String(value)}`;
-      throw new Error(message);
-    }
-
-    return result;
-  }
-
-  /**
-   * Checks whether translations exist for the given enum object.
-   *
-   * @param enumObj The enum object to check.
-   * @returns True if registered, false otherwise.
-   */
-  public has(enumObj: any): boolean {
-    return this.translations.has(enumObj);
-  }
-
-  /**
-   * Internal: Retrieves the human-readable name of the enum.
-   *
-   * @param enumObj The enum object.
-   * @returns Registered enum name or 'UnknownEnum' if not set.
-   */
-  private getEnumName(enumObj: any): string {
-    return this.enumNames.get(enumObj) || 'UnknownEnum';
-  }
-
-  /**
-   * Internal: Validates that translation entries only use available languages.
-   *
-   * @template TEnum Enum value type.
-   * @param translations Mapping of language codes to translations.
-   * @param enumName Enum name for error reporting.
-   * @throws {Error} If a translation language is not available.
-   */
-  private validateTranslations<TEnum extends string | number>(
-    translations: EnumLanguageTranslation<TEnum, TLanguage>,
-    enumName: string,
-  ): void {
-    for (const language of Object.keys(translations) as TLanguage[]) {
-      if (!this.availableLanguages.has(language)) {
-        const message = this.translateFn
-          ? this.translateFn(
-              'Error_EnumLanguageNotAvailableTemplate' as TStringKey,
-              { language, enumName },
-            )
-          : `Language '${language}' in enum '${enumName}' is not available in this registry`;
-        throw new Error(message);
-      }
-    }
-  }
-}

package/src/errors/context-error.ts

@@ -1,122 +0,0 @@
-import { ContextErrorType } from '../context-error-type';
-import { CoreI18nComponentId } from '../core-component-id';
-import { CoreStringKey } from '../core-string-key';
-import { EnhancedErrorHelper } from './enhanced-error-base';
-
-// Lazy reference to I18nEngine to avoid circular dependencies
-let engineGetter: (() => any) | undefined;
-
-/**
- * Error class for context-related failures in the i18n system.
- * Thrown when attempting to access or manipulate an invalid or non-existent context.
- *
- * **i18n Feature Support:**
- * - ICU MessageFormat variable substitution
- * - Nested message paths detection
- * - Number formatting for context depths/positions
- * - SelectOrdinal for context priority levels
- *
- * **Translation String Examples:**
- * ```typescript
- * // ICU plural
- * "Context has {count, plural, one {# issue} other {# issues}}"
- *
- * // ICU select + nested
- * "{severity, select, low {Minor context issue} high {Critical context error}}"
- *
- * // Number formatting
- * "Context exceeded {limit, number, integer} maximum depth"
- * ```
- */
-export class ContextError extends Error {
-  /** The type of context error */
-  public override readonly type: ContextErrorType;
-  /** The context key that caused the error, if applicable */
-  public readonly contextKey?: string;
-  /** Additional context metadata */
-  public override readonly metadata?: Record<string, any>;
-
-  /**
-   * Creates a new ContextError instance.
-   * @param type - The type of context error
-   * @param contextKey - Optional context key that caused the error
-   * @param variables - Additional variables for ICU message formatting
-   * @param language - Optional language code
-   */
-  constructor(
-    type: ContextErrorType,
-    contextKey?: string,
-    variables?: Record<string, string | number>,
-    language?: string,
-  ) {
-    // Lazy initialization: get engine instance at runtime to avoid circular dependencies
-    let message: string;
-    try {
-      // Lazy load I18nEngine to break circular dependency
-      if (!engineGetter) {
-        // Dynamically import at runtime
-        const coreModule = eval('require')('../core');
-        engineGetter = () => coreModule.I18nEngine.getInstance('default');
-      }
-      const engine = engineGetter();
-      const allVars = { ...variables, contextKey: contextKey || '' };
-      message = contextKey
-        ? engine.safeTranslate(
-            CoreI18nComponentId,
-            CoreStringKey.Error_InvalidContextTemplate,
-            allVars,
-            language,
-          )
-        : engine.safeTranslate(
-            CoreI18nComponentId,
-            CoreStringKey.Error_InvalidContext,
-            allVars,
-            language,
-          );
-    } catch {
-      // Fallback if engine not available
-      message = contextKey
-        ? `Invalid context: ${contextKey}`
-        : 'Invalid context';
-    }
-    super(message);
-    this.name = 'ContextError';
-    this.type = type;
-    this.contextKey = contextKey;
-    this.metadata = variables;
-  }
-
-  /**
-   * Create context error with nested path information
-   * Demonstrates selectordinal for depth level
-   */
-  static withNestedPath(
-    type: ContextErrorType,
-    contextPath: string,
-    language = 'en-US',
-  ): ContextError {
-    const analysis = EnhancedErrorHelper.analyzeKeyPath(contextPath);
-    return new ContextError(
-      type,
-      contextPath,
-      {
-        depth: analysis.depth,
-        isNested: analysis.isNested ? 'true' : 'false',
-      },
-      language,
-    );
-  }
-
-  /**
-   * Create context error with count information
-   * Demonstrates plural formatting
-   */
-  static withCount(
-    type: ContextErrorType,
-    contextKey: string,
-    count: number,
-    language = 'en-US',
-  ): ContextError {
-    return new ContextError(type, contextKey, { count }, language);
-  }
-}