reslib 2.0.3 → 2.1.1

package/build/i18n/index.d.ts

@@ -1,648 +1,484 @@
-import { Observable, ObservableCallback } from '../observable';
-import { Dict, I18n as I18nJs, I18nOptions, Scope, TranslateOptions } from 'i18n-js';
 import { LocaleSpecification } from 'moment';
 import 'reflect-metadata';
-import { I18nEvent, I18nTranslation } from '../types/i18n';
 import { ClassConstructor, Dictionary } from '../types/index';
-/**
-* A decorator to attach metadata to properties or methods for translation.
-* @param key The translation key in the translations.
-* @returns A property and method decorator.
-* @example
-* ```ts
-*   // Class with translations using the decorator
-    class MyComponent {
-        @Translate("greeting")
-        public greeting: string;
-
-        @Translate("nested.example")
-        public nestedExample: string;
-
-        @Translate("farewell")
-        public sayGoodbye(): string {
-            return "";
-        }
-    }
-* ```
-*/
-export declare function Translate(key: string): PropertyDecorator & MethodDecorator;
-/**
- * The I18n class extends the i18n-js library to provide internationalization (i18n)
- * functionality with observable capabilities. It manages translations, allows for
- * dynamic loading of language dictionaries, and supports event-driven architecture
- * through observable patterns.
- *
- * @extends I18nJs
- * @implements Observable<I18nEvent>
- *
- * @example
- * // Example usage of the I18n class
- * const i18nInstance = I18n.getInstance();
- * i18nInstance.registerTranslations({
- *   en: {
- *     greeting: "Hello, %{name}!",
- *     farewell: "Goodbye!",
- *   },
- * });
- * console.log(i18nInstance.translate("greeting", { name: "John" })); // Outputs: Hello, John!
- * @see https://www.npmjs.com/package/i18n-js?activeTab=readme for more information on i18n-js library.
- */
-export declare class I18n extends I18nJs implements Observable<I18nEvent> {
+import { I18nFormatter, I18nNamespaceResolver, I18nScope, I18nTranslateOptions, I18nTranslations } from './types';
+export declare class I18n {
+    constructor(translations?: I18nTranslations, options?: Partial<I18nOptions>);
     /**
-     * Custom instanceof check. When consumers import `I18n` from built packages or
-     * across module boundaries, class identity can differ. Using Symbol.hasInstance
-     * allows `instanceof I18n` to succeed if the object has the required i18n API
-     * shape (duck typing). This preserves `instanceof` checks externally while
-     * keeping the current exported API intact.
+     * Custom instanceof check. Checks if an object looks like an I18n instance.
+     * @param obj The object to check.
      */
     static [Symbol.hasInstance](obj: any): obj is I18n;
     /**
      * Type guard to check if an object is an instance of I18n.
-     * Uses duck typing to verify the object has the required i18n methods,
-     * allowing for cross-realm compatibility when instanceof checks fail.
+     * Uses duck typing.
      * @param obj The object to check.
-     * @returns True if the object is an I18n instance, false otherwise.
      */
     static isI18nInstance(obj: any): obj is I18n;
     /**
-     * Translates the given scope with the provided options.
-     * If the scope is a string and the options include pluralization, the method will pluralize the translation.
-     * Otherwise, it will call the parent `translate` method.
-     * @param scope The translation scope.
-     * @param options The translation options, including pluralization.
-     * @returns The translated string or the type specified in the generic parameter.
-     * @example
-     * // Register translations for the "en" locale.
-     * i18n.registerTranslations({
-     *   en: {
-     *     greeting: {
-     *       one: "Hello, %{name}!",
-     *       other: "Hello, %{name}s!",
-     *       zero: "Hello, %{name}s!"
-     *     },
-     *     farewell: "Goodbye!"
-     *   }
-     * });
+     * Retrieves the singleton instance of the I18n class.
+     * @param options Optional configuration options.
+     * @returns The singleton I18n instance.
+     */
+    static getInstance(options?: Partial<I18nOptions>): I18n;
+    /**
+     * Factory method to create new I18n instances dynamically.
+     * @param translations Initial translations.
+     * @param options Configuration options.
+     * @returns A new I18n instance.
+     */
+    static createInstance(translations?: I18nTranslations, options?: Partial<I18nOptions>): I18n;
+    /**
+     * Flattens a nested object into a single-level object with dot-notation keys.
+     * @param obj Object to flatten.
+     */
+    static flattenObject(obj: any): Dictionary;
+    /**
+     * Retrieves the user's locale from the active session.
+     * @returns The locale string if found, otherwise `undefined`.
+     */
+    static getLocaleFromSession(): string | undefined;
+    /**
+     * Registers a custom Moment.js locale specification.
      *
-     * // Translate the "greeting" scope with pluralization.
-     * i18n.translate("greeting", { count: 1 }); // "Hello, John!"
-     * i18n.translate("greeting", { count: 2 }); // "Hello, Johns!"
-     * i18n.translate("greeting", { count: 0 }); // "Hello, Johns!"
+     * This allows defining locale-specific date/time formatting rules (months, weekdays, etc.)
+     * that will be applied when the locale is active.
      *
-     * // Translate the "farewell" scope.
-     * i18n.translate("farewell"); // "Goodbye!"
+     * @param locale - The locale code (e.g., "fr").
+     * @param momentLocale - The Moment.js locale specification object.
+     * @returns The updated dictionary of registered moment locales.
      */
-    translate<T = string>(scope: Scope, options?: TranslateOptions): string | T;
-    /***
-     * Translates the keys of the given target class.
-     * @param target The target class.
-     * @param options The translation options.
-     * @returns The translated keys.
+    static registerMomentLocale(locale: string, momentLocale: LocaleSpecification): Record<string, LocaleSpecification>;
+    /**
+     * Retrieves translation keys defined via `@Translate` decorators on a class.
+     *
+     * @template T - The class constructor type.
+     * @param target - The class to inspect.
+     * @returns A record of property names to translation keys.
      */
-    translateClass<T extends ClassConstructor>(target: T, options?: TranslateOptions): Record<keyof T, string>;
+    static getClassTanslationKeys<T extends ClassConstructor>(target: T): Record<keyof InstanceType<T>, string>;
     /**
-     * Translates an object containing translation keys as values.
-     * This method takes an object where each property value is expected to be a translation key,
-     * and returns a new object with the same structure but with translated values.
+     * Optional custom interpolation function.
      *
-     * @template T - The type of the input object, extending Record<string, string>
-     * @param object - The object containing translation keys as values to be translated
-     * @param {TranslateOptions} options - additional options to pass to the i18n.translate function
-     * @returns A new object with the same keys but translated values
+     * If provided, this function handles the replacement of placeholders in the translation string.
+     * It overrides the default `%{key}` interpolation.
      *
-     * @example
-     * ```typescript
-     * // Register translations first
-     * i18n.registerTranslations({
-     *   en: {
-     *     'user.name': 'Name',
-     *     'user.email': 'Email Address',
-     *     'user.phone': 'Phone Number',
-     *     'actions.save': 'Save',
-     *     'actions.cancel': 'Cancel'
-     *   },
-     *   fr: {
-     *     'user.name': 'Nom',
-     *     'user.email': 'Adresse Email',
-     *     'user.phone': 'Numéro de Téléphone',
-     *     'actions.save': 'Enregistrer',
-     *     'actions.cancel': 'Annuler'
-     *   }
-     * });
+     * @param i18n - The I18n instance.
+     * @param str - The string to interpolate.
+     * @param params - The interpolation parameters.
+     * @returns The interpolated string.
+     */
+    interpolateFunc?: (i18n: I18n, str: string, params: Dictionary) => string;
+    /**
+     * Callback for handling missing placeholders/keys.
      *
-     * // Define an object with translation keys
-     * const formLabels = {
-     *   name: 'user.name',
-     *   email: 'user.email',
-     *   phone: 'user.phone'
-     * };
+     * If defined, this function is called when a translation key (or placeholder) is not found.
+     * It provides a hook to log warnings, report errors, or provide custom fallback text.
      *
-     * // Translate the object
-     * const translatedLabels = i18n.translateObject(formLabels);
-     * console.log(translatedLabels);
-     * // Output (for 'en' locale): { name: 'Name', email: 'Email Address', phone: 'Phone Number' }
-     * // Output (for 'fr' locale): { name: 'Nom', email: 'Adresse Email', phone: 'Numéro de Téléphone' }
+     * @param i18n - The I18n instance.
+     * @param placeholder - The missing key or placeholder.
+     * @param message - The default message/fallback.
+     * @param options - Context options.
+     */
+    missingPlaceholder?: (i18n: I18n, placeholder: string, message: string, options?: Dictionary) => string;
+    /**
+     * Translates a single key or a list of keys with support for pluralization and interpolation.
      *
-     * // Can also be used with button configurations
-     * const buttonConfig = {
-     *   saveButton: 'actions.save',
-     *   cancelButton: 'actions.cancel'
-     * };
-     * const translatedButtons = i18n.translateObject(buttonConfig);
-     * // Output (for 'en' locale): { saveButton: 'Save', cancelButton: 'Cancel' }
-     * ```
+     * This is the core method for retrieving localized strings. It executes the following logic:
+     * 1. **Key Resolution**: Searches for the key in the current locale. If not found, checks for a fallback locale.
+     * 2. **Fallback**: If the key is missing, looks for `options.defaultValue` or follows the missing key strategy (returns key).
+     * 3. **Pluralization**: If `options.count` is provided, it attempts to find and return the pluralized form (zero, one, other).
+     * 4. **Interpolation**: Replaces placeholders (e.g. `%{name}`) with values from `options`.
      *
-     * @example
-     * ```typescript
-     * // Advanced usage with form validation messages
-     * const validationMessages = {
-     *   required: 'validation.required',
-     *   email: 'validation.email.invalid',
-     *   minLength: 'validation.minLength',
-     *   maxLength: 'validation.maxLength'
-     * };
+     * @template T - The expected return type (defaults to `string`).
+     * @param scope - The translation key (e.g. "auth.login") or an array of keys to try in order.
+     * @param options - Configuration options (interpolation params, `count` for pluralization, `locale`, etc).
+     * @returns The resolved translation string (or type `T`), interpolated and formatted.
      *
-     * // Assuming you have registered validation translations
-     * const translatedValidation = i18n.translateObject(validationMessages);
-     * // This allows you to easily get all validation messages in the current locale
-     * ```
+     * @example
+     * // Basic
+     * i18n.translate("welcome");
      *
-     * @note If the input object is not a valid object, an empty object of type T is returned.
-     * @note Only string values that are non-null and non-empty are translated; other values are skipped.
-     * @note This method is particularly useful for translating configuration objects, form labels,
-     *       button texts, or any structured data containing translation keys.
+     * @example
+     * // Interpolation & Pluralization
+     * i18n.translate("messages.inbox", { count: 3, user: "Alice" });
+     * // "Alice, you have 3 messages"
+     */
+    translate<T = string>(scope: I18nScope, options?: I18nTranslateOptions): T;
+    /**
+     * An alias for `translate`.
      *
-     * @see {@link translateClass} for translating class properties decorated with @Translate
-     * @see {@link t} for translating individual keys with interpolation support
+     * A concise helper method for calling {@link translate}.
      *
+     * @see {@link translate}
+     * @param scope - The translation key or keys.
+     * @param options - Translation options.
+     * @returns The translated result.
      */
-    translateObject<T extends Record<string, string>>(object: T, options?: TranslateOptions): T;
-    /***
-     * returns the translation keys for the target class
-     * @param target the target class
-     * @returns the translation keys for the target class
-     */
-    static getClassTanslationKeys<T extends ClassConstructor>(target: T): Record<keyof T, string>;
-    private _isLoading;
-    /***
-     * locales that are superted by the i18n instance
+    t(scope: I18nScope, options?: I18nTranslateOptions): string;
+    /**
+     * Checks if a translation key exists in the store.
+     *
+     * @param scope - The key or array of keys to check.
+     * @param locale - Optional locale to check in (defaults to current).
+     * @returns `true` if the translation exists, `false` otherwise.
      */
-    private _locales;
+    has(scope: I18nScope, locale?: string): boolean;
     /**
-     * Namespace resolvers for loading translations.
+     * Gets the currently active locale.
+     * @returns The language code of the current locale (e.g. "en").
      */
-    private namespaceResolvers;
+    getLocale(): string;
     /**
-     * Singleton instance of the I18n class.
+     * Sets the active locale and triggers necessary updates.
+     *
+     * This method performs several actions:
+     * 1. Loads required namespaces for the new locale (if resolvers are registered).
+     * 2. Updates the internal `locale` state.
+     * 3. Persists the locale to the session (if default instance).
+     * 4. Updates the global Moment.js locale.
+     *
+     * @param locale - The new locale to set.
+     * @param forceUpdate - If true, reloads namespaces even if the locale is already active.
+     * @returns A promise that resolves to the new locale string.
      */
-    private static instance;
+    setLocale(locale: string, forceUpdate?: boolean): Promise<string>;
     /**
-     * Creates an instance of the I18n class.
-     * @param options Optional configuration options for the I18n instance.
-     */
-    constructor(translations?: I18nTranslation, options?: Partial<I18nOptions>);
-    readonly _observableFactory: {
-        _____isObservable?: boolean;
-        on: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        finally: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        off: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        trigger: (event: "*" | I18nEvent, ...args: any[]) => /*elided*/ any;
-        offAll: () => /*elided*/ any;
-        once: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        getEventCallBacks: () => Partial<Record<"*" | I18nEvent, ObservableCallback[]>>;
-    };
-    readonly _____isObservable?: boolean | undefined;
-    /**
-     * Subscribes a callback function to a specific event.
-     * @param event The event name to listen for.
-     * @param fn The callback function to be invoked when the event is triggered.
-     * @returns An object containing a remove method to unsubscribe from the event.
-     */
-    on(event: I18nEvent, fn: ObservableCallback): {
-        remove: () => any;
-    };
-    /**
-     * Registers a callback to be invoked finally when an event is triggered.
-     * @param event The event name.
-     * @param fn The callback function to be invoked.
-     * @returns The observable instance.
-     */
-    finally(event: I18nEvent, fn: ObservableCallback): {
-        _____isObservable?: boolean;
-        on: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        finally: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        off: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        trigger: (event: "*" | I18nEvent, ...args: any[]) => /*elided*/ any;
-        offAll: () => /*elided*/ any;
-        once: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        getEventCallBacks: () => Partial<Record<"*" | I18nEvent, ObservableCallback[]>>;
-    };
-    /**
-     * Unsubscribes a callback from a specific event.
-     * @param event The event name.
-     * @param fn The callback function to remove.
-     * @returns The observable instance.
-     */
-    off(event: I18nEvent, fn: ObservableCallback): {
-        _____isObservable?: boolean;
-        on: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        finally: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        off: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        trigger: (event: "*" | I18nEvent, ...args: any[]) => /*elided*/ any;
-        offAll: () => /*elided*/ any;
-        once: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        getEventCallBacks: () => Partial<Record<"*" | I18nEvent, ObservableCallback[]>>;
-    };
-    /**
-     * Triggers a specific event with optional arguments.
-     * @param event The event name to trigger.
-     * @param args Optional arguments to pass to the event callbacks.
-     * @returns The observable instance.
-     */
-    trigger(event: I18nEvent | '*', ...args: any[]): {
-        _____isObservable?: boolean;
-        on: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        finally: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        off: (event: I18nEvent, fn: ObservableCallback) => /*elided*/ any;
-        trigger: (event: "*" | I18nEvent, ...args: any[]) => /*elided*/ any;
-        offAll: () => /*elided*/ any;
-        once: (event: I18nEvent, fn: ObservableCallback) => {
-            remove: () => any;
-        };
-        getEventCallBacks: () => Partial<Record<"*" | I18nEvent, ObservableCallback[]>>;
-    };
-    /**
-     * Unsubscribes all event callbacks for this component.
-     * @returns The observable instance.
-     */
-    offAll(): Observable<I18nEvent>;
-    /**
-     * Subscribes a callback function to be triggered once for a specific event.
-     * @param event The event name.
-     * @param fn The callback function to be invoked.
-     * @returns An object containing a remove method to unsubscribe from the event.
-     */
-    once(event: I18nEvent, fn: ObservableCallback): {
-        remove: () => any;
-    };
-    /**
-     * Retrieves all registered event callbacks.
-     * @returns An object mapping event names to their respective callback functions.
-     */
-    getEventCallBacks(): Partial<Record<"*" | I18nEvent, ObservableCallback[]>>;
+     * Defines the list of supported locales.
+     *
+     * Ensures that "en" (default) is always included in the supported list.
+     *
+     * @param locales - An array of locale codes.
+     * @returns The updated list of supported locales.
+     */
+    setLocales(locales: string[]): string[];
     /**
-     * Retrieves the singleton instance of the I18n class.
-     * @returns The singleton I18n instance.
+     * Retrieves all available locales.
+     *
+     * Combines the explicitly supported locales (set via `setLocales`) with any
+     * locales discovered in the loaded translation store.
+     *
+     * @returns A unique list of all known locale codes.
      */
-    static getInstance(options?: I18nOptions): I18n;
-    /***
-     * returns true if the instance is the default instance.
-     * @returns true if the instance is the default instance.
+    getLocales(): string[];
+    /**
+     * Checks if a specific locale is supported and known.
+     *
+     * @param locale - The locale code to check.
+     * @returns `true` if the locale is in the supported/available list.
      */
+    hasLocale(locale: string): boolean;
     isDefaultInstance(): boolean;
-    private static setLocaleToSession;
-    static getLocaleFromSession(): any;
-    /**
-     * Checks if the provided translation key can be pluralized for the given locale.
-     * @param scope The translation scope to check.
-     * @param locale The locale to use for the check. If not provided, the current locale is used.
-     * @returns `true` if the translation key can be pluralized, `false` otherwise.
-     * @note This method is useful for determining if a translation key can be pluralized for a specific locale.
-     * A translation key can be pluralized if it has pluralization rules defined in the translation dictionary.
-     * The pluralization rules are defined in the `one`, `other`, and `zero` properties of the translation dictionary.
+    /**
+     * Registers and merges new translations into the global store.
+     *
+     * This method merges the provided translation object with the existing translations.
+     * New keys are added, and existing keys are updated (overwritten).
+     *
+     * @param translations - The translations to register, grouped by locale.
+     * @returns The updated translation store.
+     *
      * @example
-     * //register a translation dictionary for the "en" locale.
      * i18n.registerTranslations({
-     *   en: {
-     *     greeting: {
-     *       one: "Hello, {name}!",
-     *       other: "Hello, {name}s!",
-     *       zero: "Hello, {name}s!"
-     *     },
-     *     farewell: "Goodbye!"
-     *   }
-     * );
+     *   en: { title: "Welcome" },
+     *   fr: { title: "Bienvenue" }
      * });
-     * // Check if the translation key "greeting" can be pluralized for the current locale.
-     * i18n.canPluralize("greeting");
-     *
-     * // Check if the translation key "greeting" can be pluralized for the "en" locale.
-     * i18n.canPluralize("greeting", "en");
-     * i18n.canPluralize("greeting", "fr"); // returns false
-     * i18n.canPluralize("farewell", "en"); // returns false
      */
-    canPluralize(scope: Scope, locale?: string): boolean;
+    registerTranslations(translations: I18nTranslations): I18nTranslations;
     /**
-     * Checks if the provided translation key exists for the given locale.
-     * @since 1.1.1
-     * @param scope The translation scope to check.
-     * @param locale The locale to use for the check. If not provided, the current locale is used.
-     * @returns `true` if the translation key exists, `false` otherwise.
+     * Retrieves specific translations or the entire store.
+     *
+     * @param locale - The locale to retrieve translations for. If omitted, returns the entire store.
+     * @returns A dictionary of translations (for a locale) or the full store (if no locale provided).
      */
-    has(scope: Scope, locale?: string): boolean;
+    getTranslations(locale?: string): Dictionary;
     /**
-     * Resolves translation for nested keys.
-     * @param scope {Scope} The translation scope.
-     * @param locale The locale to use for translation.
-     * @returns The translated string or undefined if not found.
-     * @example
-     * // Register translations for the "en" locale.
-     * i18n.registerTranslations({
-     *   en: {
-     *     greeting: {
-     *       one: "Hello, {name}!",
-     *       other: "Hello, {name}s!",
-     *       zero: "Hello, {name}s!"
-     *     },
-     *     farewell: "Goodbye!"
-     *   }
-     * });
-     *
-     * // Resolve translation for the "greeting" key.
-     * i18n.getNestedTranslation("greeting.one", "en");
-     *
-     * // Resolve translation for the "greeting" key.
-     * i18n.getNestedTranslation("greeting.other", "en");
+     * Registers a function to lazily load translations for a specific namespace.
      *
-     * // Resolve translation for the "greeting" key.
-     * i18n.getNestedTranslation("en", "greeting.zero", 0);
+     * The resolver function is called when `loadNamespace` is invoked. It should return
+     * a promise resolving to a dictionary of translations.
      *
-     * // Resolve translation for the "farewell" key.
-     * i18n.getNestedTranslation("en", "farewell");
+     * @param {string} namespace - The unique name of the namespace.
+     * @param {I18nNamespaceResolver} resolver - The async function that fetches translations.
      */
-    getNestedTranslation<T = string | Dictionary>(scope: Scope, locale?: string): T | undefined;
+    registerNamespaceResolver(namespace: string, resolver: I18nNamespaceResolver): void;
     /**
-     * Checks if the provided `TranslateOptions` object has a `count` property of type `number`.
-     * This is used to determine if the translation should be pluralized based on the provided count.
-     * @param options The `TranslateOptions` object to check.
-     * @returns `true` if the `options` object has a `count` property of type `number`, `false` otherwise.
+     * Loads translations for a specific namespace and merges them into the store.
+     *
+     * @param namespace - The namespace to load.
+     * @param locale - The locale to load for (defaults to current).
+     * @param updateTranslations - If true, automatically registers the loaded translations.
+     * @returns A promise resolving to the dictionary of loaded translations.
      */
-    isPluralizeOptions(options?: TranslateOptions): options is TranslateOptions;
-    /**
-       * static function to attach translations to the I18n default instance.
-          @example :
-          // --- Usage as a decorator ---
-          I18n.RegisterTranslations({
-              de: {
-                  greeting: "Hallo, {name}!",
-                  farewell: "Auf Wiedersehen!",
-              },
-          })
-      * @param translations The language translations.
-      */
-    static RegisterTranslations(translations: I18nTranslation): I18nTranslation;
+    loadNamespace(namespace: string, locale?: string, updateTranslations?: boolean): Promise<Dictionary>;
     /**
-     * Factory method to create I18n instances dynamically.
-     * @param options Optional configuration options for the I18n instance.
-     * @returns A new I18n instance.
+     * Loads all registered namespaces for a specific locale.
+     *
+     * Executes all registered namespace resolvers concurrently.
+     *
+     * @param locale - The locale to load.
+     * @param updateTranslations - If true, updates the store with results.
+     * @returns A promise resolving to the combined translations from all namespaces.
      */
-    static createInstance(translations?: I18nTranslation, options?: Partial<I18nOptions> & {
-        interpolate?: (i18n: I18nJs, str: string, params: Dictionary) => string;
-    }): I18n;
+    loadNamespaces(locale?: string, updateTranslations?: boolean): Promise<I18nTranslations>;
     /**
-     * Gets the translations for the specified locale, or all translations if no locale is provided.
-     * @param locale The locale to get translations for. If not provided, returns all translations.
-     * @returns The translations for the specified locale, or all translations if no locale is provided.
+     * Retrieves a raw translation value or object from the store for a specific scope and locale.
+     *
+     * This method provides direct access to the translation structure without performing
+     * interpolation, pluralization, or missing key fallbacks. It strictly traverses
+     * the object tree based on the provided dot-separated scope or array path.
+     *
+     * It is particularly useful for:
+     * - Retrieving entire sections of translations (e.g., a dictionary of validation messages).
+     * - Accessing lists/arrays defined in the localization files.
+     * - Checking if a specific key or branch exists in the store.
+     *
+     * Key Resolution:
+     * - Dots in the scope string are ALWAYS treated as separators (traversal).
+     * - To match keys containing literal dots, use `lookup` internally or ensure your store structure matches.
+     *
+     * @template T - The expected return type (defaults to `string | Dictionary`).
+     * @param scope - The path to the value. Can be a dot-separated string (e.g., "auth.login.title")
+     *                or an array of keys (e.g., ["auth", "login"]).
+     * @param locale - The locale to search in. Defaults to the current instance locale if omitted.
+     * @returns The value at the specified path cast to `T`, or `undefined` if resolution fails.
+     *
      * @example
-     * // Get all translations
-     * const translations = i18n.getTranslations();
-     * console.log(translations);
+     * // Get a simple string
+     * const title = i18n.get("app.title");
      *
-     * // Get translations for the "en" locale
-     * const enTranslations = i18n.getTranslations("en");
-     * console.log(enTranslations);
-     */
-    getTranslations(locale?: string): any;
-    /***
-     * list of registered moment locales
-     */
-    private static momentLocales;
-    private hasRegisteredDefaultTranslations;
-    /***
-     * register a moment locale
-     * @param {string} locale
-     * @param {LocaleSpecification} momentLocale
-     * @see https://momentjs.com/docs/#/customization/ for more information on customizing moment locales
-     * @see https://momentjs.com/docs/#/i18n/ for more information on moment locales
-     * @returns
-     */
-    static registerMomentLocale(locale: string, momentLocale: LocaleSpecification): Record<string, LocaleSpecification>;
-    /***
-     * get a registered moment locale
-     * @param {string} locale
-     * @returns {LocaleSpecification}
-     */
-    static getMomentLocale(locale: string): LocaleSpecification;
-    /***
-     * set a moment locale. the locale is picked from the momentLocales list
-     * @param {string} locale
-     * @param {Moment} momentInstance, The moment instance to set the locale on
-     * @returns {boolean}
+     * @example
+     * // Get a full dictionary object
+     * const validationMessages = i18n.get<Dictionary>("validation");
+     * // Result: { required: "Field is required", email: "Invalid email" }
+     *
+     * @example
+     * // Get from a specific locale (e.g. 'fr')
+     * const label = i18n.get("button.submit", "fr");
      */
-    static setMomentLocale(locale: string): boolean;
+    get<T = string | Dictionary>(scope: I18nScope, locale?: string): T | undefined;
     /**
-     * Registers translations into the I18n manager.
-     * @param translations The translations to register.
-     * @returns The updated translations.
+     * Resolves and translates properties decorated with `@Translate` on a specific class.
+     *
+     * This method uses reflection to find properties on the `target` that have been decorated
+     * with the `@Translate` decorator. It retrieves the translation keys stored in the metadata,
+     * translates them using the current locale and options, and returns a mapped object.
+     *
+     * **Note**: This does NOT modify the class itself. It returns a separate object containing
+     * the translated values for the decorated properties.
+     *
+     * Use Cases:
+     * - Fetching all localized labels for a specific component or form class.
+     * - aggregating static translation requirements for a module.
+     *
+     * @template T - The constructor type of the target class.
+     * @param target - The class constructor to inspect for `@Translate` decorators.
+     * @param options - Optional translation options (arguments, locale) to apply to all keys.
+     * @returns A dictionary mapping the property names to their translated string values.
+     *
+     * @example
+     * class AuthForm {
+     *   @Translate("auth.title")
+     *   static formTitle: string;
+     *
+     *   @Translate("auth.submit")
+     *   static submitBtn: string;
+     * }
+     *
+     * const texts = i18n.translateClass(AuthForm);
+     * // Returns: { formTitle: "Login", submitBtn: "Sign In" }
      */
-    registerTranslations(translations: I18nTranslation): I18nTranslation;
+    translateClass<T extends ClassConstructor>(target: T, options?: I18nTranslateOptions): Record<keyof InstanceType<T>, string>;
     /**
-     * Stores the provided translations and triggers a "translations-changed" event with the current locale and translations.
-     * @param translations The translations to store.
+     * Translates the string values of a given object, treating them as translation keys.
+     *
+     * This method iterates over the provided object's properties. If a property value is a string,
+     * it treats that string as a translation scope (key) and attempts to translate it using the
+     * current or specified locale.
+     *
+     * Key Behaviors:
+     * - **Shallow Processing**: It processes only the top-level properties of the object. It does not recurse into nested objects.
+     * - **Immutability**: It returns a new object with the translated values, ensuring the original object remains unmodified.
+     * - **Type Safety**: It is typed to accept objects where values are strings (translation keys).
+     * - **Filtering**: Only non-null string values are processed and included in the result. Non-string values are omitted.
+     *
+     * Use cases:
+     * - specific dictionaries of labels (e.g. for dropdown options or map keys).
+     * - Batch translating a set of related keys.
+     *
+     * @template T - The type of the object (must extend Record<string, string>).
+     * @param object - The object containing translation keys as values.
+     * @param options - Optional translations options (e.g., interpolation parameters) that will be applied to EVERY translation in the object.
+     * @returns A new object with the same keys but translated values.
+     *
+     * @example
+     * const keys = {
+     *   welcome: "app.welcome",
+     *   goodbye: "app.goodbye"
+     * };
+     *
+     * const texts = i18n.translateObject(keys);
+     * // Returns: { welcome: "Welcome!", goodbye: "Goodbye!" }
+     *
+     * @example
+     * // Using interpolation parameters for all keys
+     * const keys = { msg: "alerts.user_msg" }; // "alerts.user_msg" -> "User: %{user}"
+     * const result = i18n.translateObject(keys, { user: "Bob" });
+     * // Returns: { msg: "User: Bob" }
      */
-    store(translations: Dict): void;
+    translateObject<T extends Record<string, string>>(object: T, options?: I18nTranslateOptions): T;
     /**
-     * Automatically resolves translations using reflect Metadata.
-     * Translations created using the @Translate decorator will be resolved.
-     * @param target The target class instance or object.
+     * Applies translations to the decorated properties of a target object instance.
+     *
+     * This method performs a lookup for properties on the `target` object that have been
+     * decorated with `@Translate`. For each such property, it resolves the translation
+     * using the stored key and overwrites the property's value on the instance.
+     *
+     * **Side Effect Warning**: This method **mutates** the `target` object in place.
+     *
+     * Use Cases:
+     * - Hydrating a component instance with localized strings after initialization or locale change.
+     * - Converting a DTO with annotated fields into a display-ready object.
+     *
+     * @template T - The type of the target object.
+     * @param target - The object instance to apply translations to.
+     *
      * @example
-     * // Class with translations using the decorator
-     * class MyComponent {
-     *     @Translate("greeting")
-     *     public greeting: string;
-     *
-     *     @Translate("nested.example")
-     *     public nestedExample: string;
-     *
-     *     @Translate("farewell")
-     *     public sayGoodbye(): string {
-     *         return "";
-     *     }
+     * class Page {
+     *   @Translate("page.title")
+     *   title: string = "";
      * }
-     * // Resolve translations and print them
-     * const component = new MyComponent();
-     * I18n.getInstance().resolveTranslations(component);
-     */
-    resolveTranslations<T extends object>(target: T): void;
-    /***
-     * returns the missing placeholder string for the given placeholder and message.
-     * @param placeholder - The placeholder to be replaced.
-     * @param message - The message to be displayed.
-     * @param options - The options for the missing placeholder string.
-     * @returns The missing placeholder string.
+     *
+     * const page = new Page();
+     * i18n.applyTranslations(page);
+     * console.log(page.title); // "My Page Title"
      */
-    getMissingPlaceholderString(placeholder: string, message?: string, options?: I18nTranslation): string;
+    applyTranslations<T extends object>(target: T): void;
     /**
-     * Gets the current locale for the i18n instance.
-     * @returns {string} The current locale.
+     * The current locale.
      */
-    getLocale(): string;
+    private locale;
     /**
-     * Sets the list of supported locales for the i18n instance.
-     * @param locales - An array of locale strings to set as the supported locales.
-     * @returns The list of all locales supported by the i18n instance, including both the locales for which translations are available and the locales explicitly set as supported.
+     * Supported locales.
      */
-    setLocales(locales: string[]): string[];
-    /***
-     * returns true if the locale is supported by a i18n instance.
-     * @param locale - The locale to check.
-     * @returns true if the locale is supported, false otherwise.
+    private _locales;
+    /**
+     * Fallback locale.
      */
-    hasLocale(locale: string): boolean;
+    private _fallbackLocale;
     /**
-     * Gets the list of all locales supported by the i18n instance, including both the locales for which translations are available and the locales explicitly set as supported.
-     * @returns {string[]} The list of all supported locales.
+     * Dictionary of translations: { locale: { key: "value", ... } }
      */
-    getLocales(): string[];
-    /***
-     * returns true if the locale is supported by the i18n instance.
-     * @param locale - The locale to check.
-     * @returns true if the locale is supported, false otherwise.
-     */
-    isLocaleSupported(locale: string): boolean;
-    /***
-     * returns true if the instance is loading translations.
-     * @returns true if the instance is loading translations, false otherwise.
-     * @example
-     * // Check if the instance is loading translations.
-     * i18n.isLoading();
+    private _translations;
+    /**
+     * Namespace resolvers.
      */
-    isLoading(): boolean;
+    private namespaceResolvers;
     private _namespacesLoaded;
-    setLocale(locale: string, forceUpdate?: boolean): Promise<string>;
+    private _hasDefaultTranslations;
     /**
-     * Register a namespace resolver.
-     * @param namespace The namespace to register.
-     * @param resolver The resolver function to load the namespace.
-     * @example
-     * // Register a namespace resolver for the "common" namespace.
-     * i18n.registerNamespaceResolver("common", async (locale) => {
-     *   const response = await fetch(`/i18n/${locale}/common.json`);
-     *   return await response.json();
-     * });
+     * Singleton instance of the I18n class.
      */
-    registerNamespaceResolver(namespace: string, resolver: (locale: string) => Promise<I18nTranslation>): void;
+    private static instance;
     /**
-     * Static method to register a namespace resolver to the I18n default instance.
-     * @param namespace, The namespace to register.
-     * @param resolver, The resolver function to load the namespace.
-     * @returns
-     * @example
-     * // Register a namespace resolver for the "common" namespace.
-     * I18n.RegisterNamespaceResolver("common", async (locale) => {
-     *   const response = await fetch(`/i18n/${locale}/common.json`);
-     *   return await response.json();
-     * });
+     * Fallback method when translation is missing.
      */
-    static RegisterNamespaceResolver(namespace: string, resolver: (locale: string) => Promise<any>): void;
-    loadNamespace(namespace: string, locale?: string, updateTranslations?: boolean): Promise<I18nTranslation>;
-    static LoadNamespace(namespace: string, locale?: string, updateTranslations?: boolean): Promise<I18nTranslation>;
-    loadNamespaces(locale?: string, updateTranslations?: boolean): Promise<I18nTranslation>;
-    /***
-     * Load all registered namespaces for the current locale on the I18n default instance.
-     * @param locale optional locale to load the namespaces for
-     * @param updateTranslations optional boolean to update the translations
-     * @returns {Promise<I18nTranslation>} A promise that resolves to the combined translations for the current local
+    private missingTranslation;
+    private static momentLocales;
+    /**
+     * Lookup a key in the translations for a locale.
+     * Supports dot notation 'a.b.c'.
      */
-    static LoadNamespaces(locale?: string, updateTranslations?: boolean): Promise<I18nTranslation>;
+    private lookup;
     /**
-     * Flattens a nested object into a single-level object with dot-notation keys.
-     *
-     * This utility method transforms complex nested objects into flat key-value pairs,
-     * where nested properties are represented using dot notation (e.g., `user.name`).
-     * This is particularly useful for interpolation processes that need to access
-     * nested values using simple string keys.
-     *
-     * @param obj - The object to flatten. Can be any type.
-     * @returns A flattened object where nested properties are accessible via dot-notation keys,
-     *          or the original input if it's not an object.
-     *
-     * @example
-     * ```typescript
-     * // Basic flattening
-     * const nested = {
-     *   user: {
-     *     name: 'John',
-     *     profile: {
-     *       age: 30,
-     *       city: 'New York'
-     *     }
-     *   },
-     *   settings: { theme: 'dark' }
-     * };
-     *
-     * const flattened = I18n.flattenObject(nested);
-     * // Result: {
-     * //   'user.name': 'John',
-     * //   'user.profile.age': 30,
-     * //   'user.profile.city': 'New York',
-     * //   'settings.theme': 'dark'
-     * // }
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Non-object inputs are returned as-is
-     * I18n.flattenObject("string"); // Returns: "string"
-     * I18n.flattenObject(42); // Returns: 42
-     * I18n.flattenObject(null); // Returns: null
-     * ```
+     * Performs the interpolation on a string.
+     */
+    private performInterpolation;
+    private defaultInterpolator;
+    private static setLocaleToSession;
+    private getMomentLocale;
+    private setMomentLocale;
+}
+declare const i18n: I18n;
+export { i18n };
+/**
+ * A decorator to attach metadata to properties or methods for translation.
+ * @param key The translation key in the translations.
+ * @returns A property and method decorator.
+ * @example
+ * ```ts
+ *   // Class with translations using the decorator
+ *     class MyComponent {
+ *         @Translate("greeting")
+ *         public greeting: string;
+ *
+ *         @Translate("nested.example")
+ *         public nestedExample: string;
+ *
+ *         @Translate("farewell")
+ *         public sayGoodbye(): string {
+ *             return "";
+ *         }
+ *     }
+ * ```
+ */
+export declare function Translate(key: string): PropertyDecorator & MethodDecorator;
+/**
+ * @interface I18nOptions
+ * Options for configuring internationalization (i18n) settings.
+ *
+ * This interface defines the options that can be used to customize
+ * the behavior of the i18n system, including the locale, fallback
+ * locale, and a custom formatter for string values.
+ *
+ * @property {string} locale - The primary locale to use for translations.
+ * @property {string} [fallbackLocale] - An optional fallback locale to use if the primary locale is not available.
+ * @property {I18nFormatter} [formatter] - An optional custom formatter function for formatting strings.
+ *
+ * @example
+ * const i18nOptions: I18nOptions = {
+ *     locale: "en",
+ *     fallbackLocale: "es",
+ *     formatter: (value, params) => value.replace(/{(\w+)}/g, (_, key) => params[key] || '')
+ * };
+ */
+export interface I18nOptions {
+    /**
+     * The primary locale to use for translations.
      *
+     * @type {string}
      * @example
-     * ```typescript
-     * // Usage in interpolation
-     * const params = { user: { firstName: 'John', lastName: 'Doe' } };
-     * const flattened = I18n.flattenObject(params);
-     * // Now flattened can be used for interpolation like:
-     * // "Hello %{user.firstName} %{user.lastName}" -> "Hello John Doe"
-     * ```
-     *
-     * @note This method relies on `Object.flatten()` which should be available
-     *       in the environment. If the input is not an object, it is returned unchanged.
-     * @note Circular references in objects may cause issues during flattening.
-     * @note Arrays are treated as objects and their indices become keys in the flattened result.
-     *
-     * @see {@link defaultInterpolator} for how this method is used in string interpolation.
+     * const currentLocale = i18nOptions.locale; // "en"
      */
-    static flattenObject(obj: any): TranslateOptions;
+    locale: string;
     /**
-     * Provides a default interpolation function for the I18n instance.
-     *
-     * If the input `value` is `undefined` or `null`, an empty string is returned.
-     * If the input `value` is not a number, boolean, or string, it is converted to a string using `stringify`.
-     * If the input `params` is not an object, the `value` is returned as-is.
-     * If the input `params` is an object, the `value` is replaced with any matching placeholders in the format `%{key}` using the corresponding values from the `params` object.
+     * An optional fallback locale to use if the primary locale is not available.
      *
-     * @param i18n The I18n instance.
-     * @param value The input value to be interpolated.
-     * @param params Optional object containing replacement values for placeholders in the `value`.
-     * @returns The interpolated string.
-     */
-    private static defaultInterpolator;
+     * @type {string}
+     * @example
+     * const fallback = i18nOptions.fallbackLocale; // "es"
+     */
+    fallbackLocale?: string;
+    /**
+       * An optional custom formatter function for formatting strings.
+       *
+       * @type {I18nFormatter}
+       * @example
+       * const formattedString = i18nOptions.formatter("Hello, {name}!", { name: "Alice" });
+       * // Outputs: "Hello, Alice!"
+      ```typescript
+       *
+       * @example
+       * const i18nOptions: I18nOptions = {
+       *     locale: "en",
+       *     fallbackLocale: "es",
+       *     formatter: (value, params) => value.replace(/{(\w+)}/g, (_, key) => params[key] || '')
+       * };
+       */
+    formatter?: I18nFormatter;
+    /**
+     * Optional custom interpolation.
+     */
+    interpolate?: (i18n: I18n, str: string, params: Dictionary) => string;
 }
-declare const i18n: I18n;
-export { i18n };
+export * from './types';