@digitaldefiance/i18n-lib 1.0.23 → 1.0.25

package/dist/src/currency-code.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CurrencyCode = void 0;
+const currency_codes_1 = require("currency-codes");
+const types_1 = require("./types");
+/**
+ * Class representing a validated currency code.
+ */
+class CurrencyCode {
+    /**
+     * Gets the currency code value.
+     */
+    get value() {
+        return this._value;
+    }
+    /**
+     * Sets the currency code value after validating it.
+     */
+    set value(value) {
+        if (!CurrencyCode.values.includes(value)) {
+            throw new Error('Invalid currency code');
+        }
+        this._value = value;
+    }
+    /**
+     * Gets the list of all valid currency codes.
+     */
+    static get values() {
+        return (0, currency_codes_1.codes)();
+    }
+    constructor(value = types_1.DefaultCurrencyCode) {
+        this._value = types_1.DefaultCurrencyCode;
+        this.value = value;
+    }
+}
+exports.CurrencyCode = CurrencyCode;

package/dist/src/currency-format.d.ts

@@ -0,0 +1,10 @@
+import { CurrencyPosition } from './types';
+/**
+ * Represents the format details for a specific currency in a given locale.
+ */
+export interface CurrencyFormat {
+    symbol: string;
+    position: CurrencyPosition;
+    groupSeparator: string;
+    decimalSeparator: string;
+}

package/dist/src/currency-format.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/currency.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Currency formatting utilities
+ */
+import { CurrencyFormat } from './currency-format';
+/**
+ * Get currency format details for a given locale and currency code.
+ * @param locale The locale string (e.g., 'en-US')
+ * @param currencyCode The ISO 4217 currency code (e.g., 'USD')
+ * @returns The currency format details
+ */
+export declare function getCurrencyFormat(locale: string, currencyCode: string): CurrencyFormat;

package/dist/src/currency.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Currency formatting utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrencyFormat = getCurrencyFormat;
+/**
+ * Get currency format details for a given locale and currency code.
+ * @param locale The locale string (e.g., 'en-US')
+ * @param currencyCode The ISO 4217 currency code (e.g., 'USD')
+ * @returns The currency format details
+ */
+function getCurrencyFormat(locale, currencyCode) {
+    const formatter = new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency: currencyCode,
+    });
+    const parts = formatter.formatToParts(1234567.89);
+    const symbol = parts.find((part) => part.type === 'currency')?.value || '';
+    const symbolIndex = parts.findIndex((part) => part.type === 'currency');
+    const decimalIndex = parts.findIndex((part) => part.type === 'decimal');
+    const integerIndex = parts.findIndex((part) => part.type === 'integer');
+    let position;
+    if (decimalIndex === -1) {
+        // No decimal separator
+        if (symbolIndex < integerIndex) {
+            position = 'prefix';
+        }
+        else {
+            position = 'postfix';
+        }
+    }
+    else if (symbolIndex < decimalIndex && symbolIndex < integerIndex) {
+        position = 'prefix';
+    }
+    else if (symbolIndex > decimalIndex) {
+        position = 'postfix';
+    }
+    else {
+        position = 'infix';
+    }
+    return {
+        symbol,
+        position,
+        groupSeparator: parts.find((part) => part.type === 'group')?.value || ',',
+        decimalSeparator: parts.find((part) => part.type === 'decimal')?.value || '.',
+    };
+}

package/dist/src/enum-registry.d.ts

@@ -0,0 +1,35 @@
+import { EnumLanguageTranslation } from './types';
+/**
+ * Registry for managing enum translations across multiple languages.
+ */
+export declare class EnumTranslationRegistry<TLanguage extends string> {
+    protected translations: Map<any, Partial<{ [L in TLanguage]: import("./types").EnumTranslation<any>; }>>;
+    protected enumNames: WeakMap<any, string>;
+    /**
+     * Registers an enumeration with its translations and a name.
+     * @param enumObj The enumeration object
+     * @param translations The translations for the enumeration
+     * @param enumName The name of the enumeration
+     */
+    register<TEnum extends string | number>(enumObj: Record<string, TEnum>, translations: EnumLanguageTranslation<TEnum, TLanguage>, enumName: string): void;
+    /**
+     * Translates a value from the given enumeration to the specified language.
+     * @param enumObj The enumeration object
+     * @param value The value to translate
+     * @param language The target language for translation
+     * @returns The translated string
+     */
+    translate<TEnum extends string | number>(enumObj: Record<string, TEnum>, value: TEnum, language: TLanguage): string;
+    /**
+     * Gets the name of the enumeration.
+     * @param enumObj The enumeration object
+     * @returns The name of the enumeration
+     */
+    private getEnumName;
+    /**
+     * Checks if the registry has translations for the given enumeration.
+     * @param enumObj The enumeration object
+     * @returns True if translations exist, false otherwise
+     */
+    has(enumObj: any): boolean;
+}

