@nexim/localizer 1.0.0

package/README.md

@@ -0,0 +1,26 @@
+# @nexim/localizer
+
+![NPM Version](https://img.shields.io/npm/v/@nexim/localizer)
+![npm bundle size](https://img.shields.io/bundlephobia/min/@nexim/localizer)
+![Build & Lint & Test](https://github.com/the-nexim/nanolib/actions/workflows/build-lint-test.yaml/badge.svg)
+![NPM Downloads](https://img.shields.io/npm/dm/@nexim/localizer)
+![NPM License](https://img.shields.io/npm/l/@nexim/localizer)
+
+## Overview
+
+`@nexim/localizer` is a Lightweight i18n utilities to handle translations, number formatting, date/time localization using native browser APIs.
+
+## Installation
+
+Install the package using npm or yarn:
+
+```sh
+npm install @nexim/localizer
+
+# Or using yarn
+yarn add @nexim/localizer
+```
+
+## Documentation
+
+Read full documentation [here](./docs/README.md).

package/dist/main.cjs

@@ -0,0 +1,171 @@
+/* @nexim/localizer v1.0.0 */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/main.ts
+var main_exports = {};
+__export(main_exports, {
+  Localizer: () => Localizer
+});
+module.exports = __toCommonJS(main_exports);
+var import_unicode_digits = require("@alwatr/unicode-digits");
+var import_package_tracer = require("@alwatr/package-tracer");
+var import_logger = require("@alwatr/logger");
+__dev_mode__: import_package_tracer.packageTracer.add("@nexim/localizer", "1.0.0");
+var _Localizer = class _Localizer {
+  /**
+   * Creates a new instance of the Localizer class.
+   *
+   * @param options__ - Configuration options for localization
+   */
+  constructor(options__) {
+    this.options__ = options__;
+    this.logger_ = (0, import_logger.createLogger)("@nexim/localizer");
+    this.numberFormatter_ = new Intl.NumberFormat(this.options__.locale.code);
+    this.unicodeDigits_ = new import_unicode_digits.UnicodeDigits(this.options__.locale.language);
+  }
+  /**
+   * 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) {
+    this.logger_.logMethodArgs?.("message", key);
+    if (!key) return "";
+    const msg = this.options__.resource?.[key];
+    if (msg === void 0) {
+      this.logger_.accident("message", "l10n_key_not_found", "Key not defined in the localization resource", {
+        key,
+        locale: this.options__.locale
+      });
+      return `{${key}}`;
+    }
+    return msg;
+  }
+  /**
+   * 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, decimal = 2) {
+    if (number == null) return "";
+    decimal = Math.pow(10, decimal);
+    number = Math.round(number * decimal) / decimal;
+    return this.numberFormatter_.format(number);
+  }
+  /**
+   * 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) {
+    this.logger_.logMethodArgs?.("replaceNumber", str);
+    return this.unicodeDigits_.translate(str);
+  }
+  /**
+   * 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, options) {
+    this.logger_.logMethodArgs?.("time", { date, options });
+    if (typeof date === "number") date = new Date(date);
+    return date.toLocaleDateString(this.options__.locale.code, options);
+  }
+  /**
+   * 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, from = Date.now(), options = { numeric: "auto", style: "narrow" }) {
+    this.logger_.logMethodArgs?.("relativeTime", { date, from, options });
+    const rtf = new Intl.RelativeTimeFormat(this.options__.locale.code, options);
+    if (typeof date !== "number") date = date.getTime();
+    if (typeof from !== "number") from = from.getTime();
+    const diffSec = (from - date) / 1e3;
+    for (const unit of _Localizer.timeUnits_) {
+      const interval = Math.floor(Math.abs(diffSec / unit.seconds));
+      if (interval >= 1) {
+        return rtf.format(diffSec > 0 ? interval : -interval, unit.label);
+      }
+    }
+    return rtf.format(0, "second");
+  }
+};
+/**
+ * Time units used for relative time calculations.
+ * @internal
+ */
+_Localizer.timeUnits_ = [
+  { label: "year", seconds: 31536e3 },
+  { label: "month", seconds: 2592e3 },
+  { label: "week", seconds: 604800 },
+  { label: "day", seconds: 86400 },
+  { label: "hour", seconds: 3600 },
+  { label: "minute", seconds: 60 },
+  { label: "second", seconds: 1 }
+];
+var Localizer = _Localizer;
+//# sourceMappingURL=main.cjs.map

package/dist/main.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/main.ts"],
+  "sourcesContent": ["import { UnicodeDigits, type UnicodeLangKeys } from '@alwatr/unicode-digits';\nimport { packageTracer } from '@alwatr/package-tracer';\nimport { createLogger } from '@alwatr/logger';\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\n/**\n * Represents a locale code in the format \"language-COUNTRY\".\n * The language part must be in lowercase, and the country part must be in uppercase.\n *\n * @example \"en-US\"\n * @example \"fr-FR\"\n * @example \"de-DE\"\n */\nexport type LocaleCode = `${Lowercase<string>}-${Uppercase<string>}`;\n\n/**\n * Represents a locale configuration with language code and language identifier.\n */\nexport interface Locale {\n  /**\n   * fa-IR, en-US, ...\n   */\n  code: LocaleCode;\n\n  /**\n   * The ISO 639-1 language code (e.g., 'fa', 'en')\n   */\n  language: UnicodeLangKeys;\n}\n\n/**\n * Provides localization and internationalization functionality.\n *\n * @remarks\n * This class handles number formatting, text translation, date formatting,\n * and relative time calculations based on the specified locale.\n */\nexport class Localizer {\n  /**\n   * Number formatter instance for formatting numbers according to the locale.\n   *\n   * @internal\n   */\n  protected numberFormatter_;\n\n  /**\n   * UnicodeDigits instance for converting numbers to locale-specific digits.\n   *\n   * @internal\n   */\n  protected unicodeDigits_;\n\n  protected logger_ = createLogger(__package_name__);\n\n  /**\n   * Time units used for relative time calculations.\n   * @internal\n   */\n  static timeUnits_ = [\n    { label: 'year', seconds: 31536000 },\n    { label: 'month', seconds: 2592000 },\n    { label: 'week', seconds: 604800 },\n    { label: 'day', seconds: 86400 },\n    { label: 'hour', seconds: 3600 },\n    { label: 'minute', seconds: 60 },\n    { label: 'second', seconds: 1 },\n  ] as const;\n\n  /**\n   * Creates a new instance of the Localizer class.\n   *\n   * @param options__ - Configuration options for localization\n   */\n  constructor(private options__: { locale: Locale; resource: DictionaryReq | null }) {\n    this.numberFormatter_ = new Intl.NumberFormat(this.options__.locale.code);\n    this.unicodeDigits_ = new UnicodeDigits(this.options__.locale.language);\n  }\n\n  /**\n   * Retrieves a localized message by key from the resource dictionary.\n   *\n   * @param key - The key to lookup in the resource dictionary\n   * @returns The localized message string\n   *\n   * @remarks\n   * - Returns \"\\{key\\}\" if the key is not found in the dictionary\n   * - Returns an empty string if the key is null or undefined\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * console.log(localizer.message('hello_world')); // \"Hello world!\"\n   * console.log(localizer.message('missing_key')); // \"{missing_key}\"\n   * ```\n   */\n  message(key: keyof NonNullable<typeof this.options__.resource>): string {\n    this.logger_.logMethodArgs?.('message', key);\n    if (!key) return '';\n\n    const msg = this.options__.resource?.[key];\n    if (msg === undefined) {\n      this.logger_.accident('message', 'l10n_key_not_found', 'Key not defined in the localization resource', {\n        key,\n        locale: this.options__.locale,\n      });\n      return `{${key}}`;\n    }\n    // else\n    return msg;\n  }\n\n  /**\n   * Formats a number according to the current locale settings.\n   *\n   * @param number - The number to format\n   * @param decimal - Number of decimal places (default: 2)\n   * @returns Formatted number string using locale-specific formatting\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * console.log(localizer.number(1234.567)); // \"1,234.57\"\n   * console.log(localizer.number(1234.567, 1)); // \"1,234.6\"\n   * ```\n   */\n  number(number?: number | null, decimal = 2): string {\n    if (number == null) return '';\n    decimal = Math.pow(10, decimal);\n    number = Math.round(number * decimal) / decimal;\n    return this.numberFormatter_.format(number);\n  }\n\n  /**\n   * Replaces all numeric digits in a string with their locale-specific Unicode equivalents.\n   *\n   * @param str - The input string containing numbers to replace\n   * @returns String with numbers converted to locale-specific digits\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({locale: {code: 'fa-IR', language: 'fa'}, ...});\n   * console.log(localizer.replaceNumber('123')); // '۱۲۳'\n   * ```\n   */\n  replaceNumber(str: string): string {\n    this.logger_.logMethodArgs?.('replaceNumber', str);\n    return this.unicodeDigits_.translate(str);\n  }\n\n  /**\n   * Formats a date according to the current locale settings.\n   *\n   * @param date - Date to format (as Date object or timestamp)\n   * @param options - Intl.DateTimeFormatOptions for customizing the output\n   * @returns Localized date string\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * console.log(localizer.time(new Date())); // \"4/21/2025\"\n   * ```\n   */\n  time(date: number | Date, options?: Intl.DateTimeFormatOptions): string {\n    this.logger_.logMethodArgs?.('time', { date, options });\n    if (typeof date === 'number') date = new Date(date);\n    return date.toLocaleDateString(this.options__.locale.code, options);\n  }\n\n  /**\n   * Creates a relative time string comparing two dates.\n   *\n   * @param date - The date to compare (as Date object or timestamp)\n   * @param from - Reference date for comparison (defaults to current time)\n   * @param options - Formatting options for relative time\n   * @returns Localized relative time string\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * const date = new Date(Date.now() - 3600000); // 1 hour ago\n   * console.log(localizer.relativeTime(date)); // \"1 hour ago\"\n   * ```\n   */\n  relativeTime(\n    date: number | Date,\n    from: number | Date = Date.now(),\n    options: Intl.RelativeTimeFormatOptions = { numeric: 'auto', style: 'narrow' },\n  ): string {\n    this.logger_.logMethodArgs?.('relativeTime', { date, from, options });\n\n    const rtf = new Intl.RelativeTimeFormat(this.options__.locale.code, options);\n\n    if (typeof date !== 'number') date = date.getTime();\n    if (typeof from !== 'number') from = from.getTime();\n    const diffSec = (from - date) / 1000;\n\n    // Find the appropriate unit for the time difference\n    for (const unit of Localizer.timeUnits_) {\n      const interval = Math.floor(Math.abs(diffSec / unit.seconds));\n      if (interval >= 1) {\n        return rtf.format(diffSec > 0 ? interval : -interval, unit.label);\n      }\n    }\n\n    return rtf.format(0, 'second');\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/main.d.ts

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

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM7E;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;IAoCR,OAAO,CAAC,SAAS;IAnC7B;;;;OAIG;IACH,SAAS,CAAC,gBAAgB,oBAAC;IAE3B;;;;OAIG;IACH,SAAS,CAAC,cAAc,gBAAC;IAEzB,SAAS,CAAC,OAAO,wCAAkC;IAEnD;;;OAGG;IACH,MAAM,CAAC,UAAU;;;;;;;;;;;;;;;;;;;;;OAQN;IAEX;;;;OAIG;gBACiB,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAA;KAAE;IAKjF;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,WAAW,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,MAAM;IAgBvE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,SAAI,GAAG,MAAM;IAOnD;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAKlC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,GAAG,MAAM;IAMvE;;;;;;;;;;;;;;OAcG;IACH,YAAY,CACV,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,IAAI,GAAE,MAAM,GAAG,IAAiB,EAChC,OAAO,GAAE,IAAI,CAAC,yBAAgE,GAC7E,MAAM;CAmBV"}

package/dist/main.mjs

@@ -0,0 +1,151 @@
+/* @nexim/localizer v1.0.0 */
+
+// src/main.ts
+import { UnicodeDigits } from "@alwatr/unicode-digits";
+import { packageTracer } from "@alwatr/package-tracer";
+import { createLogger } from "@alwatr/logger";
+__dev_mode__: packageTracer.add("@nexim/localizer", "1.0.0");
+var _Localizer = class _Localizer {
+  /**
+   * Creates a new instance of the Localizer class.
+   *
+   * @param options__ - Configuration options for localization
+   */
+  constructor(options__) {
+    this.options__ = options__;
+    this.logger_ = createLogger("@nexim/localizer");
+    this.numberFormatter_ = new Intl.NumberFormat(this.options__.locale.code);
+    this.unicodeDigits_ = new UnicodeDigits(this.options__.locale.language);
+  }
+  /**
+   * 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) {
+    this.logger_.logMethodArgs?.("message", key);
+    if (!key) return "";
+    const msg = this.options__.resource?.[key];
+    if (msg === void 0) {
+      this.logger_.accident("message", "l10n_key_not_found", "Key not defined in the localization resource", {
+        key,
+        locale: this.options__.locale
+      });
+      return `{${key}}`;
+    }
+    return msg;
+  }
+  /**
+   * 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, decimal = 2) {
+    if (number == null) return "";
+    decimal = Math.pow(10, decimal);
+    number = Math.round(number * decimal) / decimal;
+    return this.numberFormatter_.format(number);
+  }
+  /**
+   * 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) {
+    this.logger_.logMethodArgs?.("replaceNumber", str);
+    return this.unicodeDigits_.translate(str);
+  }
+  /**
+   * 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, options) {
+    this.logger_.logMethodArgs?.("time", { date, options });
+    if (typeof date === "number") date = new Date(date);
+    return date.toLocaleDateString(this.options__.locale.code, options);
+  }
+  /**
+   * 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, from = Date.now(), options = { numeric: "auto", style: "narrow" }) {
+    this.logger_.logMethodArgs?.("relativeTime", { date, from, options });
+    const rtf = new Intl.RelativeTimeFormat(this.options__.locale.code, options);
+    if (typeof date !== "number") date = date.getTime();
+    if (typeof from !== "number") from = from.getTime();
+    const diffSec = (from - date) / 1e3;
+    for (const unit of _Localizer.timeUnits_) {
+      const interval = Math.floor(Math.abs(diffSec / unit.seconds));
+      if (interval >= 1) {
+        return rtf.format(diffSec > 0 ? interval : -interval, unit.label);
+      }
+    }
+    return rtf.format(0, "second");
+  }
+};
+/**
+ * Time units used for relative time calculations.
+ * @internal
+ */
+_Localizer.timeUnits_ = [
+  { label: "year", seconds: 31536e3 },
+  { label: "month", seconds: 2592e3 },
+  { label: "week", seconds: 604800 },
+  { label: "day", seconds: 86400 },
+  { label: "hour", seconds: 3600 },
+  { label: "minute", seconds: 60 },
+  { label: "second", seconds: 1 }
+];
+var Localizer = _Localizer;
+export {
+  Localizer
+};
+//# sourceMappingURL=main.mjs.map

package/dist/main.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/main.ts"],
+  "sourcesContent": ["import { UnicodeDigits, type UnicodeLangKeys } from '@alwatr/unicode-digits';\nimport { packageTracer } from '@alwatr/package-tracer';\nimport { createLogger } from '@alwatr/logger';\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\n/**\n * Represents a locale code in the format \"language-COUNTRY\".\n * The language part must be in lowercase, and the country part must be in uppercase.\n *\n * @example \"en-US\"\n * @example \"fr-FR\"\n * @example \"de-DE\"\n */\nexport type LocaleCode = `${Lowercase<string>}-${Uppercase<string>}`;\n\n/**\n * Represents a locale configuration with language code and language identifier.\n */\nexport interface Locale {\n  /**\n   * fa-IR, en-US, ...\n   */\n  code: LocaleCode;\n\n  /**\n   * The ISO 639-1 language code (e.g., 'fa', 'en')\n   */\n  language: UnicodeLangKeys;\n}\n\n/**\n * Provides localization and internationalization functionality.\n *\n * @remarks\n * This class handles number formatting, text translation, date formatting,\n * and relative time calculations based on the specified locale.\n */\nexport class Localizer {\n  /**\n   * Number formatter instance for formatting numbers according to the locale.\n   *\n   * @internal\n   */\n  protected numberFormatter_;\n\n  /**\n   * UnicodeDigits instance for converting numbers to locale-specific digits.\n   *\n   * @internal\n   */\n  protected unicodeDigits_;\n\n  protected logger_ = createLogger(__package_name__);\n\n  /**\n   * Time units used for relative time calculations.\n   * @internal\n   */\n  static timeUnits_ = [\n    { label: 'year', seconds: 31536000 },\n    { label: 'month', seconds: 2592000 },\n    { label: 'week', seconds: 604800 },\n    { label: 'day', seconds: 86400 },\n    { label: 'hour', seconds: 3600 },\n    { label: 'minute', seconds: 60 },\n    { label: 'second', seconds: 1 },\n  ] as const;\n\n  /**\n   * Creates a new instance of the Localizer class.\n   *\n   * @param options__ - Configuration options for localization\n   */\n  constructor(private options__: { locale: Locale; resource: DictionaryReq | null }) {\n    this.numberFormatter_ = new Intl.NumberFormat(this.options__.locale.code);\n    this.unicodeDigits_ = new UnicodeDigits(this.options__.locale.language);\n  }\n\n  /**\n   * Retrieves a localized message by key from the resource dictionary.\n   *\n   * @param key - The key to lookup in the resource dictionary\n   * @returns The localized message string\n   *\n   * @remarks\n   * - Returns \"\\{key\\}\" if the key is not found in the dictionary\n   * - Returns an empty string if the key is null or undefined\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * console.log(localizer.message('hello_world')); // \"Hello world!\"\n   * console.log(localizer.message('missing_key')); // \"{missing_key}\"\n   * ```\n   */\n  message(key: keyof NonNullable<typeof this.options__.resource>): string {\n    this.logger_.logMethodArgs?.('message', key);\n    if (!key) return '';\n\n    const msg = this.options__.resource?.[key];\n    if (msg === undefined) {\n      this.logger_.accident('message', 'l10n_key_not_found', 'Key not defined in the localization resource', {\n        key,\n        locale: this.options__.locale,\n      });\n      return `{${key}}`;\n    }\n    // else\n    return msg;\n  }\n\n  /**\n   * Formats a number according to the current locale settings.\n   *\n   * @param number - The number to format\n   * @param decimal - Number of decimal places (default: 2)\n   * @returns Formatted number string using locale-specific formatting\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * console.log(localizer.number(1234.567)); // \"1,234.57\"\n   * console.log(localizer.number(1234.567, 1)); // \"1,234.6\"\n   * ```\n   */\n  number(number?: number | null, decimal = 2): string {\n    if (number == null) return '';\n    decimal = Math.pow(10, decimal);\n    number = Math.round(number * decimal) / decimal;\n    return this.numberFormatter_.format(number);\n  }\n\n  /**\n   * Replaces all numeric digits in a string with their locale-specific Unicode equivalents.\n   *\n   * @param str - The input string containing numbers to replace\n   * @returns String with numbers converted to locale-specific digits\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({locale: {code: 'fa-IR', language: 'fa'}, ...});\n   * console.log(localizer.replaceNumber('123')); // '۱۲۳'\n   * ```\n   */\n  replaceNumber(str: string): string {\n    this.logger_.logMethodArgs?.('replaceNumber', str);\n    return this.unicodeDigits_.translate(str);\n  }\n\n  /**\n   * Formats a date according to the current locale settings.\n   *\n   * @param date - Date to format (as Date object or timestamp)\n   * @param options - Intl.DateTimeFormatOptions for customizing the output\n   * @returns Localized date string\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * console.log(localizer.time(new Date())); // \"4/21/2025\"\n   * ```\n   */\n  time(date: number | Date, options?: Intl.DateTimeFormatOptions): string {\n    this.logger_.logMethodArgs?.('time', { date, options });\n    if (typeof date === 'number') date = new Date(date);\n    return date.toLocaleDateString(this.options__.locale.code, options);\n  }\n\n  /**\n   * Creates a relative time string comparing two dates.\n   *\n   * @param date - The date to compare (as Date object or timestamp)\n   * @param from - Reference date for comparison (defaults to current time)\n   * @param options - Formatting options for relative time\n   * @returns Localized relative time string\n   *\n   * @example\n   * ```typescript\n   * const localizer = new Localizer({...});\n   * const date = new Date(Date.now() - 3600000); // 1 hour ago\n   * console.log(localizer.relativeTime(date)); // \"1 hour ago\"\n   * ```\n   */\n  relativeTime(\n    date: number | Date,\n    from: number | Date = Date.now(),\n    options: Intl.RelativeTimeFormatOptions = { numeric: 'auto', style: 'narrow' },\n  ): string {\n    this.logger_.logMethodArgs?.('relativeTime', { date, from, options });\n\n    const rtf = new Intl.RelativeTimeFormat(this.options__.locale.code, options);\n\n    if (typeof date !== 'number') date = date.getTime();\n    if (typeof from !== 'number') from = from.getTime();\n    const diffSec = (from - date) / 1000;\n\n    // Find the appropriate unit for the time difference\n    for (const unit of Localizer.timeUnits_) {\n      const interval = Math.floor(Math.abs(diffSec / unit.seconds));\n      if (interval >= 1) {\n        return rtf.format(diffSec > 0 ? interval : -interval, unit.label);\n      }\n    }\n\n    return rtf.format(0, 'second');\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/main.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.test.d.ts.map

package/dist/main.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.test.d.ts","sourceRoot":"","sources":["../src/main.test.js"],"names":[],"mappings":""}

package/docs/README.md

@@ -0,0 +1,19 @@
+# @nexim/localizer
+
+## Classes
+
+| Class                             | Description                                                   |
+| --------------------------------- | ------------------------------------------------------------- |
+| [Localizer](classes/Localizer.md) | Provides localization and internationalization functionality. |
+
+## Interfaces
+
+| Interface                      | Description                                                                   |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| [Locale](interfaces/Locale.md) | Represents a locale configuration with language code and language identifier. |
+
+## Type Aliases
+
+| Type Alias                               | Description                                                                                                                                   |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [LocaleCode](type-aliases/LocaleCode.md) | Represents a locale code in the format "language-COUNTRY". The language part must be in lowercase, and the country part must be in uppercase. |