@digitaldefiance/i18n-lib 1.3.1 → 1.3.3

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,6 +2274,14 @@ For issues, questions, or contributions:
 
 ## ChangeLog
 
+### Version 1.3.3
+
+- Make LanguageRegistry static
+
+### Version 1.3.2
+
+- Add functionality to Language Registry for getMatchingLanguageCode
+
 ### Version 1.3.1
 
 - **Changed**: `CoreLanguageCode` is now `string` - Language Registry is single source of truth

package/dist/language-registry.d.ts

@@ -3,85 +3,92 @@
  */
 import { LanguageDefinition } from './language-definition';
 /**
- * Registry for managing supported languages
+ * Static singleton registry for managing supported languages globally
  */
-export declare class LanguageRegistry<TLanguages extends string> {
-    private readonly languages;
-    private readonly languagesByCodes;
-    private defaultLanguageId;
-    constructor();
+export declare class LanguageRegistry {
+    private static languages;
+    private static languagesByCodes;
+    private static defaultLanguageId;
+    private constructor();
     /**
      * Register a new language
      */
-    registerLanguage(language: LanguageDefinition): void;
+    static registerLanguage(language: LanguageDefinition): void;
     /**
      * Register multiple languages at once
      */
-    registerLanguages(languages: readonly LanguageDefinition[]): void;
+    static registerLanguages(languages: readonly LanguageDefinition[]): void;
     /**
      * Get a language by its ID
      */
-    getLanguage(languageId: TLanguages): LanguageDefinition | undefined;
+    static getLanguage(languageId: string): LanguageDefinition | undefined;
     /**
      * Get a language by its code
      */
-    getLanguageByCode(code: string): LanguageDefinition | undefined;
+    static getLanguageByCode(code: string): LanguageDefinition | undefined;
     /**
      * Get all registered languages
      */
-    getAllLanguages(): ReadonlyArray<LanguageDefinition>;
+    static getAllLanguages(): ReadonlyArray<LanguageDefinition>;
     /**
      * Get all language IDs
      */
-    getLanguageIds(): readonly TLanguages[];
+    static getLanguageIds(): readonly string[];
     /**
      * Get all language codes
      */
-    getLanguageCodes(): readonly string[];
+    static getLanguageCodes(): readonly string[];
     /**
      * Check if a language is registered
      */
-    hasLanguage(languageId: TLanguages): boolean;
+    static hasLanguage(languageId: string): boolean;
     /**
      * Check if a language code is registered
      */
-    hasLanguageCode(code: string): boolean;
+    static hasLanguageCode(code: string): boolean;
     /**
      * Get the default language
      */
-    getDefaultLanguage(): LanguageDefinition | null;
+    static getDefaultLanguage(): LanguageDefinition | null;
     /**
      * Get the default language ID
      */
-    getDefaultLanguageId(): TLanguages | null;
+    static getDefaultLanguageId(): string | null;
+    /**
+     * Get matching language code with fallback logic:
+     * 1. Try requested code
+     * 2. Fall back to user default
+     * 3. Fall back to site default
+     */
+    static getMatchingLanguageCode(requestedCode?: string, userDefaultCode?: string): string;
     /**
      * Set the default language
      */
-    setDefaultLanguage(languageId: TLanguages): void;
+    static setDefaultLanguage(languageId: string): void;
     /**
      * Get the number of registered languages
      */
-    getLanguageCount(): number;
+    static getLanguageCount(): number;
     /**
      * Validate that all required languages are present
      */
-    validateRequiredLanguages(requiredLanguages: readonly TLanguages[]): LanguageValidationResult;
+    static validateRequiredLanguages(requiredLanguages: readonly string[]): LanguageValidationResult;
     /**
      * Create a mapping of language IDs to their display names
      */
-    getLanguageDisplayNames(): Record<TLanguages, string>;
+    static getLanguageDisplayNames(): Record<string, string>;
     /**
      * Create a mapping of language IDs to their codes
      */
-    getLanguageCodeMapping(): Record<TLanguages, string>;
+    static getLanguageCodeMapping(): Record<string, string>;
     /**
      * Find languages by partial name match (case-insensitive)
      */
-    findLanguagesByName(partialName: string): readonly LanguageDefinition[];
+    static findLanguagesByName(partialName: string): readonly LanguageDefinition[];
     /**
-     * Clear all registered languages
+     * Clear all registered languages (useful for testing)
      */
-    clear(): void;
+    static clear(): void;
 }
 /**
  * Validation result for language operations

package/dist/language-registry.js

@@ -9,125 +9,144 @@ exports.createLanguageDefinitions = createLanguageDefinitions;
 const registry_error_1 = require("./registry-error");
 const registry_error_type_1 = require("./registry-error-type");
 /**
- * Registry for managing supported languages
+ * Static singleton registry for managing supported languages globally
  */
 class LanguageRegistry {
     constructor() {
-        this.languages = new Map();
-        this.languagesByCodes = new Map();
-        this.defaultLanguageId = null;
-        // Empty constructor - languages are registered via registerLanguage method
+        // Private constructor - use static methods
     }
     /**
      * Register a new language
      */
-    registerLanguage(language) {
+    static registerLanguage(language) {
         const languageId = language.id;
         // Check for duplicate language ID
-        if (this.languages.has(languageId)) {
+        if (LanguageRegistry.languages.has(languageId)) {
             throw registry_error_1.RegistryError.createSimple(registry_error_type_1.RegistryErrorType.DuplicateLanguage, `Language '${languageId}' is already registered`, { languageId });
         }
         // Check for duplicate language code
-        if (this.languagesByCodes.has(language.code)) {
-            const existingLanguageId = this.languagesByCodes.get(language.code);
+        if (LanguageRegistry.languagesByCodes.has(language.code)) {
+            const existingLanguageId = LanguageRegistry.languagesByCodes.get(language.code);
             throw registry_error_1.RegistryError.createSimple(registry_error_type_1.RegistryErrorType.DuplicateLanguage, `Language code '${language.code}' is already used by language '${existingLanguageId}'`, { languageId, code: language.code, existingLanguageId });
         }
         // Register the language
-        this.languages.set(languageId, language);
-        this.languagesByCodes.set(language.code, languageId);
+        LanguageRegistry.languages.set(languageId, language);
+        LanguageRegistry.languagesByCodes.set(language.code, languageId);
         // Set as default if specified or if it's the first language
-        if (language.isDefault || this.defaultLanguageId === null) {
-            this.defaultLanguageId = languageId;
+        if (language.isDefault || LanguageRegistry.defaultLanguageId === null) {
+            LanguageRegistry.defaultLanguageId = languageId;
         }
     }
     /**
      * Register multiple languages at once
      */
-    registerLanguages(languages) {
+    static registerLanguages(languages) {
         for (const language of languages) {
-            this.registerLanguage(language);
+            LanguageRegistry.registerLanguage(language);
         }
     }
     /**
      * Get a language by its ID
      */
-    getLanguage(languageId) {
-        return this.languages.get(languageId);
+    static getLanguage(languageId) {
+        return LanguageRegistry.languages.get(languageId);
     }
     /**
      * Get a language by its code
      */
-    getLanguageByCode(code) {
-        const languageId = this.languagesByCodes.get(code);
-        return languageId ? this.languages.get(languageId) : undefined;
+    static getLanguageByCode(code) {
+        const languageId = LanguageRegistry.languagesByCodes.get(code);
+        return languageId ? LanguageRegistry.languages.get(languageId) : undefined;
     }
     /**
      * Get all registered languages
      */
-    getAllLanguages() {
-        return Array.from(this.languages.values());
+    static getAllLanguages() {
+        return Array.from(LanguageRegistry.languages.values());
     }
     /**
      * Get all language IDs
      */
-    getLanguageIds() {
-        return Array.from(this.languages.keys());
+    static getLanguageIds() {
+        return Array.from(LanguageRegistry.languages.keys());
     }
     /**
      * Get all language codes
      */
-    getLanguageCodes() {
-        return Array.from(this.languagesByCodes.keys());
+    static getLanguageCodes() {
+        return Array.from(LanguageRegistry.languagesByCodes.keys());
     }
     /**
      * Check if a language is registered
      */
-    hasLanguage(languageId) {
-        return this.languages.has(languageId);
+    static hasLanguage(languageId) {
+        return LanguageRegistry.languages.has(languageId);
     }
     /**
      * Check if a language code is registered
      */
-    hasLanguageCode(code) {
-        return this.languagesByCodes.has(code);
+    static hasLanguageCode(code) {
+        return LanguageRegistry.languagesByCodes.has(code);
     }
     /**
      * Get the default language
      */
-    getDefaultLanguage() {
-        return this.defaultLanguageId
-            ? this.languages.get(this.defaultLanguageId) || null
+    static getDefaultLanguage() {
+        return LanguageRegistry.defaultLanguageId
+            ? LanguageRegistry.languages.get(LanguageRegistry.defaultLanguageId) || null
             : null;
     }
     /**
      * Get the default language ID
      */
-    getDefaultLanguageId() {
-        return this.defaultLanguageId;
+    static getDefaultLanguageId() {
+        return LanguageRegistry.defaultLanguageId;
+    }
+    /**
+     * Get matching language code with fallback logic:
+     * 1. Try requested code
+     * 2. Fall back to user default
+     * 3. Fall back to site default
+     */
+    static getMatchingLanguageCode(requestedCode, userDefaultCode) {
+        // Try requested code first
+        if (requestedCode && LanguageRegistry.hasLanguageCode(requestedCode)) {
+            return requestedCode;
+        }
+        // Try user default
+        if (userDefaultCode && LanguageRegistry.hasLanguageCode(userDefaultCode)) {
+            return userDefaultCode;
+        }
+        // Fall back to site default
+        const defaultLanguage = LanguageRegistry.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
      */
-    setDefaultLanguage(languageId) {
-        if (!this.languages.has(languageId)) {
+    static setDefaultLanguage(languageId) {
+        if (!LanguageRegistry.languages.has(languageId)) {
             throw registry_error_1.RegistryError.createSimple(registry_error_type_1.RegistryErrorType.LanguageNotFound, `Language '${languageId}' not found`, { languageId });
         }
-        this.defaultLanguageId = languageId;
+        LanguageRegistry.defaultLanguageId = languageId;
     }
     /**
      * Get the number of registered languages
      */
-    getLanguageCount() {
-        return this.languages.size;
+    static getLanguageCount() {
+        return LanguageRegistry.languages.size;
     }
     /**
      * Validate that all required languages are present
      */
-    validateRequiredLanguages(requiredLanguages) {
+    static validateRequiredLanguages(requiredLanguages) {
         const missingLanguages = [];
         const errors = [];
         for (const languageId of requiredLanguages) {
-            if (!this.languages.has(languageId)) {
+            if (!LanguageRegistry.languages.has(languageId)) {
                 missingLanguages.push(languageId);
                 errors.push(`Required language '${languageId}' is not registered`);
             }
@@ -141,9 +160,9 @@ class LanguageRegistry {
     /**
      * Create a mapping of language IDs to their display names
      */
-    getLanguageDisplayNames() {
+    static getLanguageDisplayNames() {
         const result = {};
-        for (const [languageId, language] of this.languages) {
+        for (const [languageId, language] of LanguageRegistry.languages) {
             result[languageId] = language.name;
         }
         return result;
@@ -151,9 +170,9 @@ class LanguageRegistry {
     /**
      * Create a mapping of language IDs to their codes
      */
-    getLanguageCodeMapping() {
+    static getLanguageCodeMapping() {
         const result = {};
-        for (const [languageId, language] of this.languages) {
+        for (const [languageId, language] of LanguageRegistry.languages) {
             result[languageId] = language.code;
         }
         return result;
@@ -161,20 +180,23 @@ class LanguageRegistry {
     /**
      * Find languages by partial name match (case-insensitive)
      */
-    findLanguagesByName(partialName) {
+    static findLanguagesByName(partialName) {
         const searchTerm = partialName.toLowerCase();
-        return Array.from(this.languages.values()).filter((language) => language.name.toLowerCase().includes(searchTerm));
+        return Array.from(LanguageRegistry.languages.values()).filter((language) => language.name.toLowerCase().includes(searchTerm));
     }
     /**
-     * Clear all registered languages
+     * Clear all registered languages (useful for testing)
      */
-    clear() {
-        this.languages.clear();
-        this.languagesByCodes.clear();
-        this.defaultLanguageId = null;
+    static clear() {
+        LanguageRegistry.languages.clear();
+        LanguageRegistry.languagesByCodes.clear();
+        LanguageRegistry.defaultLanguageId = null;
     }
 }
 exports.LanguageRegistry = LanguageRegistry;
+LanguageRegistry.languages = new Map();
+LanguageRegistry.languagesByCodes = new Map();
+LanguageRegistry.defaultLanguageId = null;
 /**
  * Helper function to create language definitions with type safety
  */

package/dist/plugin-i18n-engine.d.ts

@@ -7,7 +7,6 @@ import { ComponentRegistry } from './component-registry';
 import { EnumTranslationRegistry } from './enum-registry';
 import { IActiveContext } from './active-context';
 import { LanguageDefinition } from './language-definition';
-import { LanguageRegistry } from './language-registry';
 import { RegistryConfig } from './registry-config';
 import { TranslationResponse } from './translation-response';
 import { EnumLanguageTranslation } from './types';
@@ -15,7 +14,6 @@ import { EnumLanguageTranslation } from './types';
  * Plugin-based I18n Engine with registration capabilities
  */
 export declare class PluginI18nEngine<TLanguages extends string> {
-    private readonly languageRegistry;
     private readonly componentRegistry;
     private readonly enumRegistry;
     private readonly config;
@@ -40,11 +38,11 @@ export declare class PluginI18nEngine<TLanguages extends string> {
      */
     static getInstance<TLangs extends string>(key?: string): PluginI18nEngine<TLangs>;
     /**
-     * Register a new language
+     * Register a new language (updates static registry)
      */
     registerLanguage(language: LanguageDefinition): void;
     /**
-     * Register multiple languages
+     * Register multiple languages (updates static registry)
      */
     registerLanguages(languages: readonly LanguageDefinition[]): void;
     /**
@@ -92,7 +90,7 @@ export declare class PluginI18nEngine<TLanguages extends string> {
      */
     setLanguage(language: TLanguages): void;
     /**
-     * Get available languages
+     * Get available languages from static registry
      */
     getLanguages(): readonly LanguageDefinition[];
     /**
@@ -104,17 +102,13 @@ export declare class PluginI18nEngine<TLanguages extends string> {
      */
     hasComponent(componentId: string): boolean;
     /**
-     * Check if a language is registered
+     * Check if a language is registered in static registry
      */
     hasLanguage(language: TLanguages): boolean;
     /**
-     * Get language by code
+     * Get language by code from static registry
      */
     getLanguageByCode(code: string): LanguageDefinition | undefined;
-    /**
-     * Get language registry for direct access
-     */
-    getLanguageRegistry(): LanguageRegistry<TLanguages>;
     /**
      * Get component registry for direct access
      */

package/dist/plugin-i18n-engine.js

@@ -36,12 +36,15 @@ class PluginI18nEngine {
             },
             ...config,
         };
-        // Initialize registries
-        this.languageRegistry = new language_registry_1.LanguageRegistry();
+        // Register initial languages in static registry (skip if already registered)
+        for (const lang of initialLanguages) {
+            if (!language_registry_1.LanguageRegistry.hasLanguage(lang.id)) {
+                language_registry_1.LanguageRegistry.registerLanguage(lang);
+            }
+        }
+        // Initialize component registry (per-instance)
         this.componentRegistry = new component_registry_1.ComponentRegistry(initialLanguages.map((l) => l.id), this.config.validation);
         this.enumRegistry = new enum_registry_1.EnumTranslationRegistry(initialLanguages.map((l) => l.id), (key, vars) => this.safeTranslate('core', key, vars));
-        // Register initial languages
-        this.languageRegistry.registerLanguages(initialLanguages);
         // Initialize context key for this engine instance
         this.contextKey = PluginI18nEngine.DefaultInstanceKey;
         // Create or get the global context for this engine
@@ -113,16 +116,16 @@ class PluginI18nEngine {
         return instance;
     }
     /**
-     * Register a new language
+     * Register a new language (updates static registry)
      */
     registerLanguage(language) {
-        this.languageRegistry.registerLanguage(language);
+        language_registry_1.LanguageRegistry.registerLanguage(language);
         // Update component registry with new language
-        const newLanguages = this.languageRegistry.getLanguageIds();
+        const newLanguages = language_registry_1.LanguageRegistry.getLanguageIds();
         this.componentRegistry.updateRegisteredLanguages(newLanguages);
     }
     /**
-     * Register multiple languages
+     * Register multiple languages (updates static registry)
      */
     registerLanguages(languages) {
         for (const language of languages) {
@@ -226,17 +229,17 @@ class PluginI18nEngine {
      * Set current language
      */
     setLanguage(language) {
-        if (!this.languageRegistry.hasLanguage(language)) {
+        if (!language_registry_1.LanguageRegistry.hasLanguage(language)) {
             throw registry_error_1.RegistryError.createSimple(registry_error_type_1.RegistryErrorType.LanguageNotFound, `Language '${language}' is not registered`, { language });
         }
         const globalContext = global_active_context_1.GlobalActiveContext.getInstance();
         globalContext.setUserLanguage(language, this.contextKey);
     }
     /**
-     * Get available languages
+     * Get available languages from static registry
      */
     getLanguages() {
-        return this.languageRegistry.getAllLanguages();
+        return language_registry_1.LanguageRegistry.getAllLanguages();
     }
     /**
      * Get registered components
@@ -251,22 +254,16 @@ class PluginI18nEngine {
         return this.componentRegistry.hasComponent(componentId);
     }
     /**
-     * Check if a language is registered
+     * Check if a language is registered in static registry
      */
     hasLanguage(language) {
-        return this.languageRegistry.hasLanguage(language);
+        return language_registry_1.LanguageRegistry.hasLanguage(language);
     }
     /**
-     * Get language by code
+     * Get language by code from static registry
      */
     getLanguageByCode(code) {
-        return this.languageRegistry.getLanguageByCode(code);
-    }
-    /**
-     * Get language registry for direct access
-     */
-    getLanguageRegistry() {
-        return this.languageRegistry;
+        return language_registry_1.LanguageRegistry.getLanguageByCode(code);
     }
     /**
      * Get component registry for direct access
@@ -288,7 +285,7 @@ class PluginI18nEngine {
         const warnings = [];
         let isValid = true;
         const components = this.getComponents();
-        const languages = this.languageRegistry.getLanguageIds();
+        const languages = language_registry_1.LanguageRegistry.getLanguageIds();
         for (const component of components) {
             const componentStrings = this.componentRegistry.getComponentStrings(component.id);
             if (!componentStrings) {
@@ -355,6 +352,7 @@ class PluginI18nEngine {
         }
         PluginI18nEngine._instances.clear();
         PluginI18nEngine._defaultKey = null;
+        language_registry_1.LanguageRegistry.clear();
     }
 }
 exports.PluginI18nEngine = PluginI18nEngine;

package/package.json

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