package/dist/src/enum-registry.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnumTranslationRegistry = void 0;
+/**
+ * Registry for managing enum translations across multiple languages.
+ */
+class EnumTranslationRegistry {
+    constructor() {
+        this.translations = new Map();
+        this.enumNames = new WeakMap();
+    }
+    /**
+     * Registers an enumeration with its translations and a name.
+     * @param enumObj The enumeration object
+     * @param translations The translations for the enumeration
+     * @param enumName The name of the enumeration
+     */
+    register(enumObj, translations, enumName) {
+        this.translations.set(enumObj, translations);
+        this.enumNames.set(enumObj, enumName);
+    }
+    /**
+     * Translates a value from the given enumeration to the specified language.
+     * @param enumObj The enumeration object
+     * @param value The value to translate
+     * @param language The target language for translation
+     * @returns The translated string
+     */
+    translate(enumObj, value, language) {
+        const translations = this.translations.get(enumObj);
+        if (!translations) {
+            throw new Error(`No translations found for enum: ${this.getEnumName(enumObj)}`);
+        }
+        const langTranslations = translations[language];
+        if (!langTranslations) {
+            throw new Error(`No translations found for language: ${language}`);
+        }
+        let result = langTranslations[value];
+        if (!result && typeof value === 'number') {
+            const stringKey = Object.keys(enumObj).find((key) => enumObj[key] === value);
+            if (stringKey) {
+                result = langTranslations[stringKey];
+            }
+        }
+        if (!result) {
+            throw new Error(`No translation found for value: ${String(value)}`);
+        }
+        return result;
+    }
+    /**
+     * Gets the name of the enumeration.
+     * @param enumObj The enumeration object
+     * @returns The name of the enumeration
+     */
+    getEnumName(enumObj) {
+        return this.enumNames.get(enumObj) || 'UnknownEnum';
+    }
+    /**
+     * Checks if the registry has translations for the given enumeration.
+     * @param enumObj The enumeration object
+     * @returns True if translations exist, false otherwise
+     */
+    has(enumObj) {
+        return this.translations.has(enumObj);
+    }
+}
+exports.EnumTranslationRegistry = EnumTranslationRegistry;

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

