@digitaldefiance/i18n-lib 3.8.2 → 3.8.4

package/src/errors/translatable-generic.ts

@@ -1,245 +0,0 @@
-import { I18nEngine } from '../core/i18n-engine';
-import { GenderCategory } from '../gender/gender-categories';
-
-/**
- * Generic translatable error that works with any plugin engine and component.
- *
- * Uses lazy initialization to avoid circular dependencies with core modules.
- * The I18nEngine is only accessed when the error is constructed, not at module load time.
- *
- * **Full i18n 3.0/3.5 Feature Support:**
- * - ICU MessageFormat (all formatters: plural, select, selectordinal)
- * - Pluralization for 37 languages with CLDR rules
- * - Gender-aware translations (male, female, neutral, other)
- * - Number formatting (integer, currency, percent)
- * - Date/Time formatting (short, medium, long, full)
- * - Nested messages up to 4 levels deep
- * - Context variable injection
- *
- * **Usage Examples:**
- * ```typescript
- * // Plural-aware error
- * new TranslatableGenericError('component', 'errorKey', { count: 5 });
- * // Translation: \"{count, plural, one {# error} other {# errors}}\"
- *
- * // Gender-aware error
- * new TranslatableGenericError('component', 'userError', { gender: 'female', name: 'Alice' });
- * // Translation: \"{gender, select, male {He} female {She}} {name} caused an error\"
- *
- * // Number formatting
- * new TranslatableGenericError('component', 'thresholdError', { value: 1500.50, limit: 1000 });
- * // Translation: \"Value {value, number, currency} exceeds {limit, number, currency}\"
- *
- * // SelectOrdinal
- * new TranslatableGenericError('component', 'stepError', { step: 3 });
- * // Translation: \"Failed at {step, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} step\"
- * ```
- */
-export class TranslatableGenericError<
-  TStringKey extends string = string,
-> extends Error {
-  public readonly stringKey: TStringKey;
-  public override readonly componentId: string;
-  public readonly language?: string;
-  public readonly variables?: Record<string, string | number>;
-  public override 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?: string,
-    metadata?: Record<string, any>,
-    instanceKey?: string,
-  ) {
-    // Lazy initialization: getInstance() is only called when error is constructed
-    let translatedMessage: string;
-    try {
-      const engine = I18nEngine.getInstance(instanceKey);
-      translatedMessage = engine.safeTranslate(
-        componentId,
-        stringKey,
-        variables,
-        language,
-      );
-    } catch (error) {
-      // Fallback if engine not found - TranslatableGenericError is designed to be flexible
-      translatedMessage = `[${componentId}.${stringKey}]`;
-    }
-
-    super(translatedMessage);
-    this.name = 'TranslatableGenericError';
-    this.stringKey = stringKey;
-    this.componentId = componentId;
-    this.language = language;
-    this.variables = variables;
-    this.metadata = metadata;
-  }
-
-  /**
-   * Create error with explicit engine instance
-   */
-  static withEngine<TStringKey extends string>(
-    engine: I18nEngine,
-    componentId: string,
-    stringKey: TStringKey,
-    variables?: Record<string, string | number>,
-    language?: string,
-    metadata?: Record<string, any>,
-  ): TranslatableGenericError<TStringKey> {
-    const translatedMessage = engine.safeTranslate(
-      componentId,
-      stringKey,
-      variables,
-      language,
-    );
-
-    const error = Object.create(TranslatableGenericError.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: string, instanceKey?: string): string {
-    try {
-      const engine = I18nEngine.getInstance(instanceKey);
-      return engine.safeTranslate(
-        this.componentId,
-        this.stringKey,
-        this.variables,
-        language,
-      );
-    } catch (error) {
-      // Fallback if engine not found
-      return `[${this.componentId}.${this.stringKey}]`;
-    }
-  }
-
-  /**
-   * Create error with plural count
-   * Translation string should use ICU plural format
-   */
-  static withCount<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    count: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-  ): TranslatableGenericError<TStringKey> {
-    return new TranslatableGenericError(
-      componentId,
-      stringKey,
-      { ...otherVars, count },
-      language,
-      undefined,
-      instanceKey,
-    );
-  }
-
-  /**
-   * Create error with gender context
-   * Translation string should use ICU select format
-   */
-  static withGender<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    gender: GenderCategory,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-  ): TranslatableGenericError<TStringKey> {
-    return new TranslatableGenericError(
-      componentId,
-      stringKey,
-      { ...otherVars, gender },
-      language,
-      undefined,
-      instanceKey,
-    );
-  }
-
-  /**
-   * Create error with ordinal number
-   * Translation string should use ICU selectordinal format
-   */
-  static withOrdinal<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    ordinalNumber: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-  ): TranslatableGenericError<TStringKey> {
-    return new TranslatableGenericError(
-      componentId,
-      stringKey,
-      { ...otherVars, ordinalNumber },
-      language,
-      undefined,
-      instanceKey,
-    );
-  }
-
-  /**
-   * Create error with number formatting
-   * Translation string should use ICU number format
-   */
-  static withNumberFormat<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    value: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-  ): TranslatableGenericError<TStringKey> {
-    return new TranslatableGenericError(
-      componentId,
-      stringKey,
-      { ...otherVars, value },
-      language,
-      undefined,
-      instanceKey,
-    );
-  }
-
-  /**
-   * Create error with multiple i18n features combined
-   * Translation string can use nested ICU messages
-   */
-  static withMultipleFeatures<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    features: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-  ): TranslatableGenericError<TStringKey> {
-    return new TranslatableGenericError(
-      componentId,
-      stringKey,
-      features,
-      language,
-      undefined,
-      instanceKey,
-    );
-  }
-}

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

