@digitaldefiance/i18n-lib 1.2.1 → 1.2.2

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

@@ -1,156 +0,0 @@
-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

@@ -1,267 +0,0 @@
-"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

@@ -1,13 +0,0 @@
-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';

package/dist/src/index.js

@@ -1,32 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.I18n = void 0;
-__exportStar(require("./active-context"), exports);
-__exportStar(require("./context"), exports);
-__exportStar(require("./context-manager"), exports);
-__exportStar(require("./currency"), exports);
-__exportStar(require("./currency-code"), exports);
-__exportStar(require("./currency-format"), exports);
-__exportStar(require("./enum-registry"), exports);
-__exportStar(require("./i18n-engine"), exports);
-__exportStar(require("./template"), exports);
-__exportStar(require("./timezone"), exports);
-__exportStar(require("./types"), exports);
-__exportStar(require("./utils"), exports);
-// Re-export for convenience
-var i18n_engine_1 = require("./i18n-engine");
-Object.defineProperty(exports, "I18n", { enumerable: true, get: function () { return i18n_engine_1.I18nEngine; } });

package/dist/src/template.d.ts

@@ -1,12 +0,0 @@
-/**
- * Template processing utilities for i18n
- */
-export type EnumKeys<T> = keyof T;
-/**
- * Recursive type to validate that all enum keys in the template string exist in the provided enum type
- */
-export type IsValidEnumTemplate<T extends string, TEnum> = T extends `${string}{{${string}.${infer Key}}}${infer Rest}` ? Key extends EnumKeys<TEnum> ? IsValidEnumTemplate<Rest, TEnum> : false : true;
-/**
- * Template function that processes {{EnumName.EnumKey}} patterns
- */
-export declare function createTemplateProcessor<TEnum extends Record<string, string>, TLanguage extends string>(enumObj: TEnum, translateFn: (key: TEnum[keyof TEnum], vars?: Record<string, string | number>, language?: TLanguage) => string, enumName: string): <T extends string>(str: IsValidEnumTemplate<T, TEnum> extends true ? T : never, language?: TLanguage, ...otherVars: Record<string, string | number>[]) => string;

package/dist/src/template.js

@@ -1,30 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTemplateProcessor = createTemplateProcessor;
-/**
- * Template function that processes {{EnumName.EnumKey}} patterns
- */
-function createTemplateProcessor(enumObj, translateFn, enumName) {
-    return function t(str, language, ...otherVars) {
-        let varIndex = 0;
-        const pattern = new RegExp(`\\{\\{${enumName}\\.(\\w+)\\}\\}`, 'g');
-        // First replace enum patterns
-        let result = str.replace(pattern, (match, enumKey) => {
-            const enumValue = enumObj[enumKey];
-            if (!enumValue) {
-                return match; // Return original if enum key not found
-            }
-            const needsVars = enumValue
-                .toLowerCase()
-                .endsWith('template');
-            const vars = needsVars ? otherVars[varIndex++] ?? {} : {};
-            return translateFn(enumValue, vars, language);
-        });
-        // Then replace any remaining variables from all otherVars
-        const allVars = otherVars.reduce((acc, vars) => ({ ...acc, ...vars }), {});
-        result = result.replace(/\{(\w+)\}/g, (match, varName) => {
-            return allVars[varName] !== undefined ? String(allVars[varName]) : match;
-        });
-        return result;
-    };
-}

package/dist/src/timezone.d.ts

@@ -1,11 +0,0 @@
-/**
- * Class representing a validated timezone.
- */
-export declare class Timezone {
-    private readonly _timezone;
-    constructor(timezone: string);
-    /**
-     * Gets the timezone value.
-     */
-    get value(): string;
-}

package/dist/src/timezone.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Timezone = void 0;
-const utils_1 = require("./utils");
-/**
- * Class representing a validated timezone.
- */
-class Timezone {
-    constructor(timezone) {
-        if (!(0, utils_1.isValidTimezone)(timezone)) {
-            throw new Error(`Invalid timezone: ${timezone}`);
-        }
-        this._timezone = timezone;
-    }
-    /**
-     * Gets the timezone value.
-     */
-    get value() {
-        return this._timezone;
-    }
-}
-exports.Timezone = Timezone;

package/dist/src/types.d.ts

@@ -1,78 +0,0 @@
-import { CurrencyCode } from './currency-code';
-import { Timezone } from './timezone';
-/**
- * Standard language contexts
- */
-export type LanguageContext = 'admin' | 'user' | 'system' | 'api';
-/**
- * Default currency code
- */
-export declare const DefaultCurrencyCode: string;
-/**
- * Currency position type
- */
-export type CurrencyPosition = 'prefix' | 'postfix' | 'infix';
-/**
- * Custom language context type
- */
-export type CustomLanguageContext<T extends string = LanguageContext> = T;
-/**
- * Collection of localized strings for a specific language
- */
-export type StringsCollection<TStringKey extends string> = Partial<Record<TStringKey, string>>;
-/**
- * Mapping of languages to their respective string collections
- */
-export type MasterStringsCollection<TStringKey extends string, TLanguage extends string> = Partial<Record<TLanguage, StringsCollection<TStringKey>>>;
-/**
- * Mapping of language codes to their respective languages
- */
-export type LanguageCodeCollection<TLanguage extends string> = Partial<Record<TLanguage, string>>;
-/**
- * Mapping of enumeration values to their translations in multiple languages
- */
-export type EnumTranslationMap<TEnum extends string | number, TLanguage extends string> = Partial<Record<TLanguage, Partial<Record<TEnum, string>>>>;
-/**
- * I18n configuration interface
- */
-export interface I18nConfig<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TTranslationContext extends string = LanguageContext> {
-    stringNames: TStringKey[];
-    strings: MasterStringsCollection<TStringKey, TLanguage>;
-    defaultLanguage: TLanguage;
-    defaultTranslationContext: TTranslationContext;
-    defaultCurrencyCode: CurrencyCode;
-    languageCodes: LanguageCodeCollection<TLanguage>;
-    languages: TLanguage[];
-    constants?: TConstants;
-    enumName?: string;
-    enumObj?: Record<string, TStringKey>;
-    timezone: Timezone;
-    adminTimezone: Timezone;
-}
-/**
- * I18n context interface
- */
-export interface I18nContext<TLanguage extends string, TTranslationContext extends string = LanguageContext> {
-    language: TLanguage;
-    adminLanguage: TLanguage;
-    currencyCode: CurrencyCode;
-    currentContext: TTranslationContext;
-    timezone: Timezone;
-    adminTimezone: Timezone;
-}
-/**
- * Generic translation type for any enumeration
- */
-export type EnumTranslation<T extends string | number> = {
-    [K in T]: string;
-};
-/**
- * Generic language translation type for any enumeration
- */
-export type EnumLanguageTranslation<T extends string | number, TLanguage extends string = string> = Partial<{
-    [L in TLanguage]: EnumTranslation<T>;
-}>;
-/**
- * Helper function to create typed translations for an enumeration
- */
-export declare function createTranslations<T extends string | number, TLanguage extends string>(translations: EnumLanguageTranslation<T, TLanguage>): EnumLanguageTranslation<T, TLanguage>;

package/dist/src/types.js

@@ -1,14 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultCurrencyCode = void 0;
-exports.createTranslations = createTranslations;
-/**
- * Default currency code
- */
-exports.DefaultCurrencyCode = 'USD';
-/**
- * Helper function to create typed translations for an enumeration
- */
-function createTranslations(translations) {
-    return translations;
-}