@lakutata/i18n 3.0.0-beta.0

package/dist/esm/i18n/I18n.js

@@ -0,0 +1,454 @@
+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);
+};
+import path from 'node:path';
+import { Component, DTO, loadValidationMessages, registerValidationMessages } from '@lakutata/core';
+import { Configurable } from '@lakutata/core/decorator/di';
+import { flattenMessages, loadDirectory, mergeMessages } from './lib/Catalog.js';
+import { fallbackChain, negotiateLocale, normalizeLocale } from './lib/Locale.js';
+import { formatMessage, parseMessage } from './lib/MessageFormat.js';
+import { LocaleTranslator } from './lib/LocaleTranslator.js';
+import { I18nCatalogException } from './exceptions/I18nCatalogException.js';
+import { I18nMissingKeyException } from './exceptions/I18nMissingKeyException.js';
+/**
+ * Build the component options of an {@link I18n} component, to register it in the `components` of an application.
+ * Name it `i18n`: the {@link I18nMiddleware} and {@link commanderTranslator} use the component of that name by
+ * default. The options are validated when the component is created, not here.
+ * @param options Where the messages come from (`directory`, `messages`), the default language, the fallbacks, the
+ * behavior on a missing message, the currency and time zone of the formatted arguments, the validation messages.
+ * Without options, the component has no messages and its default language is `en`.
+ * @returns The component options (`{class: I18n, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildI18nOptions, type I18n} from 'lakutata/com/i18n'
+ *
+ * Application
+ *     .alias({'@locales': '/srv/shop/locales'})
+ *     .run(() => ({
+ *         id: 'shop.app',
+ *         name: 'Shop',
+ *         components: {
+ *             i18n: buildI18nOptions({
+ *                 //locales/en.json, locales/zh-CN.json, or a directory per language
+ *                 directory: '@locales',
+ *                 defaultLocale: 'en',
+ *                 //A message missing in zh-TW is looked up in zh-CN, then zh, then en
+ *                 fallback: {'zh-TW': 'zh-CN'},
+ *                 currency: 'CNY',
+ *                 timeZone: 'Asia/Shanghai'
+ *             })
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const i18n: I18n = await app.getObject('i18n')
+ *         console.log(i18n.getLocales())
+ *     })
+ * ```
+ */
+export const buildI18nOptions = (options) => ({
+    class: I18n,
+    directory: options?.directory,
+    locales: options?.locales,
+    defaultLocale: options?.defaultLocale,
+    fallback: options?.fallback,
+    messages: options?.messages,
+    missing: options?.missing,
+    currency: options?.currency,
+    timeZone: options?.timeZone,
+    validationMessages: options?.validationMessages
+});
+/**
+ * The internationalization component: the application's messages in each language, by key, written in ICU
+ * MessageFormat (arguments, numbers, currencies, dates, plurals, selects), formatted in their language by the `Intl`
+ * of Node.js. Register it in the `components` of an application with {@link buildI18nOptions}, named `i18n`, and get
+ * it with `getObject()` or `@Inject('i18n')`. In a request, inject the {@link Translator} instead (the
+ * {@link I18nMiddleware} gives it the request's language); out of a request, call {@link I18n.t} with a language or
+ * use {@link I18n.translator}.
+ *
+ * When it is created, the component loads the messages of its `directory` option, then adds the ones of its `messages`
+ * option, and registers the validation messages of its languages. A message missing in a language is looked up in the
+ * languages it falls back to: its `fallback` languages, its less specific tags (`zh-Hant-TW`, `zh-Hant`, `zh`), then
+ * the default language (see {@link fallbackChain}). A message is always formatted in the language asked, even when it
+ * comes from a fallback. A key found nowhere throws {@link I18nMissingKeyException}, or gives the key itself with the
+ * `missing: 'key'` option (the default when `NODE_ENV` is `production`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildI18nOptions, type I18n} from 'lakutata/com/i18n'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'shop.app',
+ *         name: 'Shop',
+ *         components: {
+ *             i18n: buildI18nOptions({
+ *                 messages: {
+ *                     'en': {order: {count: '{count, plural, =0 {No orders} one {# order} other {# orders}}', total: 'Total: {price, number, currency}'}},
+ *                     'zh-CN': {order: {count: '{count, plural, =0 {暂无订单} other {# 个订单}}'}}
+ *                 },
+ *                 currency: 'CNY'
+ *             })
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const i18n: I18n = await app.getObject('i18n')
+ *         console.log(i18n.t('order.count', {count: 1200})) //1,200 orders
+ *         console.log(i18n.t('order.count', {count: 0}, 'zh-CN')) //暂无订单
+ *         //Missing in zh-CN: the English message, formatted in Chinese
+ *         console.log(i18n.t('order.total', {price: 9.5}, 'zh-CN')) //Total: ¥9.50
+ *         console.log(i18n.negotiate(['zh-TW', 'en'])) //zh-CN
+ *     })
+ * ```
+ */
+export class I18n extends Component {
+    #catalogs = new Map();
+    #parsed = new Map();
+    #warned = new Set();
+    #builtIns = new Map();
+    #default = 'en';
+    #supported = [];
+    #fallbacks = {};
+    /**
+     * Load the messages (the directories, then the `messages` option), compute the supported languages and register
+     * the validation messages; called when the component is created.
+     * @throws {I18nCatalogException} When a directory, a file, a key or a language tag of the options is invalid.
+     */
+    async init() {
+        this.#default = this.locale(this.defaultLocale, 'defaultLocale');
+        for (const [locale, fallbacks] of Object.entries(this.fallback ?? {})) {
+            this.#fallbacks[this.locale(locale, 'fallback')] = (Array.isArray(fallbacks) ? fallbacks : [fallbacks]).map((fallback) => this.locale(fallback, 'fallback'));
+        }
+        const directories = this.directory === undefined ? [] : Array.isArray(this.directory) ? this.directory : [this.directory];
+        for (const directory of directories)
+            await loadDirectory(this.#catalogs, this.resolvePath(directory));
+        for (const [locale, messages] of Object.entries(this.messages ?? {}))
+            this.merge(locale, messages);
+        this.#supported = this.locales
+            ? this.locales.map((locale) => this.locale(locale, 'locales'))
+            : this.discovered();
+        await this.registerValidationMessages();
+    }
+    /**
+     * Give the supported languages without the `locales` option: the default language, then the languages having
+     * messages, in alphabetical order.
+     * @returns The canonical tags.
+     */
+    discovered() {
+        return [...new Set([this.#default, ...[...this.#catalogs.keys()].sort()])];
+    }
+    /**
+     * Register the validation error messages of languages, so that the validations run in that language give them. A
+     * language's messages are layered from the end of its fallback chain to itself: for each language of the chain,
+     * its built-in messages (unless `validationMessages` is `false`), then the application's `validation.<code>`
+     * messages (`validation.any.required`), the later ones replacing the earlier ones. Called by `init()` for all the
+     * languages, and by {@link I18n.addMessages} for the languages its messages change.
+     * @param locales The canonical tags of the languages to register: by default, each supported language and each
+     * language having messages.
+     * @throws {SchemaDefinitionException} When a `validation.*` message is not a valid template.
+     */
+    async registerValidationMessages(locales = new Set([...this.#supported, ...this.#catalogs.keys()])) {
+        const prefix = 'validation.';
+        //The built-in messages loaded once for the component's lifetime
+        const builtIns = this.#builtIns;
+        for (const locale of locales) {
+            const messages = {};
+            //The languages it falls back to first, its own messages replacing theirs
+            for (const tag of fallbackChain(locale, this.#fallbacks, this.#default).reverse()) {
+                if (this.validationMessages) {
+                    if (!builtIns.has(tag))
+                        builtIns.set(tag, await loadValidationMessages(tag));
+                    Object.assign(messages, builtIns.get(tag));
+                }
+                this.#catalogs.get(tag)?.forEach((message, key) => {
+                    if (key.startsWith(prefix))
+                        messages[key.slice(prefix.length)] = message;
+                });
+            }
+            if (Object.keys(messages).length)
+                registerValidationMessages(locale, messages);
+        }
+    }
+    /**
+     * Normalize a language tag given in the configuration.
+     * @param tag The language tag.
+     * @param option The name of the option giving it, for the error message.
+     * @returns The canonical tag.
+     * @throws {I18nCatalogException} When the tag is not a language tag.
+     */
+    locale(tag, option) {
+        const locale = normalizeLocale(tag);
+        if (!locale)
+            throw new I18nCatalogException(`${option}: "${tag}" is not the tag of a language (en, zh-CN, zh-Hant-TW)`);
+        return locale;
+    }
+    /**
+     * Resolve a directory of the configuration to an absolute path: an alias (`@locales/en`) by the application
+     * holding the component, any other path from the working directory.
+     * @param directory The path or the alias.
+     * @returns The absolute path.
+     * @throws {I18nCatalogException} When an alias is given and no enclosing module resolves aliases.
+     */
+    resolvePath(directory) {
+        if (!directory.startsWith('@'))
+            return path.resolve(directory);
+        //The application holding the aliases: the module of the module, up to the one with the aliases
+        let module = this.getModule();
+        while (module && typeof module.alias?.resolve !== 'function')
+            module = module.getModule?.();
+        if (!module)
+            throw new I18nCatalogException(`directory: the alias of "${directory}" is resolved by an application`);
+        return path.resolve(module.alias.resolve(directory));
+    }
+    /**
+     * Tell what a missing message or argument does: the `missing` option, else `'key'` when `NODE_ENV` is
+     * `production` and `'throw'` otherwise (read at each call).
+     * @returns `'throw'` or `'key'`.
+     */
+    missingMode() {
+        return this.missing ?? (process.env.NODE_ENV === 'production' ? 'key' : 'throw');
+    }
+    /**
+     * Emit a process warning of type `I18nWarning`, once per distinct text for the component's lifetime.
+     * @param warning The text of the warning.
+     */
+    warn(warning) {
+        if (this.#warned.has(warning))
+            return;
+        this.#warned.add(warning);
+        process.emitWarning(warning, 'I18nWarning');
+    }
+    /**
+     * Give the formatting settings of a language: the language, the configured currency and time zone, and what a
+     * missing argument or currency does (thrown, or kept with a warning emitted once by {@link I18n.warn}).
+     * @param locale The canonical language tag the message is formatted in.
+     * @returns The formatting settings.
+     */
+    context(locale) {
+        return {
+            locale: locale,
+            currency: this.currency,
+            timeZone: this.timeZone,
+            missing: this.missingMode() === 'throw' ? 'throw' : 'keep',
+            warn: (warning) => this.warn(warning)
+        };
+    }
+    /**
+     * Give the supported languages: the `locales` option, or the default language then the languages having messages
+     * (the ones added by {@link I18n.addMessages} included), in alphabetical order.
+     * @returns A copy of the canonical tags.
+     */
+    getLocales() {
+        return [...this.#supported];
+    }
+    /**
+     * Give the default language.
+     * @returns The canonical tag of the `defaultLocale` option (`en` by default).
+     */
+    getDefaultLocale() {
+        return this.#default;
+    }
+    /**
+     * Give the time zone the dates and the times are formatted in.
+     * @returns The `timeZone` option; `undefined` when it is not set (the process's time zone is then used).
+     */
+    getTimeZone() {
+        return this.timeZone;
+    }
+    /**
+     * List the keys a language has messages for: its own keys, not the ones of the languages it falls back to.
+     * @param locale The language tag (normalized; `zh_CN` is `zh-CN`).
+     * @returns The full keys (`order.count`), in their loading order; empty for a language without messages.
+     */
+    getKeys(locale) {
+        return [...(this.#catalogs.get(normalizeLocale(locale) ?? locale)?.keys() ?? [])];
+    }
+    /**
+     * Add messages to a language at run time, replacing the messages of the same keys; {@link I18n.t} gives them as
+     * soon as it returns. As for the messages loaded at the creation, a new language is added to the supported
+     * languages ({@link I18n.getLocales}, {@link I18n.negotiate}) unless the `locales` option lists them, and the
+     * validation messages of the new language (its built-in ones) and of the `validation.*` messages added are
+     * registered, for the language and the languages falling back to it.
+     * @param locale The language tag (normalized).
+     * @param messages The messages, nested by the parts of their keys (`{order: {count: '...'}}`).
+     * @returns A promise resolved once the validation messages are registered (the built-in ones of a language are
+     * loaded on demand); it rejects with a `SchemaDefinitionException` when a `validation.*` message is not a valid
+     * template.
+     * @throws {I18nCatalogException} When the tag is not a language tag, or a key or a value is invalid: thrown by the
+     * call, nothing added.
+     * @example
+     * ```typescript
+     * import {type I18n} from 'lakutata/com/i18n'
+     *
+     * declare const i18n: I18n
+     *
+     * await i18n.addMessages('fr', {order: {created: 'Commande créée pour {customer}'}, validation: {any: {required: '{{#label}} est obligatoire'}}})
+     * console.log(i18n.negotiate(['fr-CA'])) //fr
+     * console.log(i18n.t('order.created', {customer: 'Ada'}, 'fr')) //Commande créée pour Ada
+     * ```
+     */
+    addMessages(locale, messages) {
+        const tag = this.locale(locale, 'messages');
+        const known = this.#catalogs.has(tag);
+        const flattened = this.merge(tag, messages);
+        if (!this.locales)
+            this.#supported = this.discovered();
+        //The validation messages changed: the language's built-in ones when it is new, its validation.* messages
+        if (known && ![...flattened.keys()].some((key) => key.startsWith('validation.')))
+            return Promise.resolve();
+        const changed = [...new Set([...this.#supported, ...this.#catalogs.keys()])].filter((candidate) => fallbackChain(candidate, this.#fallbacks, this.#default).includes(tag));
+        return this.registerValidationMessages(changed);
+    }
+    /**
+     * Merge messages into the catalog of a language, its cached parsed messages dropped.
+     * @param locale The language tag.
+     * @param messages The nested messages.
+     * @returns The messages merged, by full key.
+     * @throws {I18nCatalogException} When the tag is not a language tag, or a key or a value is invalid.
+     */
+    merge(locale, messages) {
+        const tag = this.locale(locale, 'messages');
+        const flattened = flattenMessages(messages, `messages of ${tag}`);
+        mergeMessages(this.#catalogs, tag, flattened);
+        //The messages replaced are parsed again
+        for (const key of this.#parsed.keys())
+            if (key.startsWith(`${tag}\u0000`))
+                this.#parsed.delete(key);
+        return flattened;
+    }
+    /**
+     * Choose the supported language for the requested ones (see {@link negotiateLocale}): for each requested language
+     * in turn, the same tag, then its language alone (`en-GB` gives `en`), then another tag of its language (`pt-PT`
+     * gives `pt-BR`).
+     * @param requested The requested language tags, preferred first; the invalid ones are skipped.
+     * @returns A supported language, or the default language when none matches.
+     */
+    negotiate(requested) {
+        return negotiateLocale(requested, this.#supported, this.#default);
+    }
+    /**
+     * Find the message of a key in a language or the languages it falls back to, parsed once and cached.
+     * @param key The key of the message.
+     * @param locale The canonical language tag.
+     * @returns The parsed message and the language it was found in; `undefined` when no language of the chain has it.
+     * @throws {I18nMessageSyntaxException} When the message found is not valid ICU MessageFormat.
+     */
+    message(key, locale) {
+        for (const tag of fallbackChain(locale, this.#fallbacks, this.#default)) {
+            const message = this.#catalogs.get(tag)?.get(key);
+            if (message === undefined)
+                continue;
+            const cacheKey = `${tag}\u0000${key}`;
+            let parts = this.#parsed.get(cacheKey);
+            if (!parts)
+                this.#parsed.set(cacheKey, parts = parseMessage(message, `${tag}: ${key}`));
+            return { parts: parts, locale: tag };
+        }
+        return undefined;
+    }
+    /**
+     * Tell whether a key has a message in a language or in the languages it falls back to.
+     * @param key The key of the message.
+     * @param locale The language tag: the default language by default, and when it is not a language tag.
+     * @returns `true` when {@link I18n.t} finds a message for the key in that language.
+     */
+    has(key, locale = this.#default) {
+        return fallbackChain(normalizeLocale(locale) ?? this.#default, this.#fallbacks, this.#default).some((tag) => !!this.#catalogs.get(tag)?.has(key));
+    }
+    /**
+     * Give the message of a key in a language, formatted with its arguments. The language is not negotiated: the
+     * message is looked up in the language given, then in the languages it falls back to (see {@link I18n}), and is
+     * formatted in the language given (its numbers, dates and plural rules) even when it comes from a fallback.
+     * @param key The key of the message (`order.count`).
+     * @param params The arguments of the message, by their names: the numbers and the bigints are formatted in the
+     * language, the `Date` objects as dates. A `currency` argument gives the currency of `{price, number, currency}`.
+     * @param locale The language tag: the default language by default, and when it is not a language tag.
+     * @returns The formatted message. With `missing: 'key'`, the key itself when no message has it, `{name}` in place
+     * of a missing argument, and a plain number for a currency argument without a currency, each with a warning
+     * emitted once (per key, or per message and argument).
+     * @throws {I18nMissingKeyException} When no message has the key and the `missing` mode is `'throw'`.
+     * @throws {I18nMissingParameterException} When an argument is missing, or a currency argument has no currency, and
+     * the `missing` mode is `'throw'`.
+     * @throws {I18nMessageSyntaxException} When the message is not valid ICU MessageFormat.
+     */
+    t(key, params, locale = this.#default) {
+        const tag = normalizeLocale(locale) ?? this.#default;
+        const message = this.message(key, tag);
+        if (!message) {
+            const missing = `No message "${key}" in ${fallbackChain(tag, this.#fallbacks, this.#default).join(', ')}`;
+            if (this.missingMode() === 'throw')
+                throw new I18nMissingKeyException(missing);
+            this.warn(missing);
+            return key;
+        }
+        //Formatted in the language asked, its numbers and plurals too
+        return formatMessage(message.parts, (params ?? {}), this.context(tag), `${message.locale}: ${key}`);
+    }
+    /**
+     * Format an ICU MessageFormat message which is not in the catalogs (parsed at each call).
+     * @param message The message (`Hello, {name}`).
+     * @param params The arguments of the message, by their names.
+     * @param locale The language tag it is formatted in: the default language by default, and when it is not a
+     * language tag.
+     * @returns The formatted message. With `missing: 'key'`, `{name}` in place of a missing argument and a plain
+     * number for a currency argument without a currency, each with a warning emitted once per message and argument.
+     * @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` mode is `'throw'`.
+     */
+    format(message, params, locale = this.#default) {
+        const tag = normalizeLocale(locale) ?? this.#default;
+        return formatMessage(parseMessage(message), params ?? {}, this.context(tag), `message "${message}"`);
+    }
+    /**
+     * Create a translator of a language, which gives its messages without the language at each call. The language is
+     * not negotiated: it is used as given (its messages falling back as in {@link I18n.t}).
+     * @param locale The language tag (normalized): the default language when it is not a language tag.
+     * @returns The translator, a {@link LocaleTranslator}.
+     */
+    translator(locale) {
+        return new LocaleTranslator(this, normalizeLocale(locale) ?? this.#default);
+    }
+}
+__decorate([
+    Configurable(DTO.Alternatives(DTO.String(), DTO.Array(DTO.String())).optional()),
+    __metadata("design:type", Object)
+], I18n.prototype, "directory", void 0);
+__decorate([
+    Configurable(DTO.Array(DTO.String()).optional()),
+    __metadata("design:type", Array)
+], I18n.prototype, "locales", void 0);
+__decorate([
+    Configurable(DTO.String().optional().default('en')),
+    __metadata("design:type", String)
+], I18n.prototype, "defaultLocale", void 0);
+__decorate([
+    Configurable(DTO.Object().pattern(DTO.String(), DTO.Alternatives(DTO.String(), DTO.Array(DTO.String()))).optional()),
+    __metadata("design:type", Object)
+], I18n.prototype, "fallback", void 0);
+__decorate([
+    Configurable(DTO.Object().pattern(DTO.String(), DTO.Object().unknown()).optional()),
+    __metadata("design:type", Object)
+], I18n.prototype, "messages", void 0);
+__decorate([
+    Configurable(DTO.String().valid('throw', 'key').optional()),
+    __metadata("design:type", String)
+], I18n.prototype, "missing", void 0);
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], I18n.prototype, "currency", void 0);
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], I18n.prototype, "timeZone", void 0);
+__decorate([
+    Configurable(DTO.Boolean().optional().default(true)),
+    __metadata("design:type", Boolean)
+], I18n.prototype, "validationMessages", void 0);

package/dist/esm/i18n/Translator.js

@@ -0,0 +1,153 @@
+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);
+};
+import { DTO, Provider } from '@lakutata/core';
+import { Autoload, Configurable, Scoped } from '@lakutata/core/decorator/di';
+import { I18nTranslatorException } from './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 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('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);
+    }
+};
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], Translator.prototype, "locale", void 0);
+__decorate([
+    Configurable(DTO.Any().optional()),
+    __metadata("design:type", Function)
+], Translator.prototype, "i18n", void 0);
+Translator = __decorate([
+    Scoped(),
+    Autoload()
+], Translator);
+export { Translator };

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

@@ -0,0 +1,18 @@
+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 class I18nCatalogException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_CATALOG'`.
+         */
+        this.errno = 'E_I18N_CATALOG';
+    }
+}

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

@@ -0,0 +1,17 @@
+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 class I18nMessageSyntaxException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_MESSAGE_SYNTAX'`.
+         */
+        this.errno = 'E_I18N_MESSAGE_SYNTAX';
+    }
+}

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

@@ -0,0 +1,15 @@
+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 class I18nMissingKeyException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_I18N_MISSING_KEY'`.
+         */
+        this.errno = 'E_I18N_MISSING_KEY';
+    }
+}