@lakutata/i18n 3.0.0-beta.0

package/dist/cjs/i18n/I18n.js

@@ -0,0 +1,462 @@
+"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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18n = exports.buildI18nOptions = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const Catalog_js_1 = require("./lib/Catalog.js");
+const Locale_js_1 = require("./lib/Locale.js");
+const MessageFormat_js_1 = require("./lib/MessageFormat.js");
+const LocaleTranslator_js_1 = require("./lib/LocaleTranslator.js");
+const I18nCatalogException_js_1 = require("./exceptions/I18nCatalogException.js");
+const I18nMissingKeyException_js_1 = require("./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())
+ *     })
+ * ```
+ */
+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
+});
+exports.buildI18nOptions = buildI18nOptions;
+/**
+ * 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
+ *     })
+ * ```
+ */
+class I18n extends core_1.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 (0, Catalog_js_1.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 (0, Locale_js_1.fallbackChain)(locale, this.#fallbacks, this.#default).reverse()) {
+                if (this.validationMessages) {
+                    if (!builtIns.has(tag))
+                        builtIns.set(tag, await (0, core_1.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)
+                (0, core_1.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 = (0, Locale_js_1.normalizeLocale)(tag);
+        if (!locale)
+            throw new I18nCatalogException_js_1.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 node_path_1.default.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_js_1.I18nCatalogException(`directory: the alias of "${directory}" is resolved by an application`);
+        return node_path_1.default.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((0, Locale_js_1.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) => (0, Locale_js_1.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 = (0, Catalog_js_1.flattenMessages)(messages, `messages of ${tag}`);
+        (0, Catalog_js_1.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 (0, Locale_js_1.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 (0, Locale_js_1.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 = (0, MessageFormat_js_1.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 (0, Locale_js_1.fallbackChain)((0, Locale_js_1.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 = (0, Locale_js_1.normalizeLocale)(locale) ?? this.#default;
+        const message = this.message(key, tag);
+        if (!message) {
+            const missing = `No message "${key}" in ${(0, Locale_js_1.fallbackChain)(tag, this.#fallbacks, this.#default).join(', ')}`;
+            if (this.missingMode() === 'throw')
+                throw new I18nMissingKeyException_js_1.I18nMissingKeyException(missing);
+            this.warn(missing);
+            return key;
+        }
+        //Formatted in the language asked, its numbers and plurals too
+        return (0, MessageFormat_js_1.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 = (0, Locale_js_1.normalizeLocale)(locale) ?? this.#default;
+        return (0, MessageFormat_js_1.formatMessage)((0, MessageFormat_js_1.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_js_1.LocaleTranslator(this, (0, Locale_js_1.normalizeLocale)(locale) ?? this.#default);
+    }
+}
+exports.I18n = I18n;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Alternatives(core_1.DTO.String(), core_1.DTO.Array(core_1.DTO.String())).optional()),
+    __metadata("design:type", Object)
+], I18n.prototype, "directory", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array(core_1.DTO.String()).optional()),
+    __metadata("design:type", Array)
+], I18n.prototype, "locales", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().optional().default('en')),
+    __metadata("design:type", String)
+], I18n.prototype, "defaultLocale", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Object().pattern(core_1.DTO.String(), core_1.DTO.Alternatives(core_1.DTO.String(), core_1.DTO.Array(core_1.DTO.String()))).optional()),
+    __metadata("design:type", Object)
+], I18n.prototype, "fallback", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Object().pattern(core_1.DTO.String(), core_1.DTO.Object().unknown()).optional()),
+    __metadata("design:type", Object)
+], I18n.prototype, "messages", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().valid('throw', 'key').optional()),
+    __metadata("design:type", String)
+], I18n.prototype, "missing", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], I18n.prototype, "currency", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], I18n.prototype, "timeZone", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Boolean().optional().default(true)),
+    __metadata("design:type", Boolean)
+], I18n.prototype, "validationMessages", void 0);

package/dist/cjs/i18n/Translator.d.ts

@@ -0,0 +1,124 @@
+import { Provider } from '@lakutata/core';
+import type { I18n } from './I18n.js';
+import type { ITranslator } from './interfaces/ITranslator.js';
+import type { MessageKey, MessageParams } from './types/I18nMessages.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']
+ * }))
+ * ```
+ */
+export declare class Translator extends Provider implements ITranslator {
+    #private;
+    /**
+     * The request's language tag, negotiated by the {@link I18nMiddleware} among the supported languages (the same as
+     * `context.locale`); `undefined` without the middleware.
+     */
+    readonly locale: string;
+    /**
+     * The {@link I18n} component giving the messages, set by the {@link I18nMiddleware}.
+     */
+    protected readonly i18n?: I18n;
+    /**
+     * Create the translator of the language given by the middleware, when it gave one.
+     */
+    protected init(): Promise<void>;
+    /**
+     * 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).
+     */
+    protected get translator(): ITranslator;
+    /**
+     * 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<K extends MessageKey>(key: K, params?: MessageParams<K>): string;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string, params?: Record<string, unknown>): string;
+    /**
+     * 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: number | bigint, options?: Intl.NumberFormatOptions): string;
+    /**
+     * 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: Date | number, options?: Intl.DateTimeFormatOptions): string;
+}