@digitaldefiance/i18n-lib 1.3.0 → 1.3.2

package/README.md

@@ -234,6 +234,17 @@ const displayNames = registry.getLanguageDisplayNames();
 // Get language codes for Mongoose enum
 const languageCodes = registry.getLanguageIds(); // ['en-US', 'fr', 'es']
 const isoCodes = registry.getLanguageCodes(); // ['en-US', 'fr', 'es']
+
+// Get matching language code with fallback logic
+const matchedCode = registry.getMatchingLanguageCode(
+  'de-DE',      // Requested code (not registered)
+  'fr',         // User default (registered)
+  // Falls back to site default if neither match
+);
+// Returns: 'fr' (user default)
+
+const defaultCode = registry.getMatchingLanguageCode();
+// Returns: 'en-US' (site default)
 ```
 
 **Key Features:**
@@ -243,6 +254,53 @@ const isoCodes = registry.getLanguageCodes(); // ['en-US', 'fr', 'es']
 - Default language management
 - Duplicate detection and validation
 - Extract language codes for schema definitions
+- Intelligent language code matching with fallback chain
+
+### Language Code Resolution
+
+The Language Registry provides intelligent language code matching with a fallback chain for handling user preferences and browser language headers:
+
+```typescript
+import { LanguageRegistry } from '@digitaldefiance/i18n-lib';
+
+const registry = new LanguageRegistry<'en-US' | 'fr' | 'es'>();
+registry.registerLanguages([
+  createLanguageDefinition('en-US', 'English (US)', 'en-US', true),
+  createLanguageDefinition('fr', 'Français', 'fr'),
+  createLanguageDefinition('es', 'Español', 'es'),
+]);
+
+// Fallback chain: requested → user default → site default
+const languageCode = registry.getMatchingLanguageCode(
+  req.headers['accept-language'],  // 1. Try requested code first
+  req.user?.siteLanguage,           // 2. Fall back to user default
+  // 3. Falls back to site default if neither match
+);
+
+// Example scenarios:
+registry.getMatchingLanguageCode('fr', 'es');      // Returns: 'fr' (requested exists)
+registry.getMatchingLanguageCode('de', 'es');      // Returns: 'es' (user default exists)
+registry.getMatchingLanguageCode('de', 'it');      // Returns: 'en-US' (site default)
+registry.getMatchingLanguageCode();                // Returns: 'en-US' (site default)
+registry.getMatchingLanguageCode('', '');          // Returns: 'en-US' (empty strings ignored)
+```
+
+**Use Cases:**
+- HTTP Accept-Language header processing
+- User preference resolution
+- Browser language detection with fallback
+- Multi-tenant applications with per-user defaults
+
+**Error Handling:**
+```typescript
+try {
+  const emptyRegistry = new LanguageRegistry();
+  emptyRegistry.getMatchingLanguageCode('en-US');
+} catch (error) {
+  // Throws RegistryError if no default language configured
+  console.error('No default language configured');
+}
+```
 
 ### Enum Translation Registry
 
@@ -1391,6 +1449,7 @@ The core component provides 40+ system strings organized by category:
 - `hasLanguage(language)` - Check if language exists
 - `setLanguage(language)` - Set current language
 - `getLanguageByCode(code)` - Get language by ISO code
+- `getMatchingLanguageCode(requestedCode?, userDefaultCode?)` - Get matching language code with fallback logic
 
 **Validation**
 
@@ -2215,16 +2274,20 @@ For issues, questions, or contributions:
 
 ## ChangeLog
 
-### Version 1.3.0
+### Version 1.3.2
+
+- Add functionality to Language Registry for getMatchingLanguageCode
+
+### Version 1.3.1
 
-- **Changed**: `CoreLanguageCode` now derived from `LanguageCodes` for type safety
-  - Type: `typeof LanguageCodes[keyof typeof LanguageCodes]`
-  - Maintains compile-time type safety while using registry as single source
-  - No breaking changes - existing code continues to work
+- **Changed**: `CoreLanguageCode` is now `string` - Language Registry is single source of truth
+  - Use `engine.getLanguageRegistry().getLanguageIds()` for runtime validation
+  - Use `getCoreLanguageCodes()` for static arrays (Mongoose schemas, etc.)
+  - Runtime validation via registry, not compile-time types
 - **Added**: `getCoreLanguageCodes()` - Get core language codes as runtime array
 - **Added**: `getCoreLanguageDefinitions()` - Get core language definitions
-- **Improved**: Language Registry is now the single source of truth
-- **Benefit**: Type safety + runtime flexibility without duplication
+- **Philosophy**: Registry-based validation over hardcoded types
+- **Benefit**: Maximum flexibility - add languages without code changes
 
 ### Version 1.2.5
 

package/dist/core-i18n.d.ts

@@ -8,10 +8,16 @@ import { LanguageCodes } from './language-codes';
 import { LanguageDefinition } from './language-definition';
 import { PluginI18nEngine } from './plugin-i18n-engine';
 /**
- * Core language code type - derived from LanguageCodes for type safety
- * Use this for type parameters when you want to restrict to core languages only
+ * Core language code type - union of supported language codes
+ * Provides compile-time type safety for core languages
+ * For custom languages, extend this type or use string
  */
 export type CoreLanguageCode = typeof LanguageCodes[keyof typeof LanguageCodes];
+/**
+ * Flexible language code type - use when you want runtime-only validation
+ * Alias for string to indicate it's a language code
+ */
+export type FlexibleLanguageCode = string;
 /**
  * Create default language definitions
  */
@@ -24,11 +30,11 @@ export declare const CoreComponentDefinition: ComponentDefinition<CoreStringKey>
 /**
  * Core component strings for all default languages
  */
-export declare function createCoreComponentStrings(): import("./strict-types").CompleteComponentLanguageStrings<CoreStringKey, CoreLanguageCode>;
+export declare function createCoreComponentStrings(): import("./strict-types").CompleteComponentLanguageStrings<CoreStringKey, string>;
 /**
  * Create core component registration
  */
-export declare function createCoreComponentRegistration(): ComponentRegistration<CoreStringKey, CoreLanguageCode>;
+export declare function createCoreComponentRegistration(): ComponentRegistration<CoreStringKey, string>;
 /**
  * Get core language codes as array (for Mongoose enums, etc.)
  */
@@ -39,17 +45,18 @@ export declare function getCoreLanguageCodes(): string[];
 export declare function getCoreLanguageDefinitions(): LanguageDefinition[];
 /**
  * Create a pre-configured I18n engine with core components
+ * Returns engine with string type - use registry for language validation
  */
-export declare function createCoreI18nEngine(instanceKey?: string): PluginI18nEngine<CoreLanguageCode>;
+export declare function createCoreI18nEngine(instanceKey?: string): PluginI18nEngine<string>;
 /**
  * Type alias for easier usage
  */
-export type CoreI18nEngine = PluginI18nEngine<CoreLanguageCode>;
+export type CoreI18nEngine = PluginI18nEngine<string>;
 /**
  * Helper function to get core translation
  */
-export declare function getCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: CoreLanguageCode, instanceKey?: string): string;
+export declare function getCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: string, instanceKey?: string): string;
 /**
  * Helper function to safely get core translation with fallback
  */
-export declare function safeCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: CoreLanguageCode, instanceKey?: string): string;
+export declare function safeCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: string, instanceKey?: string): string;

package/dist/core-i18n.js

@@ -449,6 +449,7 @@ function getCoreLanguageDefinitions() {
 }
 /**
  * Create a pre-configured I18n engine with core components
+ * Returns engine with string type - use registry for language validation
  */
 function createCoreI18nEngine(instanceKey = DefaultInstanceKey) {
     const languages = createDefaultLanguages();

package/dist/language-registry.d.ts

@@ -54,6 +54,13 @@ export declare class LanguageRegistry<TLanguages extends string> {
      * Get the default language ID
      */
     getDefaultLanguageId(): TLanguages | null;
+    /**
+     * Get matching language code with fallback logic:
+     * 1. Try requested code
+     * 2. Fall back to user default
+     * 3. Fall back to site default
+     */
+    getMatchingLanguageCode(requestedCode?: string, userDefaultCode?: string): string;
     /**
      * Set the default language
      */

package/dist/language-registry.js

@@ -105,6 +105,28 @@ class LanguageRegistry {
     getDefaultLanguageId() {
         return this.defaultLanguageId;
     }
+    /**
+     * Get matching language code with fallback logic:
+     * 1. Try requested code
+     * 2. Fall back to user default
+     * 3. Fall back to site default
+     */
+    getMatchingLanguageCode(requestedCode, userDefaultCode) {
+        // Try requested code first
+        if (requestedCode && this.hasLanguageCode(requestedCode)) {
+            return requestedCode;
+        }
+        // Try user default
+        if (userDefaultCode && this.hasLanguageCode(userDefaultCode)) {
+            return userDefaultCode;
+        }
+        // Fall back to site default
+        const defaultLanguage = this.getDefaultLanguage();
+        if (!defaultLanguage) {
+            throw registry_error_1.RegistryError.createSimple(registry_error_type_1.RegistryErrorType.LanguageNotFound, 'No default language configured', {});
+        }
+        return defaultLanguage.code;
+    }
     /**
      * Set the default language
      */

package/dist/registry-error.d.ts

@@ -1,4 +1,3 @@
-import { CoreLanguageCode } from './core-i18n';
 import { RegistryErrorType } from './registry-error-type';
 import { TranslationEngine } from './typed-error';
 /**
@@ -11,7 +10,7 @@ export declare class RegistryError extends Error {
     /**
      * Create a registry error with translation support
      */
-    static createWithEngine(engine: TranslationEngine, type: RegistryErrorType, variables?: Record<string, string | number>, language?: CoreLanguageCode, metadata?: Record<string, any>): RegistryError;
+    static createWithEngine(engine: TranslationEngine, type: RegistryErrorType, variables?: Record<string, string | number>, language?: string, metadata?: Record<string, any>): RegistryError;
     /**
      * Create a simple RegistryError without engine dependency
      */

package/dist/registry-error.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegistryError = void 0;
+// CoreLanguageCode is deprecated - using string
 const core_string_key_1 = require("./core-string-key");
 const registry_error_type_1 = require("./registry-error-type");
 const typed_error_1 = require("./typed-error");

package/dist/typed-error.d.ts

@@ -1,6 +1,5 @@
 import { Language, StringKey } from './default-config';
 import { I18nEngine } from './i18n-engine';
-import { CoreLanguageCode } from './core-i18n';
 import { CoreStringKey } from './core-string-key';
 import { PluginI18nEngine } from './plugin-i18n-engine';
 import { TranslationEngine } from './translation-engine';
@@ -52,9 +51,9 @@ export declare abstract class PluginTypedError<TEnum extends Record<string, stri
 export declare abstract class CoreTypedError<TEnum extends Record<string, string>> extends Error {
     readonly type: TEnum[keyof TEnum];
     readonly reasonMap: CompleteReasonMap<TEnum, CoreStringKey>;
-    readonly language?: CoreLanguageCode | undefined;
+    readonly language?: string | undefined;
     readonly otherVars?: Record<string, string | number> | undefined;
-    constructor(engine: PluginI18nEngine<CoreLanguageCode>, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, CoreStringKey>, language?: CoreLanguageCode | undefined, otherVars?: Record<string, string | number> | undefined);
+    constructor(engine: PluginI18nEngine<string>, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, CoreStringKey>, language?: string | undefined, otherVars?: Record<string, string | number> | undefined);
 }
 /**
  * Helper function to create a plugin-based TypedError with automatic engine detection
@@ -63,7 +62,7 @@ export declare function createPluginTypedError<TEnum extends Record<string, stri
 /**
  * Helper function to create a core system TypedError with automatic engine detection
  */
-export declare function createCoreTypedError<TEnum extends Record<string, string>>(type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, CoreStringKey>, otherVars?: Record<string, string | number>, language?: CoreLanguageCode, instanceKey?: string): Error;
+export declare function createCoreTypedError<TEnum extends Record<string, string>>(type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, CoreStringKey>, otherVars?: Record<string, string | number>, language?: string, instanceKey?: string): Error;
 /**
  * Create a simple error with translation support (generalized pattern from RegistryError)
  */

package/dist/typed-error.js

@@ -6,6 +6,8 @@ exports.createCoreTypedError = createCoreTypedError;
 exports.createTranslatedError = createTranslatedError;
 // Legacy imports (for backward compatibility)
 const default_config_1 = require("./default-config");
+// New plugin architecture imports
+// CoreLanguageCode is deprecated - using string for flexibility
 const core_string_key_1 = require("./core-string-key");
 const plugin_i18n_engine_1 = require("./plugin-i18n-engine");
 /**
@@ -187,7 +189,7 @@ class DatabaseError extends CoreTypedError<typeof DatabaseErrorType> {
 }
 
 // Usage:
-// const engine = PluginI18nEngine.getInstance<CoreLanguageCode>();
+// const engine = PluginI18nEngine.getInstance<string>();
 // throw new DatabaseError(engine, DatabaseErrorType.ConnectionFailed);
 */
 // Example 2: Custom component error with custom strings
@@ -210,19 +212,19 @@ const userErrorReasonMap: CompleteReasonMap<typeof UserErrorType, UserErrorStrin
   [UserErrorType.AccountLocked]: UserErrorStringKey.AccountLockedMessage
 };
 
-class UserError extends PluginTypedError<typeof UserErrorType, UserErrorStringKey, CoreLanguageCode> {
+class UserError extends PluginTypedError<typeof UserErrorType, UserErrorStringKey, string> {
   constructor(
-    engine: PluginI18nEngine<CoreLanguageCode>,
+    engine: PluginI18nEngine<string>,
     type: UserErrorType,
     otherVars?: Record<string, string | number>,
-    language?: CoreLanguageCode
+    language?: string
   ) {
     super(engine, 'user-system', type, userErrorReasonMap, language, otherVars);
   }
 }
 
 // Usage:
-// const engine = PluginI18nEngine.getInstance<CoreLanguageCode>();
+// const engine = PluginI18nEngine.getInstance<string>();
 // throw new UserError(engine, UserErrorType.UserNotFound, { username: 'john_doe' });
 */
 // Example 3: Using helper functions for simpler error creation

package/package.json

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