@@ -1,222 +0,0 @@
-import { IHandleable } from '../interfaces/handleable';
-import { TranslatableGenericError } from './translatable-generic';
-import { PluralCategory } from '../pluralization/plural-categories';
-import { GenderCategory } from '../gender/gender-categories';
-
-/**
- * Generic translatable handleable error with full i18n feature support.
- * 
- * Combines translation capabilities with handleable error patterns and provides
- * static factory methods for all i18n features.
- * 
- * **Supported i18n Features:**
- * - ICU MessageFormat: plural, select, selectordinal
- * - Pluralization: 37 languages with CLDR rules
- * - Gender support: male, female, neutral, other
- * - Number formatting: integer, currency, percent
- * - Nested messages: complex multi-level patterns
- * 
- * **Usage Examples:**
- * ```typescript
- * // Pluralization with handleable options
- * throw TranslatableHandleableGenericError.withCount(
- *   'api', 'validationError', 5,
- *   {}, 'en-US', 'default',
- *   { statusCode: 400 }
- * );
- * 
- * // Gender-aware messages
- * throw TranslatableHandleableGenericError.withGender(
- *   'user', 'accountError', 'female',
- *   {}, 'en-US', 'default',
- *   { statusCode: 403 }
- * );
- * 
- * // Number formatting with error handling
- * throw TranslatableHandleableGenericError.withNumberFormat(
- *   'payment', 'amountExceeded', 1599.99,
- *   { limit: 1000 }, 'en-US', 'default',
- *   { statusCode: 402 }
- * );
- * 
- * // Ordinal formatting (1st, 2nd, 3rd)
- * throw TranslatableHandleableGenericError.withOrdinal(
- *   'workflow', 'stepFailed', 3,
- *   {}, 'en-US', 'default',
- *   { statusCode: 500, retryable: true }
- * );
- * ```
- */
-export class TranslatableHandleableGenericError<
-    TStringKey extends string = string,
-  >
-  extends TranslatableGenericError<TStringKey>
-  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?: string,
-    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;
-    this.name = 'TranslatableHandleableGenericError';
-  }
-  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,
-    };
-  }
-
-  /**
-   * Create error with pluralization support
-   * Translation string should include: "{count, plural, one {...} other {...}}"
-   */
-  static override withCount<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    count: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
-  ): TranslatableHandleableGenericError<TStringKey> {
-    return new TranslatableHandleableGenericError(
-      componentId,
-      stringKey,
-      { count, ...otherVars },
-      language,
-      undefined,
-      instanceKey,
-      handleableOptions,
-    );
-  }
-
-  /**
-   * Create error with gender-aware messages
-   * Translation string should include: "{gender, select, male {...} female {...} other {...}}"
-   */
-  static override withGender<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    gender: GenderCategory,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
-  ): TranslatableHandleableGenericError<TStringKey> {
-    return new TranslatableHandleableGenericError(
-      componentId,
-      stringKey,
-      { gender, ...otherVars },
-      language,
-      undefined,
-      instanceKey,
-      handleableOptions,
-    );
-  }
-
-  /**
-   * Create error with ordinal formatting (1st, 2nd, 3rd)
-   * Translation string should include: "{number, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}"
-   */
-  static override withOrdinal<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    ordinalNumber: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
-  ): TranslatableHandleableGenericError<TStringKey> {
-    return new TranslatableHandleableGenericError(
-      componentId,
-      stringKey,
-      { number: ordinalNumber, ...otherVars },
-      language,
-      undefined,
-      instanceKey,
-      handleableOptions,
-    );
-  }
-
-  /**
-   * Create error with number formatting (currency, percent, integer)
-   * Translation string should include: "{value, number, integer}" or "{amount, number, currency}"
-   */
-  static override withNumberFormat<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    value: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
-  ): TranslatableHandleableGenericError<TStringKey> {
-    return new TranslatableHandleableGenericError(
-      componentId,
-      stringKey,
-      { value, ...otherVars },
-      language,
-      undefined,
-      instanceKey,
-      handleableOptions,
-    );
-  }
-
-  /**
-   * Create error with multiple i18n features combined
-   * Translation string can combine: plural, select, number formatting, etc.
-   */
-  static override withMultipleFeatures<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    features: Record<string, string | number>,
-    language?: string,
-    instanceKey?: string,
-    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
-  ): TranslatableHandleableGenericError<TStringKey> {
-    return new TranslatableHandleableGenericError(
-      componentId,
-      stringKey,
-      features,
-      language,
-      undefined,
-      instanceKey,
-      handleableOptions,
-    );
-  }
-}

