@digitaldefiance/i18n-lib 1.0.22 → 1.0.24

package/dist/src/context.d.ts

@@ -0,0 +1,43 @@
+import { CurrencyCode } from './currency-code';
+import { Timezone } from './timezone';
+import { I18nContext, LanguageContext } from './types';
+/**
+ * Creates a new I18n context with default values.
+ * @param defaultLanguage - The default language for the context
+ * @param defaultContext - The default language context
+ * @param defaultCurrencyCode - The default currency code (defaults to USD)
+ * @param defaultTimezone - The default timezone (defaults to UTC)
+ * @param defaultAdminTimezone - The default admin timezone (defaults to UTC)
+ * @returns A new I18nContext instance
+ */
+export declare function createContext<TLanguage extends string, TTranslationContext extends string = LanguageContext, TContext extends I18nContext<TLanguage, TTranslationContext> = I18nContext<TLanguage, TTranslationContext>>(defaultLanguage: TLanguage, defaultContext: TTranslationContext, defaultCurrencyCode?: CurrencyCode, defaultTimezone?: Timezone, defaultAdminTimezone?: Timezone): TContext;
+/**
+ * Sets the language for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param language - The language to set
+ */
+export declare function setLanguage<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, language: TLanguage): void;
+/**
+ * Sets the admin language for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param language - The admin language to set
+ */
+export declare function setAdminLanguage<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, language: TLanguage): void;
+/**
+ * Sets the current context for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param languageContext - The language context to set
+ */
+export declare function setContext<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, languageContext: TContext): void;
+/**
+ * Sets the timezone for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param timezone - The timezone to set
+ */
+export declare function setTimezone<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, timezone: Timezone): void;
+/**
+ * Sets the admin timezone for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param timezone - The admin timezone to set
+ */
+export declare function setAdminTimezone<TLanguage extends string, TContext extends string = LanguageContext>(context: I18nContext<TLanguage, TContext>, timezone: Timezone): void;

package/dist/src/context.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContext = createContext;
+exports.setLanguage = setLanguage;
+exports.setAdminLanguage = setAdminLanguage;
+exports.setContext = setContext;
+exports.setTimezone = setTimezone;
+exports.setAdminTimezone = setAdminTimezone;
+const currency_code_1 = require("./currency-code");
+const timezone_1 = require("./timezone");
+/**
+ * Creates a new I18n context with default values.
+ * @param defaultLanguage - The default language for the context
+ * @param defaultContext - The default language context
+ * @param defaultCurrencyCode - The default currency code (defaults to USD)
+ * @param defaultTimezone - The default timezone (defaults to UTC)
+ * @param defaultAdminTimezone - The default admin timezone (defaults to UTC)
+ * @returns A new I18nContext instance
+ */
+function createContext(defaultLanguage, defaultContext, defaultCurrencyCode = new currency_code_1.CurrencyCode('USD'), defaultTimezone = new timezone_1.Timezone('UTC'), defaultAdminTimezone = new timezone_1.Timezone('UTC')) {
+    return {
+        language: defaultLanguage,
+        adminLanguage: defaultLanguage,
+        currencyCode: defaultCurrencyCode,
+        currentContext: defaultContext,
+        timezone: defaultTimezone,
+        adminTimezone: defaultAdminTimezone,
+    };
+}
+/**
+ * Sets the language for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param language - The language to set
+ */
+function setLanguage(context, language) {
+    context.language = language;
+}
+/**
+ * Sets the admin language for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param language - The admin language to set
+ */
+function setAdminLanguage(context, language) {
+    context.adminLanguage = language;
+}
+/**
+ * Sets the current context for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param languageContext - The language context to set
+ */
+function setContext(context, languageContext) {
+    context.currentContext = languageContext;
+}
+/**
+ * Sets the timezone for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param timezone - The timezone to set
+ */
+function setTimezone(context, timezone) {
+    context.timezone = timezone;
+}
+/**
+ * Sets the admin timezone for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param timezone - The admin timezone to set
+ */
+function setAdminTimezone(context, timezone) {
+    context.adminTimezone = timezone;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Class representing a validated currency code.
+ */
+export declare class CurrencyCode {
+    private _value;
+    /**
+     * Gets the currency code value.
+     */
+    get value(): string;
+    /**
+     * Sets the currency code value after validating it.
+     */
+    set value(value: string);
+    /**
+     * Gets the list of all valid currency codes.
+     */
+    static get values(): string[];
+    constructor(value?: string);
+}

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;
+}