@lakutata/i18n 3.0.0-beta.0

package/dist/cjs/i18n/Translator.js

@@ -0,0 +1,156 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Translator = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const I18nTranslatorException_js_1 = require("./exceptions/I18nTranslatorException.js");
+/**
+ * The messages in the language of the current request. With the {@link I18nMiddleware} on the entrypoint, each request
+ * gets one `Translator` of its negotiated language, shared by the objects of the request: the controller, the
+ * `@Scoped` providers and the access control rules inject it with `@Inject(Translator)`. It is a scoped provider,
+ * autoloaded: it needs no registration. Without the middleware (or out of a request), its methods throw
+ * {@link I18nTranslatorException}; use {@link I18n.translator} there.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ * import {CLIAction, GET} from 'lakutata/decorator/ctrl'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {buildI18nOptions, I18nMiddleware, Translator} from 'lakutata/com/i18n'
+ *
+ * class OrderController extends Controller {
+ *     @Inject(Translator)
+ *     protected readonly translator: Translator
+ *
+ *     //GET /orders/count?lang=zh-CN, or the lang cookie, or Accept-Language
+ *     @GET('/orders/count')
+ *     @CLIAction('count-orders')
+ *     public async count(): Promise<string> {
+ *         return `${this.translator.locale}: ${this.translator.t('order.count', {count: 3})}`
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'shop.app',
+ *     name: 'Shop',
+ *     components: {
+ *         i18n: buildI18nOptions({
+ *             messages: {
+ *                 'en': {order: {count: '{count, plural, one {# order} other {# orders}}'}},
+ *                 'zh-CN': {order: {count: '{count} 个订单'}}
+ *             }
+ *         }),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [OrderController],
+ *             middlewares: [I18nMiddleware],
+ *             http: expressHTTPEntrypoint({port: 3000})
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+let Translator = class Translator extends core_1.Provider {
+    #translator;
+    /**
+     * Create the translator of the language given by the middleware, when it gave one.
+     */
+    async init() {
+        if (this.i18n && this.locale)
+            this.#translator = this.i18n.translator(this.locale);
+    }
+    /**
+     * The translator of the request's language.
+     * @throws {I18nTranslatorException} When the middleware did not give the language (no {@link I18nMiddleware} on
+     * the entrypoint, or out of a request).
+     */
+    get translator() {
+        if (!this.#translator)
+            throw new I18nTranslatorException_js_1.I18nTranslatorException('The translator of a request is given by the I18nMiddleware of its entrypoint: buildEntrypoints({middlewares: [I18nMiddleware]})');
+        return this.#translator;
+    }
+    /**
+     * Give the message of a key in the request's language, formatted with its arguments (see {@link I18n.t}).
+     * @param key The key of the message (`order.count`).
+     * @param params The arguments of the message, by their names.
+     * @returns The formatted message. With `missing: 'key'`, the key itself when it is missing, `{name}` in place of a
+     * missing argument, a plain number for a currency argument without a currency (each with a warning, once).
+     * @throws {I18nTranslatorException} When the entrypoint has no {@link I18nMiddleware}, or out of a request.
+     * @throws {I18nMissingKeyException} When no message has the key and the `missing` option is `'throw'`.
+     * @throws {I18nMissingParameterException} When an argument is missing, or a currency argument has no currency, and
+     * the `missing` option is `'throw'`.
+     * @throws {I18nMessageSyntaxException} When the message is not valid ICU MessageFormat.
+     */
+    t(key, params) {
+        return this.translator.t(key, params);
+    }
+    /**
+     * Tell whether a key has a message in the request's language or in the languages it falls back to.
+     * @param key The key of the message.
+     * @returns `true` when {@link Translator.t} finds a message for the key.
+     * @throws {I18nTranslatorException} When the entrypoint has no {@link I18nMiddleware}, or out of a request.
+     */
+    has(key) {
+        return this.translator.has(key);
+    }
+    /**
+     * Format an ICU MessageFormat message which is not in the catalogs, in the request's language.
+     * @param message The message (`Hello, {name}`).
+     * @param params The arguments of the message, by their names.
+     * @returns The formatted message. With `missing: 'key'`, `{name}` in place of a missing argument, a plain number
+     * for a currency argument without a currency (each with a warning, once).
+     * @throws {I18nTranslatorException} When the entrypoint has no {@link I18nMiddleware}, or out of a request.
+     * @throws {I18nMessageSyntaxException} When the message is not valid ICU MessageFormat.
+     * @throws {I18nMissingParameterException} When an argument is missing, or a currency argument has no currency, and
+     * the `missing` option is `'throw'`.
+     */
+    format(message, params) {
+        return this.translator.format(message, params);
+    }
+    /**
+     * Format a number in the request's language (`1234.5` gives `1,234.5` in English, `1.234,5` in German).
+     * @param value The number.
+     * @param options The options of `Intl.NumberFormat` (`{style: 'currency', currency: 'EUR'}`); the component's
+     * `currency` option is not applied here.
+     * @returns The formatted number.
+     * @throws {I18nTranslatorException} When the entrypoint has no {@link I18nMiddleware}, or out of a request.
+     */
+    number(value, options) {
+        return this.translator.number(value, options);
+    }
+    /**
+     * Format a date (and its time when the options ask for it) in the request's language, in the component's
+     * `timeZone` (the process's one without it).
+     * @param value The date, or a timestamp in milliseconds.
+     * @param options The options of `Intl.DateTimeFormat` (`{dateStyle: 'long'}`); their `timeZone` replaces the
+     * component's one.
+     * @returns The formatted date.
+     * @throws {I18nTranslatorException} When the entrypoint has no {@link I18nMiddleware}, or out of a request.
+     */
+    date(value, options) {
+        return this.translator.date(value, options);
+    }
+};
+exports.Translator = Translator;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], Translator.prototype, "locale", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Any().optional()),
+    __metadata("design:type", Function)
+], Translator.prototype, "i18n", void 0);
+exports.Translator = Translator = __decorate([
+    (0, di_1.Scoped)(),
+    (0, di_1.Autoload)()
+], Translator);

