@nexim/localizer/dist/main.d.ts

Lightweight i18n utilities to handle translations, number formatting, date/time localization using native browser APIs.

import { UnicodeDigits, type UnicodeLangKeys } from '@alwatr/unicode-digits';
/**
 * Represents a locale code in the format "language-COUNTRY".
 * The language part must be in lowercase, and the country part must be in uppercase.
 *
 * @example "en-US"
 * @example "fr-FR"
 * @example "de-DE"
 */
export type LocaleCode = `${Lowercase<string>}-${Uppercase<string>}`;
/**
 * Represents a locale configuration with language code and language identifier.
 */
export interface Locale {
    /**
     * fa-IR, en-US, ...
     */
    code: LocaleCode;
    /**
     * The ISO 639-1 language code (e.g., 'fa', 'en')
     */
    language: UnicodeLangKeys;
}
/**
 * Provides localization and internationalization functionality.
 *
 * @remarks
 * This class handles number formatting, text translation, date formatting,
 * and relative time calculations based on the specified locale.
 */
export declare class Localizer {
    private options__;
    /**
     * Number formatter instance for formatting numbers according to the locale.
     *
     * @internal
     */
    protected numberFormatter_: Intl.NumberFormat;
    /**
     * UnicodeDigits instance for converting numbers to locale-specific digits.
     *
     * @internal
     */
    protected unicodeDigits_: UnicodeDigits;
    protected logger_: import("@alwatr/logger").AlwatrLogger;
    /**
     * Time units used for relative time calculations.
     * @internal
     */
    static timeUnits_: readonly [{
        readonly label: "year";
        readonly seconds: 31536000;
    }, {
        readonly label: "month";
        readonly seconds: 2592000;
    }, {
        readonly label: "week";
        readonly seconds: 604800;
    }, {
        readonly label: "day";
        readonly seconds: 86400;
    }, {
        readonly label: "hour";
        readonly seconds: 3600;
    }, {
        readonly label: "minute";
        readonly seconds: 60;
    }, {
        readonly label: "second";
        readonly seconds: 1;
    }];
    /**
     * Creates a new instance of the Localizer class.
     *
     * @param options__ - Configuration options for localization
     */
    constructor(options__: {
        locale: Locale;
        resource: DictionaryReq | null;
    });
    /**
     * Retrieves a localized message by key from the resource dictionary.
     *
     * @param key - The key to lookup in the resource dictionary
     * @returns The localized message string
     *
     * @remarks
     * - Returns "\{key\}" if the key is not found in the dictionary
     * - Returns an empty string if the key is null or undefined
     *
     * @example
     * ```typescript
     * const localizer = new Localizer({...});
     * console.log(localizer.message('hello_world')); // "Hello world!"
     * console.log(localizer.message('missing_key')); // "{missing_key}"
     * ```
     */
    message(key: keyof NonNullable<typeof this.options__.resource>): string;
    /**
     * Formats a number according to the current locale settings.
     *
     * @param number - The number to format
     * @param decimal - Number of decimal places (default: 2)
     * @returns Formatted number string using locale-specific formatting
     *
     * @example
     * ```typescript
     * const localizer = new Localizer({...});
     * console.log(localizer.number(1234.567)); // "1,234.57"
     * console.log(localizer.number(1234.567, 1)); // "1,234.6"
     * ```
     */
    number(number?: number | null, decimal?: number): string;
    /**
     * Replaces all numeric digits in a string with their locale-specific Unicode equivalents.
     *
     * @param str - The input string containing numbers to replace
     * @returns String with numbers converted to locale-specific digits
     *
     * @example
     * ```typescript
     * const localizer = new Localizer({locale: {code: 'fa-IR', language: 'fa'}, ...});
     * console.log(localizer.replaceNumber('123')); // '۱۲۳'
     * ```
     */
    replaceNumber(str: string): string;
    /**
     * Formats a date according to the current locale settings.
     *
     * @param date - Date to format (as Date object or timestamp)
     * @param options - Intl.DateTimeFormatOptions for customizing the output
     * @returns Localized date string
     *
     * @example
     * ```typescript
     * const localizer = new Localizer({...});
     * console.log(localizer.time(new Date())); // "4/21/2025"
     * ```
     */
    time(date: number | Date, options?: Intl.DateTimeFormatOptions): string;
    /**
     * Creates a relative time string comparing two dates.
     *
     * @param date - The date to compare (as Date object or timestamp)
     * @param from - Reference date for comparison (defaults to current time)
     * @param options - Formatting options for relative time
     * @returns Localized relative time string
     *
     * @example
     * ```typescript
     * const localizer = new Localizer({...});
     * const date = new Date(Date.now() - 3600000); // 1 hour ago
     * console.log(localizer.relativeTime(date)); // "1 hour ago"
     * ```
     */
    relativeTime(date: number | Date, from?: number | Date, options?: Intl.RelativeTimeFormatOptions): string;
}
//# sourceMappingURL=main.d.ts.map