@digitaldefiance/i18n-lib 1.1.6 → 1.1.8

package/README.md

@@ -423,6 +423,95 @@ For complete documentation on the plugin architecture, see [PLUGIN_ARCHITECTURE.
 
 ## Advanced Features
 
+### Translatable Errors
+
+The `TranslatableGenericError` class provides a simple way to create errors with translated messages that work across any component:
+
+```typescript
+import { TranslatableGenericError, CoreStringKey, CoreLanguage } from '@digitaldefiance/i18n-lib';
+
+// Define your error string keys
+enum UserErrorKey {
+  UserNotFound = 'userNotFound',
+  InvalidCredentials = 'invalidCredentials',
+  AccountLocked = 'accountLocked',
+}
+
+// Register your component with translations
+const userErrorComponent = {
+  id: 'user-errors',
+  name: 'User Errors',
+  stringKeys: Object.values(UserErrorKey)
+};
+
+const registration = {
+  component: userErrorComponent,
+  strings: {
+    en: {
+      [UserErrorKey.UserNotFound]: 'User "{username}" not found',
+      [UserErrorKey.InvalidCredentials]: 'Invalid credentials provided',
+      [UserErrorKey.AccountLocked]: 'Account locked until {unlockTime}'
+    },
+    fr: {
+      [UserErrorKey.UserNotFound]: 'Utilisateur "{username}" introuvable',
+      [UserErrorKey.InvalidCredentials]: 'Identifiants invalides fournis',
+      [UserErrorKey.AccountLocked]: 'Compte verrouillé jusqu\'à {unlockTime}'
+    }
+  }
+};
+
+i18n.registerComponent(registration);
+
+// Throw translatable errors
+throw new TranslatableGenericError(
+  'user-errors',
+  UserErrorKey.UserNotFound,
+  { username: 'john_doe' },
+  'en',
+  { userId: 123 }, // metadata
+  'myapp' // engine instance key
+);
+
+// Use with explicit engine instance
+const error = TranslatableGenericError.withEngine(
+  i18n,
+  'user-errors',
+  UserErrorKey.InvalidCredentials,
+  undefined,
+  'fr'
+);
+
+// Retranslate errors dynamically
+try {
+  // ... code that throws TranslatableGenericError
+} catch (error) {
+  if (error instanceof TranslatableGenericError) {
+    const localizedMessage = error.retranslate(userLanguage, 'myapp');
+    sendToUser(localizedMessage);
+  }
+}
+
+// Use with core strings
+throw new TranslatableGenericError(
+  'core',
+  CoreStringKey.Error_AccessDenied,
+  undefined,
+  CoreLanguage.EnglishUS,
+  { requestId: '12345' },
+  'myapp'
+);
+```
+
+**Key Features:**
+- Works with any registered component and string keys
+- Uses `safeTranslate` for consistent fallback behavior (`[componentId.stringKey]`)
+- Stores error context: stringKey, componentId, language, variables, metadata
+- Supports dynamic retranslation with `retranslate()` method
+- Never throws during construction - always returns a valid error
+- Compatible with both constructor and static factory methods
+
+For complete documentation, see [TRANSLATABLE_ERROR_GUIDE.md](./TRANSLATABLE_ERROR_GUIDE.md).
+
 ### Enum Translation Registry
 
 ```typescript
@@ -937,6 +1026,33 @@ Part of the DigitalBurnbag project - a secure file sharing and automated protoco
 
 ## ChangeLog
 
+### Version 1.1.8
+
+- Wed Oct 15 2025 16:43:00 GMT-0700 (Pacific Daylight Time)
+  - Fix to translatable prototype inheritance
+
+### Version 1.1.7
+
+- Wed Oct 15 2025 16:13:00 GMT-0700 (Pacific Daylight Time)
+  **Fixed:**
+  - Corrected safeCoreTranslation fallback format to use 
+    ```plaintext
+    [CoreStringKey.${stringKey}]
+    ```
+  - Fixed import issues with DefaultInstanceKey
+  **Added:**
+    - New TranslatableGenericError class for generic translatable errors across any component
+    - CoreI18nComponentId constant export
+    - 130+ new tests for comprehensive coverage
+    - Complete usage documentation
+  **Changed:**
+    - Standardized all fallback formats to use square brackets 
+    ```plaintext
+    [componentId.stringKey]
+    ```
+    - Refactored to use CoreI18nComponentId constant
+  All tests pass and backward compatibility is maintained.
+
 ### Version 1.1.6
 
 - Tue Oct 14 2025 17:04:00 GMT-0700 (Pacific Daylight Time)

package/dist/core-i18n.d.ts

@@ -11,6 +11,7 @@ import { PluginI18nEngine } from './plugin-i18n-engine';
  * Create default language definitions
  */
 export declare function createDefaultLanguages(): LanguageDefinition[];
+export declare const CoreI18nComponentId = "core";
 /**
  * Core component definition
  */

package/dist/core-i18n.js

@@ -3,7 +3,7 @@
  * Core I18n component with default languages and system strings
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CoreComponentDefinition = void 0;
+exports.CoreComponentDefinition = exports.CoreI18nComponentId = void 0;
 exports.createDefaultLanguages = createDefaultLanguages;
 exports.createCoreComponentStrings = createCoreComponentStrings;
 exports.createCoreComponentRegistration = createCoreComponentRegistration;
@@ -15,6 +15,7 @@ const core_string_key_1 = require("./core-string-key");
 const language_registry_1 = require("./language-registry");
 const plugin_i18n_engine_1 = require("./plugin-i18n-engine");
 const strict_types_1 = require("./strict-types");
+const DefaultInstanceKey = 'default';
 /**
  * Create default language definitions
  */
@@ -63,11 +64,12 @@ function createDefaultLanguages() {
         },
     ]);
 }
+exports.CoreI18nComponentId = 'core';
 /**
  * Core component definition
  */
 exports.CoreComponentDefinition = {
-    id: 'core',
+    id: exports.CoreI18nComponentId,
     name: 'Core I18n System',
     stringKeys: Object.values(core_string_key_1.CoreStringKey),
 };
@@ -418,7 +420,7 @@ function createCoreComponentRegistration() {
 /**
  * Create a pre-configured I18n engine with core components
  */
-function createCoreI18nEngine(instanceKey = 'default') {
+function createCoreI18nEngine(instanceKey = DefaultInstanceKey) {
     const languages = createDefaultLanguages();
     const engine = plugin_i18n_engine_1.PluginI18nEngine.createInstance(instanceKey, languages);
     engine.registerComponent(createCoreComponentRegistration());
@@ -429,7 +431,7 @@ function createCoreI18nEngine(instanceKey = 'default') {
  */
 function getCoreTranslation(stringKey, variables, language, instanceKey) {
     const engine = plugin_i18n_engine_1.PluginI18nEngine.getInstance(instanceKey);
-    return engine.translate('core', stringKey, variables, language);
+    return engine.translate(exports.CoreI18nComponentId, stringKey, variables, language);
 }
 /**
  * Helper function to safely get core translation with fallback
@@ -439,6 +441,6 @@ function safeCoreTranslation(stringKey, variables, language, instanceKey) {
         return getCoreTranslation(stringKey, variables, language, instanceKey);
     }
     catch {
-        return `[core.${stringKey}]`;
+        return `[CoreStringKey.${stringKey}]`;
     }
 }

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from './i18n-engine';
 export * from './language-definition';
 export * from './template';
 export * from './timezone';
+export * from './translatable-generic-error';
 export * from './typed-error';
 export * from './types';
 export * from './utils';

package/dist/index.js

@@ -37,6 +37,7 @@ __exportStar(require("./i18n-engine"), exports);
 __exportStar(require("./language-definition"), exports);
 __exportStar(require("./template"), exports);
 __exportStar(require("./timezone"), exports);
+__exportStar(require("./translatable-generic-error"), exports);
 __exportStar(require("./typed-error"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./utils"), exports);

package/dist/translatable-generic-error.d.ts

@@ -0,0 +1,29 @@
+import { PluginI18nEngine } from './plugin-i18n-engine';
+/**
+ * Generic translatable error that works with any plugin engine and component
+ */
+export declare class TranslatableGenericError<TStringKey extends string = string, TLanguage extends string = string> extends Error {
+    readonly stringKey: TStringKey;
+    readonly componentId: string;
+    readonly language?: TLanguage;
+    readonly variables?: Record<string, string | number>;
+    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);
+    /**
+     * 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>): TranslatableGenericError<TStringKey, TLanguage>;
+    /**
+     * Retranslate the error message in a different language
+     */
+    retranslate(language: TLanguage, instanceKey?: string): string;
+}

package/dist/translatable-generic-error.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranslatableGenericError = void 0;
+const plugin_i18n_engine_1 = require("./plugin-i18n-engine");
+/**
+ * Generic translatable error that works with any plugin engine and component
+ */
+class TranslatableGenericError extends Error {
+    /**
+     * 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, stringKey, variables, language, metadata, instanceKey) {
+        let translatedMessage;
+        try {
+            const engine = plugin_i18n_engine_1.PluginI18nEngine.getInstance(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
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Create error with explicit engine instance
+     */
+    static withEngine(engine, componentId, stringKey, variables, language, metadata) {
+        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, instanceKey) {
+        try {
+            const engine = plugin_i18n_engine_1.PluginI18nEngine.getInstance(instanceKey);
+            return engine.safeTranslate(this.componentId, this.stringKey, this.variables, language);
+        }
+        catch (error) {
+            return `[${this.componentId}.${this.stringKey}]`;
+        }
+    }
+}
+exports.TranslatableGenericError = TranslatableGenericError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",