package/dist/cjs/i18n/exceptions/I18nCatalogException.d.ts

@@ -0,0 +1,15 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when the messages or the configuration of the {@link I18n} component are invalid: a missing directory, a file
+ * which is not valid JSON, a file or directory name which is not a language tag, a key part containing `.`, a value
+ * which is neither a string nor an object, an option (`defaultLocale`, `locales`, `fallback`, `messages`) which is not
+ * a language tag, or an alias of `directory` without an application to resolve it. The component throws it when it is
+ * created, {@link I18n.addMessages} and {@link loadCatalogs} when they are called, and {@link generateMessageTypes} when
+ * the default language has no messages. Its `errno` is `'E_I18N_CATALOG'`.
+ */
+export declare class I18nCatalogException extends Exception {
+    /**
+     * `'E_I18N_CATALOG'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/i18n/exceptions/I18nCatalogException.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nCatalogException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when the messages or the configuration of the {@link I18n} component are invalid: a missing directory, a file
+ * which is not valid JSON, a file or directory name which is not a language tag, a key part containing `.`, a value
+ * which is neither a string nor an object, an option (`defaultLocale`, `locales`, `fallback`, `messages`) which is not
+ * a language tag, or an alias of `directory` without an application to resolve it. The component throws it when it is
+ * created, {@link I18n.addMessages} and {@link loadCatalogs} when they are called, and {@link generateMessageTypes} when
+ * the default language has no messages. Its `errno` is `'E_I18N_CATALOG'`.
+ */
+class I18nCatalogException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_CATALOG'`.
+         */
+        this.errno = 'E_I18N_CATALOG';
+    }
+}
+exports.I18nCatalogException = I18nCatalogException;

package/dist/cjs/i18n/exceptions/I18nMessageSyntaxException.d.ts