package/src/errors/translatable.ts

@@ -1,138 +0,0 @@
-import { I18nEngine } from '../core/i18n-engine';
-import { GenderCategory } from '../gender/gender-categories';
-
-/**
- * Translatable error class with full i18n 3.0/3.5 feature support.
- *
- * Uses lazy initialization to avoid circular dependencies with core modules.
- * The I18nEngine is only accessed when the error is constructed, not at module load time.
- * If the i18n engine is not initialized, falls back to displaying the raw key.
- *
- * **Supported Features:**
- * - ICU MessageFormat (variables, plural, select, selectordinal)
- * - Pluralization (37 languages, CLDR rules)
- * - Gender-aware translations
- * - Number formatting (integer, currency, percent)
- * - Date/Time formatting
- * - Nested messages (4 levels deep)
- * - Context variables
- *
- * **Translation String Examples:**
- * ```typescript
- * // ICU plural
- * "{count, plural, one {# error occurred} other {# errors occurred}}"
- *
- * // ICU select + gender
- * "{gender, select, male {He encountered} female {She encountered}} an error"
- *
- * // Number formatting
- * "Threshold {limit, number, integer} exceeded by {value, number, percent}"
- *
- * // SelectOrdinal
- * "Failed at {step, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} step"
- *
- * // Nested messages
- * "{severity, select, low {Minor: {count, plural, one {# issue} other {# issues}}} high {Critical error}}"
- * ```
- */
-export class TranslatableError<
-  TStringKey extends string = string,
-> extends Error {
-  public override readonly componentId: string;
-  public readonly stringKey: TStringKey;
-  public readonly variables?: Record<string, string | number>;
-  public readonly language?: string;
-
-  constructor(
-    componentId: string,
-    stringKey: TStringKey,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-  ) {
-    // Lazy initialization: getInstance() is only called when error is constructed, not at module load
-    const engine = I18nEngine.getInstance('default');
-    super(engine.safeTranslate(componentId, stringKey, otherVars, language));
-    this.name = 'TranslatableError';
-    this.componentId = componentId;
-    this.stringKey = stringKey;
-    this.variables = otherVars;
-    this.language = language;
-    Object.setPrototypeOf(this, TranslatableError.prototype);
-  }
-
-  /**
-   * Create error with plural count
-   * Translation string should use: {count, plural, one {...} other {...}}
-   */
-  static withCount<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    count: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-  ): TranslatableError<TStringKey> {
-    return new TranslatableError(
-      componentId,
-      stringKey,
-      { count, ...otherVars },
-      language,
-    );
-  }
-
-  /**
-   * Create error with gender context
-   * Translation string should use: {gender, select, male {...} female {...} other {...}}
-   */
-  static withGender<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    gender: GenderCategory,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-  ): TranslatableError<TStringKey> {
-    return new TranslatableError(
-      componentId,
-      stringKey,
-      { gender, ...otherVars },
-      language,
-    );
-  }
-
-  /**
-   * Create error with ordinal number
-   * Translation string should use: {number, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
-   */
-  static withOrdinal<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    number: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-  ): TranslatableError<TStringKey> {
-    return new TranslatableError(
-      componentId,
-      stringKey,
-      { number, ...otherVars },
-      language,
-    );
-  }
-
-  /**
-   * Create error with formatted number
-   * Translation string should use: {value, number, integer|currency|percent}
-   */
-  static withNumber<TStringKey extends string>(
-    componentId: string,
-    stringKey: TStringKey,
-    value: number,
-    otherVars?: Record<string, string | number>,
-    language?: string,
-  ): TranslatableError<TStringKey> {
-    return new TranslatableError(
-      componentId,
-      stringKey,
-      { value, ...otherVars },
-      language,
-    );
-  }
-}