@digitaldefiance/i18n-lib 1.1.10 → 1.2.1

package/README.md

@@ -49,38 +49,36 @@ npm install @digitaldefiance/i18n-lib
 ```typescript
 import { I18nEngine, I18nConfig, createContext, CurrencyCode, Timezone } from '@digitaldefiance/i18n-lib';
 
-// Define your enums
+// Define your string keys
 enum MyStrings {
   Welcome = 'welcome',
   UserGreetingTemplate = 'userGreetingTemplate'
 }
 
-enum MyLanguages {
-  English = 'English',
-  Spanish = 'Spanish'
-}
+// Define your language codes (or use string literals)
+type MyLanguages = 'en-US' | 'es';
 
 // Configure the engine
 const config: I18nConfig<MyStrings, MyLanguages> = {
   stringNames: Object.values(MyStrings),
   strings: {
-    [MyLanguages.English]: {
+    'en-US': {
       [MyStrings.Welcome]: 'Welcome!',
       [MyStrings.UserGreetingTemplate]: 'Hello, {name}!'
     },
-    [MyLanguages.Spanish]: {
+    'es': {
       [MyStrings.Welcome]: '¡Bienvenido!',
       [MyStrings.UserGreetingTemplate]: '¡Hola, {name}!'
     }
   },
-  defaultLanguage: MyLanguages.English,
+  defaultLanguage: 'en-US',
   defaultTranslationContext: 'user',
   defaultCurrencyCode: new CurrencyCode('USD'),
   languageCodes: {
-    [MyLanguages.English]: 'en',
-    [MyLanguages.Spanish]: 'es'
+    'en-US': 'en-US',
+    'es': 'es'
   },
-  languages: Object.values(MyLanguages),
+  languages: ['en-US', 'es'],
   timezone: new Timezone('UTC'),
   adminTimezone: new Timezone('UTC')
 };
@@ -96,7 +94,7 @@ const greeting = i18n.translate(MyStrings.UserGreetingTemplate, { name: 'John' }
 // "Hello, John!"
 
 // Change language
-i18n.context = { language: MyLanguages.Spanish };
+i18n.context = { language: 'es' };
 const spanishGreeting = i18n.translate(MyStrings.UserGreetingTemplate, { name: 'Juan' });
 // "¡Hola, Juan!"
 ```
@@ -111,7 +109,8 @@ The new plugin-based architecture provides a component registration system with
 import { 
   createCoreI18nEngine, 
   CoreStringKey, 
-  CoreLanguage,
+  CoreLanguageCode,
+  LanguageCodes,
   ComponentDefinition,
   ComponentRegistration
 } from '@digitaldefiance/i18n-lib';