@@ -0,0 +1,14 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when a message is not valid ICU MessageFormat: an unclosed brace, an unknown argument type or style, a
+ * `plural`, `selectordinal` or `select` without its `other` option, a repeated selector. Its message names the
+ * language, the key and the position (`zh-CN: order.count: the "other" option is required at 1`). A catalog message is
+ * parsed the first time it is used, so {@link I18n.t} throws it then; {@link I18n.format} and {@link parseMessage}
+ * throw it at once. Its `errno` is `'E_I18N_MESSAGE_SYNTAX'`.
+ */
+export declare class I18nMessageSyntaxException extends Exception {
+    /**
+     * `'E_I18N_MESSAGE_SYNTAX'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/i18n/exceptions/I18nMessageSyntaxException.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nMessageSyntaxException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when a message is not valid ICU MessageFormat: an unclosed brace, an unknown argument type or style, a
+ * `plural`, `selectordinal` or `select` without its `other` option, a repeated selector. Its message names the
+ * language, the key and the position (`zh-CN: order.count: the "other" option is required at 1`). A catalog message is
+ * parsed the first time it is used, so {@link I18n.t} throws it then; {@link I18n.format} and {@link parseMessage}
+ * throw it at once. Its `errno` is `'E_I18N_MESSAGE_SYNTAX'`.
+ */
+class I18nMessageSyntaxException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_MESSAGE_SYNTAX'`.
+         */
+        this.errno = 'E_I18N_MESSAGE_SYNTAX';
+    }
+}
+exports.I18nMessageSyntaxException = I18nMessageSyntaxException;

package/dist/cjs/i18n/exceptions/I18nMissingKeyException.d.ts

@@ -0,0 +1,12 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link I18n.t} (and the translators) when no message has the key, neither in the language asked nor in the
+ * languages it falls back to, and the `missing` option is `'throw'` (the default outside `NODE_ENV=production`). Its
+ * message lists the languages looked up. Its `errno` is `'E_I18N_MISSING_KEY'`.
+ */
+export declare class I18nMissingKeyException extends Exception {
+    /**
+     * `'E_I18N_MISSING_KEY'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/i18n/exceptions/I18nMissingKeyException.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nMissingKeyException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown by {@link I18n.t} (and the translators) when no message has the key, neither in the language asked nor in the
+ * languages it falls back to, and the `missing` option is `'throw'` (the default outside `NODE_ENV=production`). Its
+ * message lists the languages looked up. Its `errno` is `'E_I18N_MISSING_KEY'`.
+ */
+class I18nMissingKeyException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_MISSING_KEY'`.
+         */
+        this.errno = 'E_I18N_MISSING_KEY';
+    }
+}
+exports.I18nMissingKeyException = I18nMissingKeyException;

package/dist/cjs/i18n/exceptions/I18nMissingParameterException.d.ts

@@ -0,0 +1,13 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when a message is formatted without one of its arguments and the `missing` option is `'throw'` (the default
+ * outside `NODE_ENV=production`), or a `{price, number, currency}` argument has no currency (neither in its style, nor
+ * in the `currency` argument, nor in the component's `currency` option) and the `missing` option is `'throw'`. Its
+ * `errno` is `'E_I18N_MISSING_PARAMETER'`.
+ */
+export declare class I18nMissingParameterException extends Exception {
+    /**
+     * `'E_I18N_MISSING_PARAMETER'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/i18n/exceptions/I18nMissingParameterException.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nMissingParameterException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when a message is formatted without one of its arguments and the `missing` option is `'throw'` (the default
+ * outside `NODE_ENV=production`), or a `{price, number, currency}` argument has no currency (neither in its style, nor
+ * in the `currency` argument, nor in the component's `currency` option) and the `missing` option is `'throw'`. Its
+ * `errno` is `'E_I18N_MISSING_PARAMETER'`.
+ */
+class I18nMissingParameterException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_MISSING_PARAMETER'`.
+         */
+        this.errno = 'E_I18N_MISSING_PARAMETER';
+    }
+}
+exports.I18nMissingParameterException = I18nMissingParameterException;

package/dist/cjs/i18n/exceptions/I18nTranslatorException.d.ts

@@ -0,0 +1,12 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by the methods of a {@link Translator} which was not given its language by the {@link I18nMiddleware}: the
+ * entrypoint has no `I18nMiddleware`, or the `Translator` is used out of a request. Its `errno` is
+ * `'E_I18N_TRANSLATOR'`.
+ */
+export declare class I18nTranslatorException extends Exception {
+    /**
+     * `'E_I18N_TRANSLATOR'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/i18n/exceptions/I18nTranslatorException.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nTranslatorException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown by the methods of a {@link Translator} which was not given its language by the {@link I18nMiddleware}: the
+ * entrypoint has no `I18nMiddleware`, or the `Translator` is used out of a request. Its `errno` is
+ * `'E_I18N_TRANSLATOR'`.
+ */
+class I18nTranslatorException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_TRANSLATOR'`.
+         */
+        this.errno = 'E_I18N_TRANSLATOR';
+    }
+}
+exports.I18nTranslatorException = I18nTranslatorException;

