@lakutata/i18n 3.0.0-beta.0

package/dist/types/i18n/I18n.d.ts

@@ -0,0 +1,313 @@
+import { Component, type ComponentOptionsBuilder } from '@lakutata/core';
+import type { I18nOptions } from './interfaces/I18nOptions.js';
+import { type NestedMessages } from './lib/Catalog.js';
+import { type FormatContext, type MessagePart } from './lib/MessageFormat.js';
+import type { ITranslator } from './interfaces/ITranslator.js';
+import type { MessageKey, MessageParams } from './types/I18nMessages.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 declare const buildI18nOptions: ComponentOptionsBuilder<I18nOptions>;
+/**
+ * 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 declare class I18n extends Component {
+    #private;
+    /**
+     * The directories holding the messages, read when the component is created (see {@link I18nOptions.directory}):
+     * a path, an alias of the application (`@locales`), or several, the later ones replacing the same keys.
+     * @default none
+     */
+    protected readonly directory?: string | string[];
+    /**
+     * The languages {@link I18n.negotiate} chooses from, as language tags.
+     * @default the default language, then the languages of the messages in alphabetical order
+     */
+    protected readonly locales?: string[];
+    /**
+     * The default language: the last one a message is looked up in, the one of the calls without a language, and the
+     * one chosen when no requested language is supported.
+     * @default 'en'
+     */
+    protected readonly defaultLocale: string;
+    /**
+     * The languages a message missing in a language is looked up in next, by language (`{'zh-TW': 'zh-CN'}`).
+     * @default none
+     */
+    protected readonly fallback?: Record<string, string | string[]>;
+    /**
+     * The messages given in the code, by language tag, added after the ones of `directory` and replacing their keys.
+     * @default none
+     */
+    protected readonly messages?: Record<string, NestedMessages>;
+    /**
+     * What a missing message or argument does: `'throw'` throws; `'key'` gives the key, writes the argument as
+     * `{name}`, or formats a `{price, number, currency}` without a currency as a plain number, with a warning, once
+     * per message and key, argument or currency.
+     * @default 'throw', and 'key' when NODE_ENV is 'production'
+     */
+    protected readonly missing?: 'throw' | 'key';
+    /**
+     * The currency (ISO 4217) of the `{price, number, currency}` arguments whose style and arguments give none.
+     * @default none
+     */
+    protected readonly currency?: string;
+    /**
+     * The time zone (IANA) of the formatted dates and times.
+     * @default the process's time zone
+     */
+    protected readonly timeZone?: string;
+    /**
+     * Whether the built-in validation error messages of the languages are registered.
+     * @default true
+     */
+    protected readonly validationMessages: boolean;
+    /**
+     * 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.
+     */
+    protected init(): Promise<void>;
+    /**
+     * Give the supported languages without the `locales` option: the default language, then the languages having
+     * messages, in alphabetical order.
+     * @returns The canonical tags.
+     */
+    protected discovered(): string[];
+    /**
+     * 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.
+     */
+    protected registerValidationMessages(locales?: Iterable<string>): Promise<void>;
+    /**
+     * 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.
+     */
+    protected locale(tag: string, option: string): string;
+    /**
+     * 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.
+     */
+    protected resolvePath(directory: string): string;
+    /**
+     * 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'`.
+     */
+    protected missingMode(): 'throw' | 'key';
+    /**
+     * Emit a process warning of type `I18nWarning`, once per distinct text for the component's lifetime.
+     * @param warning The text of the warning.
+     */
+    protected warn(warning: string): void;
+    /**
+     * 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.
+     */
+    protected context(locale: string): FormatContext;
+    /**
+     * 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(): string[];
+    /**
+     * Give the default language.
+     * @returns The canonical tag of the `defaultLocale` option (`en` by default).
+     */
+    getDefaultLocale(): string;
+    /**
+     * 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(): string | undefined;
+    /**
+     * 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: string): string[];
+    /**
+     * 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: string, messages: NestedMessages): Promise<void>;
+    /**
+     * 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.
+     */
+    protected merge(locale: string, messages: NestedMessages): Map<string, string>;
+    /**
+     * 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: string[]): string;
+    /**
+     * 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.
+     */
+    protected message(key: string, locale: string): {
+        parts: MessagePart[];
+        locale: string;
+    } | 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: string, locale?: string): boolean;
+    /**
+     * 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<K extends MessageKey>(key: K, params?: MessageParams<K>, locale?: string): string;
+    /**
+     * 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: string, params?: Record<string, unknown>, locale?: string): string;
+    /**
+     * 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: string): ITranslator;
+}

package/dist/types/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;
+}

package/dist/types/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/types/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/types/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/types/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/types/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/types/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/types/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;
+}