@@ -138,26 +137,26 @@ const MyComponent: ComponentDefinition<MyComponentStringKey> = {
 
 // Define translations for all supported languages
 const myComponentStrings = {
-  [CoreLanguage.EnglishUS]: {
+  [LanguageCodes.EN_US]: {
     [MyComponentStringKey.Welcome]: 'Welcome to my component!',
     [MyComponentStringKey.Goodbye]: 'Goodbye from my component!',
     [MyComponentStringKey.UserGreetingTemplate]: 'Hello, {name}!'
   },
-  [CoreLanguage.French]: {
+  [LanguageCodes.FR]: {
     [MyComponentStringKey.Welcome]: 'Bienvenue dans mon composant !',
     [MyComponentStringKey.Goodbye]: 'Au revoir de mon composant !',
     [MyComponentStringKey.UserGreetingTemplate]: 'Bonjour, {name} !'
   },
-  [CoreLanguage.Spanish]: {
+  [LanguageCodes.ES]: {
     [MyComponentStringKey.Welcome]: '¡Bienvenido a mi componente!',
     [MyComponentStringKey.Goodbye]: '¡Adiós desde mi componente!',
     [MyComponentStringKey.UserGreetingTemplate]: '¡Hola, {name}!'
   }
-  // TypeScript ensures all CoreLanguages are handled
+  // TypeScript ensures all language codes are handled
 };
 
 // Register component (with validation)
-const registration: ComponentRegistration<MyComponentStringKey, CoreLanguage> = {
+const registration: ComponentRegistration<MyComponentStringKey, CoreLanguageCode> = {
   component: MyComponent,
   strings: myComponentStrings
 };
@@ -174,7 +173,7 @@ const greeting = i18n.translate('my-component', MyComponentStringKey.UserGreetin
 });
 
 // Change language - affects all components
-i18n.setLanguage(CoreLanguage.French);
+i18n.setLanguage(LanguageCodes.FR);
 const frenchWelcome = i18n.translate('my-component', MyComponentStringKey.Welcome);
 // "Bienvenue dans mon composant !"
 ```
@@ -199,6 +198,17 @@ Provides essential system strings in 8 languages:
 
 - English (US/UK), French, Spanish, German, Chinese (Simplified), Japanese, Ukrainian
 
+**Language Codes**: Use `LanguageCodes` constants or define your own:
+```typescript
+import { LanguageCodes } from '@digitaldefiance/i18n-lib';
+
+// Common codes provided
+LanguageCodes.EN_US  // 'en-US'
+LanguageCodes.FR     // 'fr'
+LanguageCodes.ES     // 'es'
+// ... or use any string: 'custom-lang'
+```
+
 ```typescript
 import { createCoreI18nEngine, CoreStringKey } from '@digitaldefiance/i18n-lib';
 
@@ -207,23 +217,44 @@ const saveText = i18n.translate('core', CoreStringKey.Common_Save);
 const errorMsg = i18n.translate('core', CoreStringKey.Error_ValidationFailed);
 ```
 
-#### User System Component (Example)
+#### Custom Component Example
 
-Demonstrates user management strings:
+Create your own component with translations:
 
 ```typescript
 import { 
-  registerUserSystemComponent, 
-  getUserTranslation, 
-  UserStringKey 
+  ComponentDefinition,
+  ComponentRegistration,
+  LanguageCodes
 } from '@digitaldefiance/i18n-lib';
 
-// Register user system with existing engine
-registerUserSystemComponent(i18n);
+enum UserStringKey {
+  Auth_Login = 'auth_login',
+  Error_UserNotFoundTemplate = 'error_user_not_found_template'
+}
 
-// Use user system translations
-const loginText = getUserTranslation(UserStringKey.Auth_Login);
-const userNotFound = getUserTranslation(
+const userComponent: ComponentDefinition<UserStringKey> = {
+  id: 'user-system',
+  name: 'User System',
+  stringKeys: Object.values(UserStringKey)
+};
+
+const registration: ComponentRegistration<UserStringKey, CoreLanguageCode> = {
+  component: userComponent,
+  strings: {
+    [LanguageCodes.EN_US]: {
+      [UserStringKey.Auth_Login]: 'Login',
+      [UserStringKey.Error_UserNotFoundTemplate]: 'User "{username}" not found'
+    }
+  }
+};
+
+i18n.registerComponent(registration);
+
+// Use translations
+const loginText = i18n.translate('user-system', UserStringKey.Auth_Login);
+const userNotFound = i18n.translate(
+  'user-system',
   UserStringKey.Error_UserNotFoundTemplate, 
   { username: 'john_doe' }
 );
@@ -299,18 +330,18 @@ const myComponent: ComponentDefinition<MyStrings> = {
 };
 
 // System has EN, FR, ES languages - component must provide translations for all three
-const registration: ComponentRegistration<MyStrings, CoreLanguage> = {
+const registration: ComponentRegistration<MyStrings, CoreLanguageCode> = {
   component: myComponent,
   strings: {
-    [CoreLanguage.EnglishUS]: {
+    [LanguageCodes.EN_US]: {
       [MyStrings.Welcome]: 'Welcome',
       [MyStrings.Goodbye]: 'Goodbye'
     },
-    [CoreLanguage.French]: {
+    [LanguageCodes.FR]: {
       [MyStrings.Welcome]: 'Bienvenue',
       [MyStrings.Goodbye]: 'Au revoir'
     },
-    [CoreLanguage.Spanish]: {
+    [LanguageCodes.ES]: {
       [MyStrings.Welcome]: 'Bienvenido', 
       [MyStrings.Goodbye]: 'Adiós'
     }
@@ -333,9 +364,9 @@ Components can support different subsets of system languages:
 const componentA = {
   component: { id: 'comp-a', name: 'Component A', stringKeys: ['hello'] },
   strings: {
-    en: { hello: 'Hello' },
-    fr: { hello: 'Bonjour' },
-    es: { hello: 'Hola' }
+    'en-US': { hello: 'Hello' },
+    'fr': { hello: 'Bonjour' },
+    'es': { hello: 'Hola' }
   }
 };
 
@@ -343,8 +374,8 @@ const componentA = {
 const componentB = {
   component: { id: 'comp-b', name: 'Component B', stringKeys: ['save'] },
   strings: {
-    en: { save: 'Save' },
-    de: { save: 'Speichern' }
+    'en-US': { save: 'Save' },
+    'de': { save: 'Speichern' }
   }
 };
 
@@ -353,23 +384,25 @@ i18n.registerComponent(componentA); // ✓ Complete
 i18n.registerComponent(componentB); // ⚠ Missing FR, ES - uses fallback
 
 // Usage automatically handles fallbacks
-i18n.translate('comp-b', 'save', {}, 'fr'); // Returns 'Save' (EN fallback)
+i18n.translate('comp-b', 'save', {}, 'fr'); // Returns 'Save' (en-US fallback)
 ```
 
 #### Dynamic Language Addition
 
 ```typescript
+import { createLanguageDefinition } from '@digitaldefiance/i18n-lib';
+
 // Add new language to system
-const germanLang = { id: 'de', name: 'German', code: 'de' };
+const germanLang = createLanguageDefinition('de', 'Deutsch', 'de');
 i18n.registerLanguage(germanLang);
 
 // New component registrations now require German translations
 const newRegistration = {
   component: { id: 'new-comp', name: 'New Component', stringKeys: ['test'] },
   strings: {
-    en: { test: 'Test' },
-    fr: { test: 'Test' },
-    es: { test: 'Prueba' }
+    'en-US': { test: 'Test' },
+    'fr': { test: 'Test' },
+    'es': { test: 'Prueba' }
     // Missing 'de' - validation will flag this
   }
 };
@@ -402,7 +435,7 @@ const strictEngine = new PluginI18nEngine(languages, {
   validation: {
     requireCompleteStrings: true,
     allowPartialRegistration: false,
-    fallbackLanguageId: 'en'
+    fallbackLanguageId: 'en-US'
   }
 });
 ```
@@ -428,7 +461,7 @@ For complete documentation on the plugin architecture, see [PLUGIN_ARCHITECTURE.
 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';
+import { TranslatableGenericError, CoreStringKey, LanguageCodes } from '@digitaldefiance/i18n-lib';
 
 // Define your error string keys
 enum UserErrorKey {
@@ -447,12 +480,12 @@ const userErrorComponent = {
 const registration = {
   component: userErrorComponent,
   strings: {
-    en: {
+    'en-US': {
       [UserErrorKey.UserNotFound]: 'User "{username}" not found',
       [UserErrorKey.InvalidCredentials]: 'Invalid credentials provided',
       [UserErrorKey.AccountLocked]: 'Account locked until {unlockTime}'
     },
-    fr: {
+    'fr': {
       [UserErrorKey.UserNotFound]: 'Utilisateur "{username}" introuvable',
       [UserErrorKey.InvalidCredentials]: 'Identifiants invalides fournis',
       [UserErrorKey.AccountLocked]: 'Compte verrouillé jusqu\'à {unlockTime}'
@@ -467,7 +500,7 @@ throw new TranslatableGenericError(
   'user-errors',
   UserErrorKey.UserNotFound,
   { username: 'john_doe' },
-  'en',
+  'en-US',
   { userId: 123 }, // metadata
   'myapp' // engine instance key
 );
@@ -496,7 +529,7 @@ throw new TranslatableGenericError(
   'core',
   CoreStringKey.Error_AccessDenied,
   undefined,
-  CoreLanguage.EnglishUS,
+  LanguageCodes.EN_US,
   { requestId: '12345' },
   'myapp'
 );
@@ -1026,6 +1059,51 @@ Part of the DigitalBurnbag project - a secure file sharing and automated protoco
 
 ## ChangeLog
 
+### Version 1.2.1
+
+- Thu Oct 23 2025 15:10:00 GMT-0700 (Pacific Daylight Time)
+  - Update README
+
+### Version 1.2.0
+
+- Thu Oct 23 2025 14:13:00 GMT-0700 (Pacific Daylight Time)
+
+#### Breaking Changes
+- **Removed `CoreLanguage` enum** - Replaced with `CoreLanguageCode` type and `LanguageCodes` constants
+- **Language identifiers now use BCP 47 codes** - Changed from descriptive names (e.g., `'English (US)'`) to standard codes (e.g., `'en-US'`)
+- **API changes**:
+  - `CoreLanguage` → `CoreLanguageCode` (union type)
+  - `DefaultLanguage` enum → `DefaultLanguageCode` type
+  - All language references updated to use `LanguageCodes` constants
+
+#### Added
+- **`LanguageCodes` constants object** - Provides standard BCP 47 language codes:
+  - `EN_US`, `EN_GB`, `FR`, `ES`, `DE`, `ZH_CN`, `JA`, `UK`
+- **`LanguageDisplayNames` mapping** - Maps language codes to human-readable names
+- **`CommonLanguageCode` type** - Type for built-in language codes
+- **`LanguageCode` type** - Generic string type for custom language codes
+- **Custom language code support** - Any string can now be used as a language code
+
+#### Changed
+- **Language code format** - All language identifiers now use BCP 47 standard (e.g., `'en-US'` instead of `'English (US)'`)
+- **Type system** - Languages are now string-based types instead of enums, allowing custom language codes
+- **Documentation** - Updated README with new API usage examples and language code constants
+
+#### Migration Guide
+```typescript
+// Before (v1.1.x)
+import { CoreLanguage } from '@digitaldefiance/i18n-lib';
+i18n.setLanguage(CoreLanguage.French);
+
+// After
+import { LanguageCodes } from '@digitaldefiance/i18n-lib';
+i18n.setLanguage(LanguageCodes.FR);
+
+// Extending with custom language codes
+type MyLanguageCodes = CoreLanguageCode | 'pt-BR' | 'it';
+const myEngine = PluginI18nEngine.createInstance<MyLanguageCodes>('custom', languages);
+```
+
 ### Version 1.1.10
 
 - Fri Oct 17 2025 15:02:00 GMT-0700 (Pacific Daylight Time)

package/dist/core-i18n.d.ts

@@ -3,10 +3,11 @@
  */
 import { ComponentDefinition } from './component-definition';
 import { ComponentRegistration } from './component-registration';
-import { CoreLanguage } from './core-language';
 import { CoreStringKey } from './core-string-key';
+import { LanguageCodes } from './language-codes';
 import { LanguageDefinition } from './language-definition';
 import { PluginI18nEngine } from './plugin-i18n-engine';
+export type CoreLanguageCode = typeof LanguageCodes.EN_US | typeof LanguageCodes.EN_GB | typeof LanguageCodes.FR | typeof LanguageCodes.ES | typeof LanguageCodes.DE | typeof LanguageCodes.ZH_CN | typeof LanguageCodes.JA | typeof LanguageCodes.UK;
 /**
  * Create default language definitions
  */
@@ -19,24 +20,24 @@ export declare const CoreComponentDefinition: ComponentDefinition<CoreStringKey>
 /**
  * Core component strings for all default languages
  */
-export declare function createCoreComponentStrings(): import("./strict-types").CompleteComponentLanguageStrings<CoreStringKey, CoreLanguage>;
+export declare function createCoreComponentStrings(): import("./strict-types").CompleteComponentLanguageStrings<CoreStringKey, CoreLanguageCode>;
 /**
  * Create core component registration
  */
-export declare function createCoreComponentRegistration(): ComponentRegistration<CoreStringKey, CoreLanguage>;
+export declare function createCoreComponentRegistration(): ComponentRegistration<CoreStringKey, CoreLanguageCode>;
 /**
  * Create a pre-configured I18n engine with core components
  */
-export declare function createCoreI18nEngine(instanceKey?: string): PluginI18nEngine<CoreLanguage>;
+export declare function createCoreI18nEngine(instanceKey?: string): PluginI18nEngine<CoreLanguageCode>;
 /**
  * Type alias for easier usage
  */
-export type CoreI18nEngine = PluginI18nEngine<CoreLanguage>;
+export type CoreI18nEngine = PluginI18nEngine<CoreLanguageCode>;
 /**
  * Helper function to get core translation
  */
-export declare function getCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: CoreLanguage, instanceKey?: string): string;
+export declare function getCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: CoreLanguageCode, instanceKey?: string): string;
 /**
  * Helper function to safely get core translation with fallback
  */
-export declare function safeCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: CoreLanguage, instanceKey?: string): string;
+export declare function safeCoreTranslation(stringKey: CoreStringKey, variables?: Record<string, string | number>, language?: CoreLanguageCode, instanceKey?: string): string;

package/dist/core-i18n.js

@@ -10,8 +10,8 @@ exports.createCoreComponentRegistration = createCoreComponentRegistration;
 exports.createCoreI18nEngine = createCoreI18nEngine;
 exports.getCoreTranslation = getCoreTranslation;
 exports.safeCoreTranslation = safeCoreTranslation;
-const core_language_1 = require("./core-language");
 const core_string_key_1 = require("./core-string-key");
+const language_codes_1 = require("./language-codes");
 const language_registry_1 = require("./language-registry");
 const plugin_i18n_engine_1 = require("./plugin-i18n-engine");
 const strict_types_1 = require("./strict-types");
@@ -22,43 +22,43 @@ const DefaultInstanceKey = 'default';
 function createDefaultLanguages() {
     return (0, language_registry_1.createLanguageDefinitions)([
         {
-            id: core_language_1.CoreLanguage.EnglishUS,
+            id: language_codes_1.LanguageCodes.EN_US,
             name: 'English (US)',
             code: 'en-US',
             isDefault: true,
         },
         {
-            id: core_language_1.CoreLanguage.EnglishUK,
+            id: language_codes_1.LanguageCodes.EN_GB,
             name: 'English (UK)',
             code: 'en-GB',
         },
         {
-            id: core_language_1.CoreLanguage.French,
+            id: language_codes_1.LanguageCodes.FR,
             name: 'Français',
             code: 'fr',
         },
         {
-            id: core_language_1.CoreLanguage.Spanish,
+            id: language_codes_1.LanguageCodes.ES,
             name: 'Español',
             code: 'es',
         },
         {
-            id: core_language_1.CoreLanguage.German,
+            id: language_codes_1.LanguageCodes.DE,
             name: 'Deutsch',
             code: 'de',
         },
         {
-            id: core_language_1.CoreLanguage.MandarinChinese,
+            id: language_codes_1.LanguageCodes.ZH_CN,
             name: '中文 (简体)',
             code: 'zh-CN',
         },
         {
-            id: core_language_1.CoreLanguage.Japanese,
+            id: language_codes_1.LanguageCodes.JA,
             name: '日本語',
             code: 'ja',
         },
         {
-            id: core_language_1.CoreLanguage.Ukrainian,
+            id: language_codes_1.LanguageCodes.UK,
             name: 'Українська',
             code: 'uk',
         },
@@ -78,7 +78,7 @@ exports.CoreComponentDefinition = {
  */
 function createCoreComponentStrings() {
     return (0, strict_types_1.createCompleteComponentStrings)({
-        [core_language_1.CoreLanguage.EnglishUS]: {
+        [language_codes_1.LanguageCodes.EN_US]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: 'Yes',
             [core_string_key_1.CoreStringKey.Common_No]: 'No',
@@ -121,7 +121,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: 'Operation completed successfully',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: 'No data available',
         },
-        [core_language_1.CoreLanguage.EnglishUK]: {
+        [language_codes_1.LanguageCodes.EN_GB]: {
             // Common/General (mostly same as US English)
             [core_string_key_1.CoreStringKey.Common_Yes]: 'Yes',
             [core_string_key_1.CoreStringKey.Common_No]: 'No',
@@ -164,7 +164,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: 'Operation completed successfully',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: 'No data available',
         },
-        [core_language_1.CoreLanguage.French]: {
+        [language_codes_1.LanguageCodes.FR]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: 'Oui',
             [core_string_key_1.CoreStringKey.Common_No]: 'Non',
@@ -207,7 +207,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: 'Opération terminée avec succès',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: 'Aucune donnée disponible',
         },
-        [core_language_1.CoreLanguage.Spanish]: {
+        [language_codes_1.LanguageCodes.ES]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: 'Sí',
             [core_string_key_1.CoreStringKey.Common_No]: 'No',
@@ -250,7 +250,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: 'Operación completada exitosamente',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: 'No hay datos disponibles',
         },
-        [core_language_1.CoreLanguage.German]: {
+        [language_codes_1.LanguageCodes.DE]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: 'Ja',
             [core_string_key_1.CoreStringKey.Common_No]: 'Nein',
@@ -293,7 +293,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: 'Vorgang erfolgreich abgeschlossen',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: 'Keine Daten verfügbar',
         },
-        [core_language_1.CoreLanguage.MandarinChinese]: {
+        [language_codes_1.LanguageCodes.ZH_CN]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: '是',
             [core_string_key_1.CoreStringKey.Common_No]: '否',
@@ -336,7 +336,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: '操作成功完成',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: '无可用数据',
         },
-        [core_language_1.CoreLanguage.Japanese]: {
+        [language_codes_1.LanguageCodes.JA]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: 'はい',
             [core_string_key_1.CoreStringKey.Common_No]: 'いいえ',
@@ -379,7 +379,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: '操作が正常に完了しました',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: '利用可能なデータがありません',
         },
-        [core_language_1.CoreLanguage.Ukrainian]: {
+        [language_codes_1.LanguageCodes.UK]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: 'Так',
             [core_string_key_1.CoreStringKey.Common_No]: 'Ні',

package/dist/default-config.d.ts

@@ -1,5 +1,6 @@
 import { I18nContext } from './i18n-context';
 import { I18nEngine } from './i18n-engine';
+import { LanguageCodes } from './language-codes';
 import { Timezone } from './timezone';
 import { LanguageCodeCollection } from './types';
 export declare enum DefaultStringKey {
@@ -11,21 +12,14 @@ export declare enum DefaultStringKey {
     Error_DefaultLanguageNoCollectionTemplate = "error_defaultLanguageNoCollectionTemplate",
     Error_MissingTranslationKeyTemplate = "error_missingTranslationKeyTemplate"
 }
-export declare enum DefaultLanguage {
-    EnglishUS = "English (US)",
-    EnglishUK = "English (UK)",
-    French = "Fran\u00E7ais",
-    MandarinChinese = "\u4E2D\u6587",
-    Spanish = "Espa\u00F1ol",
-    Ukrainian = "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0438\u0439"
-}
-export declare const DefaultLanguageCodes: LanguageCodeCollection<DefaultLanguage>;
+export type DefaultLanguageCode = typeof LanguageCodes.EN_US | typeof LanguageCodes.EN_GB | typeof LanguageCodes.FR | typeof LanguageCodes.ES | typeof LanguageCodes.ZH_CN | typeof LanguageCodes.UK;
+export declare const DefaultLanguageCodes: LanguageCodeCollection<DefaultLanguageCode>;
 declare global {
     namespace I18n {
         interface Config {
             StringKey: DefaultStringKey;
-            Language: DefaultLanguage;
-            LanguageCodes: LanguageCodeCollection<DefaultLanguage>;
+            Language: DefaultLanguageCode;
+            LanguageCodes: LanguageCodeCollection<DefaultLanguageCode>;
             engine: I18nEngine<I18n.Config['StringKey'], I18n.Config['Language'], Record<any, any>, string>;
         }
     }
@@ -33,6 +27,6 @@ declare global {
 export type StringKey = I18n.Config['StringKey'];
 export type Language = I18n.Config['Language'];
 export type Engine = I18n.Config['engine'];
-export type LanguageCodes = I18n.Config['LanguageCodes'];
+export type DefaultLanguageCodesType = I18n.Config['LanguageCodes'];
 export declare const getI18nEngine: () => Engine;
-export declare const getDefaultI18nEngine: <TConstants extends Record<string, any>, TTranslationContext extends string, TContext extends I18nContext<DefaultLanguage, TTranslationContext>>(constants: TConstants, timezone?: Timezone, adminTimezone?: Timezone) => I18nEngine<DefaultStringKey, DefaultLanguage, TConstants, TTranslationContext, TContext>;
+export declare const getDefaultI18nEngine: <TConstants extends Record<string, any>, TTranslationContext extends string, TContext extends I18nContext<DefaultLanguageCode, TTranslationContext>>(constants: TConstants, timezone?: Timezone, adminTimezone?: Timezone) => I18nEngine<DefaultStringKey, DefaultLanguageCode, TConstants, TTranslationContext, TContext>;

package/dist/default-config.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDefaultI18nEngine = exports.getI18nEngine = exports.DefaultLanguageCodes = exports.DefaultLanguage = exports.DefaultStringKey = void 0;
+exports.getDefaultI18nEngine = exports.getI18nEngine = exports.DefaultLanguageCodes = exports.DefaultStringKey = void 0;
 const currency_code_1 = require("./currency-code");
 const i18n_engine_1 = require("./i18n-engine");
+const language_codes_1 = require("./language-codes");
 const timezone_1 = require("./timezone");
 const types_1 = require("./types");
 // Default enum types that can be augmented by consumers
@@ -16,29 +17,20 @@ var DefaultStringKey;
     DefaultStringKey["Error_DefaultLanguageNoCollectionTemplate"] = "error_defaultLanguageNoCollectionTemplate";
     DefaultStringKey["Error_MissingTranslationKeyTemplate"] = "error_missingTranslationKeyTemplate";
 })(DefaultStringKey || (exports.DefaultStringKey = DefaultStringKey = {}));
-var DefaultLanguage;
-(function (DefaultLanguage) {
-    DefaultLanguage["EnglishUS"] = "English (US)";
-    DefaultLanguage["EnglishUK"] = "English (UK)";
-    DefaultLanguage["French"] = "Fran\u00E7ais";
-    DefaultLanguage["MandarinChinese"] = "\u4E2D\u6587";
-    DefaultLanguage["Spanish"] = "Espa\u00F1ol";
-    DefaultLanguage["Ukrainian"] = "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0438\u0439";
-})(DefaultLanguage || (exports.DefaultLanguage = DefaultLanguage = {}));
 exports.DefaultLanguageCodes = {
-    [DefaultLanguage.EnglishUS]: 'en',
-    [DefaultLanguage.EnglishUK]: 'en-GB',
-    [DefaultLanguage.French]: 'fr',
-    [DefaultLanguage.MandarinChinese]: 'zh-CN',
-    [DefaultLanguage.Spanish]: 'es',
-    [DefaultLanguage.Ukrainian]: 'uk',
+    [language_codes_1.LanguageCodes.EN_US]: 'en-US',
+    [language_codes_1.LanguageCodes.EN_GB]: 'en-GB',
+    [language_codes_1.LanguageCodes.FR]: 'fr',
+    [language_codes_1.LanguageCodes.ES]: 'es',
+    [language_codes_1.LanguageCodes.ZH_CN]: 'zh-CN',
+    [language_codes_1.LanguageCodes.UK]: 'uk',
 };
 // Singleton instance that uses the augmented types
 const getI18nEngine = () => i18n_engine_1.I18nEngine.getInstance();
 exports.getI18nEngine = getI18nEngine;
 const getConfig = (constants, timezone, adminTimezone) => ({
     strings: {
-        [DefaultLanguage.EnglishUS]: {
+        [language_codes_1.LanguageCodes.EN_US]: {
             [DefaultStringKey.Common_Test]: 'Test',
             [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]: "Instance with key '{key}' already exists",
             [DefaultStringKey.Error_InstanceNotFoundTemplate]: "Instance with key '{key}' not found",
@@ -47,7 +39,7 @@ const getConfig = (constants, timezone, adminTimezone) => ({
             [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]: "Default language '{language}' has no string collection",
             [DefaultStringKey.Error_MissingTranslationKeyTemplate]: 'Missing translation key for type: {type}',
         },
-        [DefaultLanguage.EnglishUK]: {
+        [language_codes_1.LanguageCodes.EN_GB]: {
             [DefaultStringKey.Common_Test]: 'Test',
             [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]: "Instance with key '{key}' already exists",
             [DefaultStringKey.Error_InstanceNotFoundTemplate]: "Instance with key '{key}' not found",
@@ -56,7 +48,7 @@ const getConfig = (constants, timezone, adminTimezone) => ({
             [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]: "Default language '{language}' has no string collection",
             [DefaultStringKey.Error_MissingTranslationKeyTemplate]: 'Missing translation key for type: {type}',
         },
-        [DefaultLanguage.French]: {
+        [language_codes_1.LanguageCodes.FR]: {
             [DefaultStringKey.Common_Test]: 'Test',
             [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]: "Instance avec clé '{key}' existe déjà",
             [DefaultStringKey.Error_InstanceNotFoundTemplate]: "Instance avec clé '{key}' introuvable",
@@ -65,7 +57,7 @@ const getConfig = (constants, timezone, adminTimezone) => ({
             [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]: "La langue par défaut '{language}' n'a pas de collection de chaînes",
             [DefaultStringKey.Error_MissingTranslationKeyTemplate]: 'Clé de traduction manquante pour le type: {type}',
         },
-        [DefaultLanguage.MandarinChinese]: {
+        [language_codes_1.LanguageCodes.ZH_CN]: {
             [DefaultStringKey.Common_Test]: '测试',
             [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]: "键为'{key}'的实例已存在",
             [DefaultStringKey.Error_InstanceNotFoundTemplate]: "未找到键为'{key}'的实例",
@@ -74,7 +66,7 @@ const getConfig = (constants, timezone, adminTimezone) => ({
             [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]: "默认语言'{language}'没有字符串集合",
             [DefaultStringKey.Error_MissingTranslationKeyTemplate]: '类型缺少翻译键: {type}',
         },
-        [DefaultLanguage.Spanish]: {
+        [language_codes_1.LanguageCodes.ES]: {
             [DefaultStringKey.Common_Test]: 'Prueba',
             [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]: "La instancia con clave '{key}' ya existe",
             [DefaultStringKey.Error_InstanceNotFoundTemplate]: "Instancia con clave '{key}' no encontrada",
@@ -83,7 +75,7 @@ const getConfig = (constants, timezone, adminTimezone) => ({
             [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]: "El idioma predeterminado '{language}' no tiene colección de cadenas",
             [DefaultStringKey.Error_MissingTranslationKeyTemplate]: 'Falta clave de traducción para el tipo: {type}',
         },
-        [DefaultLanguage.Ukrainian]: {
+        [language_codes_1.LanguageCodes.UK]: {
             [DefaultStringKey.Common_Test]: 'Тест',
             [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]: "Екземпляр з ключем '{key}' вже існує",
             [DefaultStringKey.Error_InstanceNotFoundTemplate]: "Екземпляр з ключем '{key}' не знайдено",
@@ -94,11 +86,11 @@ const getConfig = (constants, timezone, adminTimezone) => ({
         },
     },
     stringNames: Object.values(DefaultStringKey),
-    defaultLanguage: DefaultLanguage.EnglishUS,
+    defaultLanguage: language_codes_1.LanguageCodes.EN_US,
     defaultTranslationContext: 'user',
     defaultCurrencyCode: new currency_code_1.CurrencyCode(types_1.DefaultCurrencyCode),
     languageCodes: exports.DefaultLanguageCodes,
-    languages: Object.values(DefaultLanguage),
+    languages: [language_codes_1.LanguageCodes.EN_US, language_codes_1.LanguageCodes.EN_GB, language_codes_1.LanguageCodes.FR, language_codes_1.LanguageCodes.ES, language_codes_1.LanguageCodes.ZH_CN, language_codes_1.LanguageCodes.UK],
     constants: constants,
     enumName: 'DefaultStringKey',
     enumObj: DefaultStringKey,

package/dist/global-active-context.d.ts

@@ -1,13 +1,13 @@
 import { IActiveContext } from './active-context';
 import { CurrencyCode } from './currency-code';
-import { DefaultLanguage } from './default-config';
+import { DefaultLanguageCode } from './default-config';
 import { IGlobalActiveContext } from './i-global-active-context';
 import { Timezone } from './timezone';
 import { LanguageContextSpace } from './types';
 export declare class GlobalActiveContext<TLanguage extends string, TActiveContext extends IActiveContext<TLanguage>> implements IGlobalActiveContext<TLanguage, TActiveContext> {
     protected static _contextMap: Map<string, IActiveContext<any>>;
     static readonly defaultContextKey = "default";
-    static readonly defaultLanguage: DefaultLanguage;
+    static readonly defaultLanguage: DefaultLanguageCode;
     private static _instance;
     static get instance(): GlobalActiveContext<any, any>;
     static getInstance<TLanguage extends string, TActiveContext extends IActiveContext<TLanguage>>(): GlobalActiveContext<TLanguage, TActiveContext>;

package/dist/global-active-context.js

@@ -4,7 +4,6 @@ exports.GlobalActiveContext = void 0;
 const context_error_1 = require("./context-error");
 const context_error_type_1 = require("./context-error-type");
 const currency_code_1 = require("./currency-code");
-const default_config_1 = require("./default-config");
 const timezone_1 = require("./timezone");
 const types_1 = require("./types");
 class GlobalActiveContext {
@@ -168,4 +167,4 @@ class GlobalActiveContext {
 exports.GlobalActiveContext = GlobalActiveContext;
 GlobalActiveContext._contextMap = new Map();
 GlobalActiveContext.defaultContextKey = 'default';
-GlobalActiveContext.defaultLanguage = default_config_1.DefaultLanguage.EnglishUS;
+GlobalActiveContext.defaultLanguage = 'en-US';

package/dist/index.d.ts

@@ -25,8 +25,8 @@ export * from './utils';
 export * from './validation-config';
 export * from './validation-result';
 export * from './core-i18n';
-export * from './core-language';
 export * from './core-string-key';
+export * from './language-codes';
 export * from './language-registry';
 export * from './plugin-i18n-engine';
 export * from './registry-config';

package/dist/index.js

@@ -44,8 +44,8 @@ __exportStar(require("./utils"), exports);
 __exportStar(require("./validation-config"), exports);
 __exportStar(require("./validation-result"), exports);
 __exportStar(require("./core-i18n"), exports);
-__exportStar(require("./core-language"), exports);
 __exportStar(require("./core-string-key"), exports);
+__exportStar(require("./language-codes"), exports);
 __exportStar(require("./language-registry"), exports);
 __exportStar(require("./plugin-i18n-engine"), exports);
 __exportStar(require("./registry-config"), exports);

package/dist/language-codes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Common language codes following BCP 47 standard.
+ * These are provided as constants for convenience, but any string can be used as a language code.
+ * Site builders can use these or define their own custom language codes.
+ */
+export declare const LanguageCodes: {
+    readonly EN_US: "en-US";
+    readonly EN_GB: "en-GB";
+    readonly FR: "fr";
+    readonly ES: "es";
+    readonly DE: "de";
+    readonly ZH_CN: "zh-CN";
+    readonly JA: "ja";
+    readonly UK: "uk";
+};
+/**
+ * Type representing any language code (string)
+ */
+export type LanguageCode = string;
+/**
+ * Type representing the common language codes provided by this library
+ */
+export type CommonLanguageCode = typeof LanguageCodes[keyof typeof LanguageCodes];
+/**
+ * Helper to get display names for common language codes
+ */
+export declare const LanguageDisplayNames: Record<CommonLanguageCode, string>;

package/dist/language-codes.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LanguageDisplayNames = exports.LanguageCodes = void 0;
+/**
+ * Common language codes following BCP 47 standard.
+ * These are provided as constants for convenience, but any string can be used as a language code.
+ * Site builders can use these or define their own custom language codes.
+ */
+exports.LanguageCodes = {
+    EN_US: 'en-US',
+    EN_GB: 'en-GB',
+    FR: 'fr',
+    ES: 'es',
+    DE: 'de',
+    ZH_CN: 'zh-CN',
+    JA: 'ja',
+    UK: 'uk',
+};
+/**
+ * Helper to get display names for common language codes
+ */
+exports.LanguageDisplayNames = {
+    [exports.LanguageCodes.EN_US]: 'English (US)',
+    [exports.LanguageCodes.EN_GB]: 'English (UK)',
+    [exports.LanguageCodes.FR]: 'Français',
+    [exports.LanguageCodes.ES]: 'Español',
+    [exports.LanguageCodes.DE]: 'Deutsch',
+    [exports.LanguageCodes.ZH_CN]: '中文',
+    [exports.LanguageCodes.JA]: '日本語',
+    [exports.LanguageCodes.UK]: 'Українська',
+};

package/dist/registry-error.d.ts

@@ -1,4 +1,4 @@
-import { CoreLanguage } from './core-language';
+import { CoreLanguageCode } from './core-i18n';
 import { RegistryErrorType } from './registry-error-type';
 import { TranslationEngine } from './typed-error';
 /**
@@ -11,7 +11,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?: CoreLanguage, metadata?: Record<string, any>): RegistryError;
+    static createWithEngine(engine: TranslationEngine, type: RegistryErrorType, variables?: Record<string, string | number>, language?: CoreLanguageCode, metadata?: Record<string, any>): RegistryError;
     /**
      * Create a simple RegistryError without engine dependency
      */

package/dist/typed-error.d.ts

@@ -1,6 +1,6 @@
 import { Language, StringKey } from './default-config';
 import { I18nEngine } from './i18n-engine';
-import { CoreLanguage } from './core-language';
+import { CoreLanguageCode } from './core-i18n';
 import { CoreStringKey } from './core-string-key';
 import { PluginI18nEngine } from './plugin-i18n-engine';
 /**
@@ -42,7 +42,7 @@ export declare abstract class TypedError<TEnum extends Record<string, string>, T
 /**
  * Plugin-based TypedError that works with the new component registration system
  */
-export declare abstract class PluginTypedError<TEnum extends Record<string, string>, TStringKey extends string, TLanguages extends string = CoreLanguage> extends Error {
+export declare abstract class PluginTypedError<TEnum extends Record<string, string>, TStringKey extends string, TLanguages extends string = string> extends Error {
     readonly componentId: string;
     readonly type: TEnum[keyof TEnum];
     readonly reasonMap: CompleteReasonMap<TEnum, TStringKey>;
@@ -56,18 +56,18 @@ 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?: CoreLanguage | undefined;
+    readonly language?: CoreLanguageCode | undefined;
     readonly otherVars?: Record<string, string | number> | undefined;
-    constructor(engine: PluginI18nEngine<CoreLanguage>, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, CoreStringKey>, language?: CoreLanguage | undefined, 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);
 }
 /**
  * Helper function to create a plugin-based TypedError with automatic engine detection
  */
-export declare function createPluginTypedError<TEnum extends Record<string, string>, TStringKey extends string, TLanguages extends string = CoreLanguage>(componentId: string, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, TStringKey>, otherVars?: Record<string, string | number>, language?: TLanguages, instanceKey?: string): Error;
+export declare function createPluginTypedError<TEnum extends Record<string, string>, TStringKey extends string, TLanguages extends string = string>(componentId: string, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, TStringKey>, otherVars?: Record<string, string | number>, language?: TLanguages, instanceKey?: string): Error;
 /**
  * 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?: CoreLanguage, 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?: CoreLanguageCode, instanceKey?: string): Error;
 /**
  * Create a simple error with translation support (generalized pattern from RegistryError)
  */

package/dist/typed-error.js

@@ -177,7 +177,7 @@ const coreErrorReasonMap: CompleteReasonMap<typeof DatabaseErrorType, CoreString
 
 class DatabaseError extends CoreTypedError<typeof DatabaseErrorType> {
   constructor(
-    engine: PluginI18nEngine<CoreLanguage>,
+    engine: PluginI18nEngine<CoreLanguageCode>,
     type: DatabaseErrorType,
     otherVars?: Record<string, string | number>,
     language?: CoreLanguage
@@ -187,7 +187,7 @@ class DatabaseError extends CoreTypedError<typeof DatabaseErrorType> {
 }
 
 // Usage:
-// const engine = PluginI18nEngine.getInstance<CoreLanguage>();
+// const engine = PluginI18nEngine.getInstance<CoreLanguageCode>();
 // throw new DatabaseError(engine, DatabaseErrorType.ConnectionFailed);
 */
 // Example 2: Custom component error with custom strings
@@ -210,9 +210,9 @@ const userErrorReasonMap: CompleteReasonMap<typeof UserErrorType, UserErrorStrin
   [UserErrorType.AccountLocked]: UserErrorStringKey.AccountLockedMessage
 };
 
-class UserError extends PluginTypedError<typeof UserErrorType, UserErrorStringKey, CoreLanguage> {
+class UserError extends PluginTypedError<typeof UserErrorType, UserErrorStringKey, CoreLanguageCode> {
   constructor(
-    engine: PluginI18nEngine<CoreLanguage>,
+    engine: PluginI18nEngine<CoreLanguageCode>,
     type: UserErrorType,
     otherVars?: Record<string, string | number>,
     language?: CoreLanguage
@@ -222,7 +222,7 @@ class UserError extends PluginTypedError<typeof UserErrorType, UserErrorStringKe
 }
 
 // Usage:
-// const engine = PluginI18nEngine.getInstance<CoreLanguage>();
+// const engine = PluginI18nEngine.getInstance<CoreLanguageCode>();
 // 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.1.10",
+  "version": "1.2.1",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",