package/dist/cjs/i18n/interfaces/I18nOptions.d.ts

@@ -0,0 +1,70 @@
+import type { NestedMessages } from '../lib/Catalog.js';
+/**
+ * The options of the {@link I18n} component, given to {@link buildI18nOptions}. The messages come from `directory`
+ * (JSON files read when the component is created), from `messages` (bundled with the code), or from both; without
+ * either, the component starts with no messages.
+ */
+export interface I18nOptions {
+    /**
+     * The directories holding the messages, read when the component is created, the later directories replacing the
+     * same keys of the earlier ones. A path is resolved from the working directory; a path starting with `@` is an
+     * alias of the application (`@app/locales`). In a directory, each language is either a JSON file named by its tag
+     * (`zh-CN.json`) or a directory named by its tag whose files and subdirectories prefix their keys
+     * (`zh-CN/order.json` gives `order.*`, `zh-CN/admin/user.json` gives `admin.user.*`). Files not ending in `.json`
+     * are ignored; a missing directory, invalid JSON or a name which is not a language tag fails the component's creation
+     * with {@link I18nCatalogException}.
+     * @default none
+     */
+    directory?: string | string[];
+    /**
+     * The languages {@link I18n.negotiate} chooses from (and the requests are answered in), as language tags.
+     * @default the default language, then the languages of the messages in alphabetical order
+     */
+    locales?: string[];
+    /**
+     * The default language: the last language a message is looked up in, the language of {@link I18n.t} called
+     * without one, and the language chosen when none of the requested ones is supported.
+     * @default 'en'
+     */
+    defaultLocale?: string;
+    /**
+     * The languages a message missing in a language is looked up in next, before the less specific tags and the default
+     * language (`{'zh-TW': 'zh-CN'}`, or several in their order: `{'pt-PT': ['pt-BR', 'es']}`). The fallbacks of a
+     * fallback are followed too.
+     * @default none
+     */
+    fallback?: Record<string, string | string[]>;
+    /**
+     * The messages by language tag, nested by the parts of their keys (object literals or imported JSON), added after
+     * the ones of `directory` and replacing their keys. They are bundled with the code: no file is read.
+     * @default none
+     */
+    messages?: Record<string, NestedMessages>;
+    /**
+     * What a missing message, argument or currency does: `'throw'` throws {@link I18nMissingKeyException} or
+     * {@link I18nMissingParameterException}; `'key'` gives the key in place of a missing message, writes a missing
+     * argument as `{name}`, and formats a `{price, number, currency}` argument without a currency as a plain number,
+     * each with a process warning `I18nWarning` emitted once (per key and language, or per message and argument).
+     * @default 'throw', and 'key' when NODE_ENV is 'production'
+     */
+    missing?: 'throw' | 'key';
+    /**
+     * The currency (ISO 4217: `CNY`, `USD`) of the `{price, number, currency}` arguments whose style and arguments give
+     * none (`currency/EUR`, a `currency` argument).
+     * @default none (such a message throws I18nMissingParameterException, or is formatted as a plain number with
+     * `missing: 'key'`)
+     */
+    currency?: string;
+    /**
+     * The time zone (IANA: `Asia/Shanghai`) of the dates and the times of the messages and of the translators' `date()`.
+     * @default the process's time zone
+     */
+    timeZone?: string;
+    /**
+     * Whether the built-in validation error messages of the supported languages are registered when the component is
+     * created (and of the languages added by `addMessages()`), so that the validation errors of a request are in its language. The `validation.<code>` messages of the
+     * application (`validation.any.required`) are registered either way and replace the built-in ones.
+     * @default true
+     */
+    validationMessages?: boolean;
+}

package/dist/cjs/i18n/interfaces/I18nOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/i18n/interfaces/ITranslator.d.ts