@@ -0,0 +1,156 @@
+import { EnumTranslationRegistry } from './enum-registry';
+import { EnumLanguageTranslation, I18nConfig, I18nContext } from './types';
+/**
+ * Internationalization engine class
+ */
+export declare class I18nEngine<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TTranslationContext extends string = string, TContext extends I18nContext<TLanguage, TTranslationContext> = I18nContext<TLanguage, TTranslationContext>> {
+    /**
+     * Registry for enum translations
+     */
+    protected enumRegistry: EnumTranslationRegistry<TLanguage>;
+    /**
+     * Configuration for the i18n engine
+     */
+    readonly config: I18nConfig<TStringKey, TLanguage, TConstants, TTranslationContext>;
+    /**
+     * Static instances for semi-singleton pattern
+     */
+    private static _instances;
+    /**
+     * Default instance key (first created instance)
+     */
+    private static _defaultKey;
+    /**
+     * Default instance key if none is provided
+     */
+    protected static readonly DefaultInstanceKey = "default";
+    /**
+     * Global context for translations (used if no context is provided) for this instance
+     */
+    private _context;
+    /**
+     * Default template processor instance
+     */
+    readonly t: (str: string, language?: TLanguage, ...otherVars: Record<string, string | number>[]) => string;
+    /**
+     * Creates a new I18nEngine instance
+     * @param config The i18n configuration
+     * @param key Optional instance key for the semi-singleton pattern
+     * @throws Error if an instance with the same key already exists
+     */
+    constructor(config: I18nConfig<TStringKey, TLanguage, TConstants, TTranslationContext>, key?: string, newContext?: () => TContext);
+    /**
+     * Gets an instance of the I18nEngine by key. If no key is provided, the default instance is returned.
+     * @param key The key of the instance to retrieve
+     * @returns The I18nEngine instance
+     * @throws Error if the instance with the provided key does not exist
+     */
+    static getInstance<T extends I18nEngine<any, any, any, any>>(key?: string): T;
+    /**
+     * Gets a translation for the provided error key using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated error message
+     */
+    static getErrorMessage(errorKey: string, vars?: Record<string, string | number>, instanceKey?: string, language?: string, fallbackLanguage?: string): string;
+    /**
+     * Throws an error with a translated message using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @throws Error with translated message
+     */
+    static throwError(errorKey: string, vars?: Record<string, string | number>, instanceKey?: string): never;
+    /**
+     * Gets the global context for translations
+     * @returns The global context object
+     */
+    get context(): TContext;
+    /**
+     * Sets the global context for translations (used if no context is provided) for this instance
+     * @param context The context to set
+     */
+    set context(context: Partial<TContext>);
+    /**
+     * Translates a string key into the specified language, replacing any variables as needed.
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated string
+     */
+    translate(key: TStringKey, vars?: Record<string, string | number>, language?: TLanguage, fallbackLanguage?: TLanguage): string;
+    /**
+     * Translates an enumeration value into the specified language.
+     * @param enumObj The enumeration object
+     * @param value The enumeration value to translate
+     * @param language The language to translate to
+     * @returns The translated enumeration value
+     */
+    translateEnum<TEnum extends string | number>(enumObj: Record<string, TEnum>, value: TEnum, language: TLanguage): string;
+    /**
+     * Registers an enumeration and its translations with the engine.
+     * @param enumObj The enumeration object
+     * @param translations The translations for the enumeration
+     * @param enumName The name of the enumeration (for error messages)
+     */
+    registerEnum<TEnum extends string | number>(enumObj: Record<string, TEnum> | Record<string | number, string | number>, translations: EnumLanguageTranslation<TEnum, TLanguage>, enumName: string): void;
+    /**
+     * Safe translation that prevents infinite recursion for error messages
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @returns The translated string or the key if translation fails
+     */
+    private safeTranslate;
+    /**
+     * Retrieves the string for the given language and key, throwing an error if not found.
+     * @param language The language to get the string for
+     * @param key The string key to retrieve
+     * @returns The string value
+     * @throws Error if the language or string key is not found
+     */
+    private getString;
+    /**
+     * Gets the language code for the specified language.
+     * @param language The language to get the code for
+     * @returns The language code
+     */
+    getLanguageCode(language: TLanguage): string;
+    /**
+     * Gets the language for the specified language code.
+     * @param code The language code to look up
+     * @returns The language, or undefined if not found
+     */
+    getLanguageFromCode(code: string): TLanguage | undefined;
+    /**
+     * Gets all language codes.
+     * @returns A record of all language codes
+     */
+    getAllLanguageCodes(): Record<TLanguage, string>;
+    /**
+     * Gets all available languages.
+     * @returns An array of all available languages
+     */
+    getAvailableLanguages(): TLanguage[];
+    /**
+     * Checks if a language is available.
+     * @param language The language to check
+     * @returns True if the language is available, false otherwise
+     */
+    isLanguageAvailable(language: string): language is TLanguage;
+    /**
+     * Clears all instances (for testing purposes)
+     * @internal
+     */
+    static clearInstances(): void;
+    /**
+     * Removes a specific instance by key
+     * @param key The key of the instance to remove
+     * @internal
+     */
+    static removeInstance(key?: string): void;
+}

