@digitaldefiance/i18n-lib 3.7.5 → 3.8.1

package/src/core/context-manager.ts

@@ -0,0 +1,113 @@
+/**
+ * Interface representing the translation context for an I18nEngine instance.
+ */
+export interface Context {
+  /** Current user-facing language code. */
+  language: string;
+  /** Current administrative language code. */
+  adminLanguage: string;
+  /** Active context space: 'admin' or 'user'. */
+  currentSpace: 'admin' | 'user';
+}
+
+/**
+ * ContextManager handles creation and management of per-instance translation contexts,
+ * including separate user and admin languages and context switching.
+ */
+export class ContextManager {
+  private contexts = new Map<string, Context>();
+
+  /**
+   * Creates a new context for a given instance key with a default language.
+   *
+   * @param instanceKey Unique identifier for the context instance.
+   * @param defaultLanguage Language code to initialize both user and admin contexts.
+   * @returns The newly created Context object.
+   */
+  create(instanceKey: string, defaultLanguage: string): Context {
+    const context: Context = {
+      language: defaultLanguage,
+      adminLanguage: defaultLanguage,
+      currentSpace: 'user',
+    };
+    this.contexts.set(instanceKey, context);
+    return context;
+  }
+
+  /**
+   * Retrieves the context for a given instance key.
+   *
+   * @param instanceKey Unique identifier for the context instance.
+   * @returns The Context object associated with the key.
+   * @throws {Error} If no context exists for the provided key.
+   */
+  get(instanceKey: string): Context {
+    const context = this.contexts.get(instanceKey);
+    if (!context) {
+      throw new Error(`Context '${instanceKey}' not found`);
+    }
+    return context;
+  }
+
+  /**
+   * Sets the user-facing language for the specified context.
+   *
+   * @param instanceKey Unique identifier for the context instance.
+   * @param language New language code for user-facing translations.
+   */
+  setLanguage(instanceKey: string, language: string): void {
+    const context = this.get(instanceKey);
+    context.language = language;
+  }
+
+  /**
+   * Sets the administrative language for the specified context.
+   *
+   * @param instanceKey Unique identifier for the context instance.
+   * @param language New language code for administrative translations.
+   */
+  setAdminLanguage(instanceKey: string, language: string): void {
+    const context = this.get(instanceKey);
+    context.adminLanguage = language;
+  }
+
+  /**
+   * Switches the active context space to 'admin'.
+   *
+   * @param instanceKey Unique identifier for the context instance.
+   */
+  switchToAdmin(instanceKey: string): void {
+    const context = this.get(instanceKey);
+    context.currentSpace = 'admin';
+  }
+
+  /**
+   * Switches the active context space to 'user'.
+   *
+   * @param instanceKey Unique identifier for the context instance.
+   */
+  switchToUser(instanceKey: string): void {
+    const context = this.get(instanceKey);
+    context.currentSpace = 'user';
+  }
+
+  /**
+   * Retrieves the currently active language based on the context space.
+   *
+   * @param instanceKey Unique identifier for the context instance.
+   * @returns The active language code ('adminLanguage' or 'language').
+   */
+  getCurrentLanguage(instanceKey: string): string {
+    const context = this.get(instanceKey);
+    return context.currentSpace === 'admin'
+      ? context.adminLanguage
+      : context.language;
+  }
+
+  /**
+   * Clears all stored contexts, removing all instance data.
+   */
+  clear(): void {
+    this.contexts.clear();
+  }
+}

package/src/core/enum-registry.ts

@@ -0,0 +1,106 @@
+/**
+ * Enum translation registry (v2 - no generics)
+ */
+
+import { I18nError } from '../errors/i18n-error';
+
+/**
+ * Registry for managing translations of enum values across multiple languages.
+ * Provides a centralized way to register and translate enum values.
+ */
+export class EnumRegistry {
+  private translations = new Map<any, Record<string, Record<string, string>>>();
+  private enumNames = new WeakMap<any, string>();
+  private translateFn?: (key: string, vars?: Record<string, any>) => string;
+
+  /**
+   * Creates a new EnumRegistry instance.
+   * @param translateFn - Optional translation function for error messages
+   */
+  constructor(
+    translateFn?: (key: string, vars?: Record<string, any>) => string,
+  ) {
+    this.translateFn = translateFn;
+  }
+
+  /**
+   * Registers an enum with its translations for all languages.
+   * @template TEnum - The enum value type (string or number)
+   * @param enumObj - The enum object to register
+   * @param translations - Mapping of language codes to enum value translations
+   * @param enumName - Human-readable name for the enum (used in error messages)
+   */
+  register<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    translations: Record<string, Record<string, string>>,
+    enumName: string,
+  ): void {
+    this.translations.set(enumObj, translations);
+    this.enumNames.set(enumObj, enumName);
+  }
+
+  /**
+   * Translates an enum value to a specific language.
+   * @template TEnum - The enum value type
+   * @param enumObj - The registered enum object
+   * @param value - The enum value to translate
+   * @param language - The target language code
+   * @returns The translated string
+   * @throws {I18nError} If the enum, language, or value is not found
+   */
+  translate<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    value: TEnum,
+    language: string,
+  ): string {
+    const translations = this.translations.get(enumObj);
+    if (!translations) {
+      throw I18nError.invalidConfig(
+        `No translations found for enum: ${this.getEnumName(enumObj)}`,
+      );
+    }
+
+    const langTranslations = translations[language];
+    if (!langTranslations) {
+      throw I18nError.languageNotFound(language);
+    }
+
+    // Convert value to string for lookup
+    const valueKey = String(value);
+    let result = langTranslations[valueKey];
+
+    // For numeric enums, also try the reverse mapping (string key to value)
+    if (!result && typeof value === 'number') {
+      const stringKey = Object.keys(enumObj).find(
+        (key) => enumObj[key] === value,
+      );
+      if (stringKey) {
+        result = langTranslations[stringKey];
+      }
+    }
+
+    if (!result) {
+      throw I18nError.translationMissing('enum', String(value), language);
+    }
+
+    return result;
+  }
+
+  /**
+   * Checks if an enum has been registered.
+   * @param enumObj - The enum object to check
+   * @returns True if the enum is registered, false otherwise
+   */
+  has(enumObj: any): boolean {
+    return this.translations.has(enumObj);
+  }
+
+  /**
+   * Gets the human-readable name of an enum.
+   * @param enumObj - The enum object
+   * @returns The enum name or 'UnknownEnum' if not set
+   */
+  private getEnumName(enumObj: any): string {
+    return this.enumNames.get(enumObj) || 'UnknownEnum';
+  }
+}