@@ -0,0 +1,57 @@
+import type { MessageKey, MessageParams } from '../types/I18nMessages.js';
+/**
+ * The messages of one language, without giving the language at each call: {@link I18n.translator} gives one for a
+ * language, and the {@link Translator} injected in the objects of a request is the one of the request's language.
+ */
+export interface ITranslator {
+    /**
+     * The language tag of the translator (`zh-CN`).
+     */
+    readonly locale: string;
+    /**
+     * Give the message of a key in the translator's language, formatted with its arguments (see {@link I18n.t}).
+     * @param key The key of the message (`order.count`).
+     * @param params The arguments of the message, by their names.
+     * @returns The formatted message. With `missing: 'key'`, the key itself when it is missing, `{name}` in place of a
+     * missing argument, a plain number for a currency argument without a currency (each with a warning, once).
+     * @throws {I18nMissingKeyException} When no message has the key and the `missing` option is `'throw'`.
+     * @throws {I18nMissingParameterException} When an argument is missing, or a currency argument has no currency, and
+     * the `missing` option is `'throw'`.
+     * @throws {I18nMessageSyntaxException} When the message is not valid ICU MessageFormat.
+     */
+    t<K extends MessageKey>(key: K, params?: MessageParams<K>): string;
+    /**
+     * Tell whether a key has a message in the translator's language or in the languages it falls back to.
+     * @param key The key of the message.
+     * @returns `true` when {@link ITranslator.t} finds a message for the key.
+     */
+    has(key: string): boolean;
+    /**
+     * Format an ICU MessageFormat message which is not in the catalogs, in the translator's language.
+     * @param message The message (`Hello, {name}`).
+     * @param params The arguments of the message, by their names.
+     * @returns The formatted message. With `missing: 'key'`, `{name}` in place of a missing argument, a plain number
+     * for a currency argument without a currency (each with a warning, once).
+     * @throws {I18nMessageSyntaxException} When the message is not valid ICU MessageFormat.
+     * @throws {I18nMissingParameterException} When an argument is missing, or a currency argument has no currency, and
+     * the `missing` option is `'throw'`.
+     */
+    format(message: string, params?: Record<string, unknown>): string;
+    /**
+     * Format a number in the translator's language (`1234.5` gives `1,234.5` in English, `1.234,5` in German).
+     * @param value The number.
+     * @param options The options of `Intl.NumberFormat` (`{style: 'currency', currency: 'EUR'}`); the component's
+     * `currency` option is not applied here.
+     * @returns The formatted number.
+     */
+    number(value: number | bigint, options?: Intl.NumberFormatOptions): string;
+    /**
+     * Format a date (and its time when the options ask for it) in the translator's language, in the component's
+     * `timeZone` (the process's one without it).
+     * @param value The date, or a timestamp in milliseconds.
+     * @param options The options of `Intl.DateTimeFormat` (`{dateStyle: 'long'}`); their `timeZone` replaces the
+     * component's one.
+     * @returns The formatted date.
+     */
+    date(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+}

package/dist/cjs/i18n/interfaces/ITranslator.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/i18n/lib/Catalog.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The messages of a language, nested by the parts of their keys: `{order: {count: '...'}}` holds the key
+ * `order.count`. A key part cannot be empty or contain `.`, and every leaf is a string (ICU MessageFormat, or a
+ * validation template under `validation`).
+ */
+export type NestedMessages = {
+    [key: string]: string | NestedMessages;
+};
+/**
+ * Loaded messages, by canonical language tag then by full key (`order.count`), as {@link loadCatalogs} gives them to
+ * {@link checkCatalogs} and {@link generateMessageTypes}.
+ */
+export type Catalogs = Map<string, Map<string, string>>;
+/**
+ * The messages of nested objects by their keys: {"order": {"count": "..."}} → order.count
+ * @param messages
+ * @param source where the messages are, for the errors
+ * @param prefix
+ */
+export declare function flattenMessages(messages: unknown, source: string, prefix?: string): Map<string, string>;
+/**
+ * Add the messages of a language to catalogs, the ones already there replaced
+ * @param catalogs
+ * @param locale
+ * @param messages
+ */
+export declare function mergeMessages(catalogs: Catalogs, locale: string, messages: Map<string, string>): void;
+/**
+ * Load the messages of a directory into catalogs: a file by language (zh-CN.json), or a directory by language whose
+ * files (and their directories) prefix their keys (zh-CN/order.json: order.*, zh-CN/admin/user.json: admin.user.*)
+ * @param catalogs
+ * @param directory
+ */
+export declare function loadDirectory(catalogs: Catalogs, directory: string): Promise<void>;

package/dist/cjs/i18n/lib/Catalog.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenMessages = flattenMessages;
+exports.mergeMessages = mergeMessages;
+exports.loadDirectory = loadDirectory;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const I18nCatalogException_js_1 = require("../exceptions/I18nCatalogException.js");
+const Locale_js_1 = require("./Locale.js");
+/**
+ * The messages of nested objects by their keys: {"order": {"count": "..."}} → order.count
+ * @param messages
+ * @param source where the messages are, for the errors
+ * @param prefix
+ */
+function flattenMessages(messages, source, prefix = '') {
+    const flat = new Map();
+    if (messages === null || typeof messages !== 'object' || Array.isArray(messages))
+        throw new I18nCatalogException_js_1.I18nCatalogException(`${source}: the messages must be an object${prefix ? ` (${prefix.slice(0, -1)})` : ''}`);
+    for (const [key, value] of Object.entries(messages)) {
+        if (!key || key.includes('.'))
+            throw new I18nCatalogException_js_1.I18nCatalogException(`${source}: invalid key "${prefix}${key}" (the parts of the keys are nested objects)`);
+        if (typeof value === 'string')
+            flat.set(`${prefix}${key}`, value);
+        else
+            flattenMessages(value, source, `${prefix}${key}.`).forEach((message, name) => flat.set(name, message));
+    }
+    return flat;
+}
+/**
+ * Add the messages of a language to catalogs, the ones already there replaced
+ * @param catalogs
+ * @param locale
+ * @param messages
+ */
+function mergeMessages(catalogs, locale, messages) {
+    let catalog = catalogs.get(locale);
+    if (!catalog)
+        catalogs.set(locale, catalog = new Map());
+    messages.forEach((message, key) => catalog.set(key, message));
+}
+/**
+ * The language of a name of a file or a directory of a catalog (zh-CN.json, zh-CN)
+ * @param name
+ * @param file
+ */
+function localeOfName(name, file) {
+    const locale = (0, Locale_js_1.normalizeLocale)(name);
+    if (!locale || locale.toLowerCase() !== name.toLowerCase().replace(/_/g, '-'))
+        throw new I18nCatalogException_js_1.I18nCatalogException(`${file}: "${name}" is not the tag of a language (en, zh-CN, zh-Hant-TW)`);
+    return locale;
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await (0, promises_1.readFile)(file, 'utf8'));
+    }
+    catch (e) {
+        throw new I18nCatalogException_js_1.I18nCatalogException(`${file}: ${e.message}`);
+    }
+}
+/**
+ * Load the messages of a directory into catalogs: a file by language (zh-CN.json), or a directory by language whose
+ * files (and their directories) prefix their keys (zh-CN/order.json: order.*, zh-CN/admin/user.json: admin.user.*)
+ * @param catalogs
+ * @param directory
+ */
+async function loadDirectory(catalogs, directory) {
+    if (!(0, node_fs_1.existsSync)(directory))
+        throw new I18nCatalogException_js_1.I18nCatalogException(`${directory}: the directory of the messages does not exist`);
+    const entries = (await (0, promises_1.readdir)(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const file = node_path_1.default.join(directory, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.json')) {
+            mergeMessages(catalogs, localeOfName(entry.name.slice(0, -5), file), flattenMessages(await readJson(file), file));
+        }
+        else if (entry.isDirectory()) {
+            const locale = localeOfName(entry.name, file);
+            await loadNamespaces(catalogs, locale, file, '');
+        }
+    }
+}
+/**
+ * Load the files of the directory of a language, their names prefixing their keys
+ * @param catalogs
+ * @param locale
+ * @param directory
+ * @param prefix
+ */
+async function loadNamespaces(catalogs, locale, directory, prefix) {
+    const entries = (await (0, promises_1.readdir)(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const file = node_path_1.default.join(directory, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.json')) {
+            mergeMessages(catalogs, locale, flattenMessages(await readJson(file), file, `${prefix}${entry.name.slice(0, -5)}.`));
+        }
+        else if (entry.isDirectory()) {
+            await loadNamespaces(catalogs, locale, file, `${prefix}${entry.name}.`);
+        }
+    }
+}