package/dist/src/i18n-engine.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nEngine = void 0;
+const context_1 = require("./context");
+const enum_registry_1 = require("./enum-registry");
+const template_1 = require("./template");
+const utils_1 = require("./utils");
+/**
+ * Internationalization engine class
+ */
+class I18nEngine {
+    /**
+     * Creates a new I18nEngine instance
+     * @param config The i18n configuration
+     * @param key Optional instance key for the semi-singleton pattern
+     * @throws Error if an instance with the same key already exists
+     */
+    constructor(config, key, newContext = () => (0, context_1.createContext)(config.defaultLanguage, config.defaultTranslationContext, config.defaultCurrencyCode, config.timezone, config.adminTimezone)) {
+        this.config = config;
+        this.enumRegistry = new enum_registry_1.EnumTranslationRegistry();
+        this._context = newContext();
+        const instanceKey = key || I18nEngine.DefaultInstanceKey;
+        if (I18nEngine._instances.has(instanceKey)) {
+            const existing = I18nEngine._instances.get(instanceKey);
+            throw new Error(existing.translate('Error_InstanceAlreadyExistsTemplate', {
+                key: instanceKey,
+            }));
+        }
+        I18nEngine._instances.set(instanceKey, this);
+        if (!I18nEngine._defaultKey) {
+            I18nEngine._defaultKey = instanceKey;
+        }
+        // Initialize the default template processor
+        this.t = (0, template_1.createTemplateProcessor)(this.config.enumObj || {}, (key, vars, language) => this.translate(key, vars, language), this.config.enumName || 'StringKey');
+    }
+    /**
+     * Gets an instance of the I18nEngine by key. If no key is provided, the default instance is returned.
+     * @param key The key of the instance to retrieve
+     * @returns The I18nEngine instance
+     * @throws Error if the instance with the provided key does not exist
+     */
+    static getInstance(key) {
+        const instanceKey = key || I18nEngine._defaultKey || I18nEngine.DefaultInstanceKey;
+        if (!instanceKey || !I18nEngine._instances.has(instanceKey)) {
+            throw new Error(I18nEngine.getErrorMessage('Error_InstanceNotFoundTemplate', {
+                key: instanceKey,
+            }));
+        }
+        return I18nEngine._instances.get(instanceKey);
+    }
+    /**
+     * Gets a translation for the provided error key using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated error message
+     */
+    static getErrorMessage(errorKey, vars, instanceKey, language, fallbackLanguage) {
+        try {
+            const instance = I18nEngine.getInstance(instanceKey);
+            return instance.translate(errorKey, vars, language, fallbackLanguage);
+        }
+        catch {
+            return `${errorKey}: ${JSON.stringify(vars || {})}`;
+        }
+    }
+    /**
+     * Throws an error with a translated message using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @throws Error with translated message
+     */
+    static throwError(errorKey, vars, instanceKey) {
+        throw new Error(I18nEngine.getErrorMessage(errorKey, vars, instanceKey));
+    }
+    /**
+     * Gets the global context for translations
+     * @returns The global context object
+     */
+    get context() {
+        return this._context;
+    }
+    /**
+     * Sets the global context for translations (used if no context is provided) for this instance
+     * @param context The context to set
+     */
+    set context(context) {
+        this._context = { ...this._context, ...context };
+    }
+    /**
+     * Translates a string key into the specified language, replacing any variables as needed.
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated string
+     */
+    translate(key, vars, language, fallbackLanguage) {
+        const lang = language ??
+            (this._context.currentContext === 'admin'
+                ? this._context.adminLanguage
+                : this._context.language);
+        const fallback = fallbackLanguage ?? this.config.defaultLanguage;
+        try {
+            const stringValue = this.getString(lang, key);
+            return (0, utils_1.isTemplate)(key)
+                ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
+                : stringValue;
+        }
+        catch {
+            if (lang !== fallback) {
+                try {
+                    const stringValue = this.getString(fallback, key);
+                    return (0, utils_1.isTemplate)(key)
+                        ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
+                        : stringValue;
+                }
+                catch {
+                    return key;
+                }
+            }
+            return key;
+        }
+    }
+    /**
+     * Translates an enumeration value into the specified language.
+     * @param enumObj The enumeration object
+     * @param value The enumeration value to translate
+     * @param language The language to translate to
+     * @returns The translated enumeration value
+     */
+    translateEnum(enumObj, value, language) {
+        return this.enumRegistry.translate(enumObj, value, language);
+    }
+    /**
+     * Registers an enumeration and its translations with the engine.
+     * @param enumObj The enumeration object
+     * @param translations The translations for the enumeration
+     * @param enumName The name of the enumeration (for error messages)
+     */
+    registerEnum(enumObj, translations, enumName) {
+        this.enumRegistry.register(enumObj, translations, enumName);
+    }
+    /**
+     * Safe translation that prevents infinite recursion for error messages
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @returns The translated string or the key if translation fails
+     */
+    safeTranslate(key, vars, language) {
+        try {
+            const lang = language ?? this.config.defaultLanguage;
+            const strings = this.config.strings[lang];
+            if (!strings?.[key])
+                return key;
+            const stringValue = strings[key];
+            return (0, utils_1.isTemplate)(key)
+                ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
+                : stringValue;
+        }
+        catch {
+            return key;
+        }
+    }
+    /**
+     * Retrieves the string for the given language and key, throwing an error if not found.
+     * @param language The language to get the string for
+     * @param key The string key to retrieve
+     * @returns The string value
+     * @throws Error if the language or string key is not found
+     */
+    getString(language, key) {
+        const strings = this.config.strings[language];
+        if (!strings) {
+            throw new Error(this.safeTranslate('Error_LanguageNotFound', { language }) ||
+                `Language not found: ${language}`);
+        }
+        const value = strings[key];
+        if (!value) {
+            throw new Error(this.safeTranslate('Error_StringNotFound', { key }) ||
+                `String not found: ${key}`);
+        }
+        return value;
+    }
+    /**
+     * Gets the language code for the specified language.
+     * @param language The language to get the code for
+     * @returns The language code
+     */
+    getLanguageCode(language) {
+        return this.config.languageCodes[language] || language;
+    }
+    /**
+     * Gets the language for the specified language code.
+     * @param code The language code to look up
+     * @returns The language, or undefined if not found
+     */
+    getLanguageFromCode(code) {
+        for (const [lang, langCode] of Object.entries(this.config.languageCodes)) {
+            if (langCode === code) {
+                return lang;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Gets all language codes.
+     * @returns A record of all language codes
+     */
+    getAllLanguageCodes() {
+        return this.config.languageCodes;
+    }
+    /**
+     * Gets all available languages.
+     * @returns An array of all available languages
+     */
+    getAvailableLanguages() {
+        return Object.keys(this.config.strings);
+    }
+    /**
+     * Checks if a language is available.
+     * @param language The language to check
+     * @returns True if the language is available, false otherwise
+     */
+    isLanguageAvailable(language) {
+        return Object.keys(this.config.strings).includes(language);
+    }
+    /**
+     * Clears all instances (for testing purposes)
+     * @internal
+     */
+    static clearInstances() {
+        I18nEngine._instances.clear();
+        I18nEngine._defaultKey = null;
+    }
+    /**
+     * Removes a specific instance by key
+     * @param key The key of the instance to remove
+     * @internal
+     */
+    static removeInstance(key) {
+        const instanceKey = key || I18nEngine.DefaultInstanceKey;
+        I18nEngine._instances.delete(instanceKey);
+        if (I18nEngine._defaultKey === instanceKey) {
+            const nextKey = I18nEngine._instances.keys().next().value;
+            I18nEngine._defaultKey =
+                I18nEngine._instances.size > 0 && nextKey ? nextKey : null;
+        }
+    }
+}
+exports.I18nEngine = I18nEngine;
+/**
+ * Static instances for semi-singleton pattern
+ */
+I18nEngine._instances = new Map();
+/**
+ * Default instance key (first created instance)
+ */
+I18nEngine._defaultKey = null;
+/**
+ * Default instance key if none is provided
+ */
+I18nEngine.DefaultInstanceKey = 'default';

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+export * from './active-context';
+export * from './context';
+export * from './context-manager';
+export * from './currency';
+export * from './currency-code';
+export * from './currency-format';
+export * from './enum-registry';
+export * from './i18n-engine';
+export * from './template';
+export * from './timezone';
+export * from './types';
+export * from './utils';
+export { I18nEngine as I18n } from './i18n-engine';