@lakutata/i18n 3.0.0-beta.0

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

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

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

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

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

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

package/dist/esm/i18n/lib/CatalogTools.js

@@ -0,0 +1,213 @@
+import { defaultValidationMessages } from '@lakutata/core';
+import { loadDirectory } from './Catalog.js';
+import { I18nCatalogException } from '../exceptions/I18nCatalogException.js';
+import { normalizeLocale } from './Locale.js';
+import { messageArguments, parseMessage } from './MessageFormat.js';
+/**
+ * The prefix of the keys of the messages of the validation errors (their templates are the ones of the validation, not
+ * ICU MessageFormat)
+ */
+const VALIDATION_PREFIX = 'validation.';
+/**
+ * Load the messages of directories as the {@link I18n} component does, to check them or generate their types out of
+ * an application (in a script, a test or the CI).
+ * @param directories The directories, each holding a JSON file (`zh-CN.json`) or a directory (`zh-CN/order.json`) per
+ * language; paths resolved from the working directory (the aliases are not resolved). The later directories replace
+ * the same keys of the earlier ones.
+ * @returns The messages, by language then by key.
+ * @throws {I18nCatalogException} When a directory is missing, a file is not valid JSON, a name is not a language tag
+ * or a key is invalid.
+ * @example
+ * ```typescript
+ * import {loadCatalogs, type Catalogs} from 'lakutata/com/i18n'
+ *
+ * const catalogs: Catalogs = await loadCatalogs(['./locales'])
+ * for (const [locale, messages] of catalogs) console.log(locale, messages.size)
+ * ```
+ */
+export async function loadCatalogs(directories) {
+    const catalogs = new Map();
+    for (const directory of directories)
+        await loadDirectory(catalogs, directory);
+    return catalogs;
+}
+/**
+ * The variables of a template of the validation (#label, #limit)
+ * @param template
+ */
+function templateVariables(template) {
+    return new Set(template.match(/#[A-Za-z]+/g) ?? []);
+}
+/**
+ * Parse a message, its syntax error an issue
+ * @param issues
+ * @param locale
+ * @param key
+ * @param message
+ */
+function parse(issues, locale, key, message) {
+    try {
+        return messageArguments(parseMessage(message, `${locale}: ${key}`));
+    }
+    catch (error) {
+        issues.push({ level: 'error', locale: locale, key: key, message: error.message });
+        return undefined;
+    }
+}
+/**
+ * Check every language's messages against the default language's messages, as `lakutata i18n check` does. It reports:
+ * - errors: an ICU syntax error (in any language), a key the default language does not have, an argument the default
+ *   message does not have (the code does not give it), a `validation.<code>` message whose code is unknown or which
+ *   uses a variable that code does not have (`{{#limit}}`);
+ * - warnings: a key of the default language missing in a language (its fallback is given), an argument of the default
+ *   message not used, a message identical to the default one and containing letters (not translated yet).
+ *
+ * The `validation.*` messages are not compared between languages; they need not exist in the default language.
+ * @param catalogs The messages, as {@link loadCatalogs} gives them.
+ * @param defaultLocale The default language tag, normalized (`zh_CN` is `zh-CN`).
+ * @returns The issues, by language in alphabetical order; empty when everything is right. Only one error when the
+ * default language has no messages.
+ * @example
+ * ```typescript
+ * import {checkCatalogs, loadCatalogs, type CatalogIssue} from 'lakutata/com/i18n'
+ *
+ * const issues: CatalogIssue[] = checkCatalogs(await loadCatalogs(['./locales']), 'en')
+ * for (const issue of issues) console.log(`${issue.level} ${issue.locale} ${issue.key}: ${issue.message}`)
+ * if (issues.some((issue: CatalogIssue): boolean => issue.level === 'error')) process.exitCode = 1
+ * ```
+ */
+export function checkCatalogs(catalogs, defaultLocale) {
+    const issues = [];
+    const base = normalizeLocale(defaultLocale) ?? defaultLocale;
+    const defaults = catalogs.get(base);
+    if (!defaults)
+        return [{ level: 'error', locale: base, key: '', message: `There are no messages of the default language ${base} (${[...catalogs.keys()].join(', ') || 'no language'})` }];
+    const validation = defaultValidationMessages();
+    //The arguments of the default messages
+    const baseArguments = new Map();
+    for (const [key, message] of defaults) {
+        if (!key.startsWith(VALIDATION_PREFIX))
+            baseArguments.set(key, parse(issues, base, key, message));
+    }
+    for (const [locale, messages] of [...catalogs.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        for (const [key, message] of messages) {
+            if (key.startsWith(VALIDATION_PREFIX)) {
+                const code = key.slice(VALIDATION_PREFIX.length);
+                if (!(code in validation)) {
+                    issues.push({ level: 'error', locale: locale, key: key, message: `"${code}" is not a code of the validation errors` });
+                    continue;
+                }
+                const known = templateVariables(validation[code]);
+                const unknown = [...templateVariables(message)].filter((variable) => !known.has(variable));
+                if (unknown.length)
+                    issues.push({ level: 'error', locale: locale, key: key, message: `${unknown.join(', ')} ${unknown.length > 1 ? 'are not variables' : 'is not a variable'} of "${code}" (${[...known].join(', ')})` });
+                continue;
+            }
+            if (locale === base)
+                continue;
+            if (!defaults.has(key)) {
+                issues.push({ level: 'error', locale: locale, key: key, message: `The default language ${base} has no message "${key}"` });
+                continue;
+            }
+            const args = parse(issues, locale, key, message);
+            const expected = baseArguments.get(key);
+            if (!args || !expected)
+                continue;
+            const added = [...args.keys()].filter((name) => !expected.has(name));
+            if (added.length)
+                issues.push({ level: 'error', locale: locale, key: key, message: `The argument${added.length > 1 ? 's' : ''} ${added.join(', ')} of the message ${added.length > 1 ? 'are' : 'is'} not given to the message of ${base}` });
+            const unused = [...expected.keys()].filter((name) => !args.has(name));
+            if (unused.length)
+                issues.push({ level: 'warning', locale: locale, key: key, message: `The argument${unused.length > 1 ? 's' : ''} ${unused.join(', ')} of the message of ${base} ${unused.length > 1 ? 'are' : 'is'} not used` });
+            if (message === defaults.get(key) && /\p{L}/u.test(message))
+                issues.push({ level: 'warning', locale: locale, key: key, message: `The message is the one of ${base} (not translated yet?)` });
+        }
+        if (locale === base)
+            continue;
+        for (const key of defaults.keys()) {
+            if (!key.startsWith(VALIDATION_PREFIX) && !messages.has(key))
+                issues.push({ level: 'warning', locale: locale, key: key, message: 'The message is missing (the one of a fallback is given)' });
+        }
+    }
+    return issues;
+}
+/**
+ * The TypeScript type of an argument of a message, by its use
+ * @param type
+ */
+function argumentType(type) {
+    switch (type) {
+        case 'number':
+            return 'number | bigint';
+        case 'date':
+        case 'time':
+            return 'Date | number | string';
+        case 'plural':
+        case 'selectordinal':
+            return 'number';
+        case 'select':
+            return 'string';
+        default:
+            return 'string | number | bigint | boolean | Date';
+    }
+}
+/**
+ * Whether a message has a currency argument without its currency ({price, number, currency}: the currency argument may
+ * give it)
+ * @param parts
+ */
+function hasCurrency(parts) {
+    return parts.some((part) => typeof part !== 'string' && part.type !== 'pound' &&
+        ((part.type === 'number' && part.style === 'currency') || ('options' in part && Object.values(part.options).some(hasCurrency))));
+}
+/**
+ * A string literal of TypeScript
+ * @param value
+ */
+function literal(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, '\\\'')}'`;
+}
+/**
+ * Generate the TypeScript declaration of the default language's message keys and their arguments (the
+ * {@link I18nMessages} augmentation), as `lakutata i18n types` does. Each argument is typed by its use: `number |
+ * bigint` for `{n, number}`, `number` for a plural, `string` for a select, `Date | number | string` for a date or a
+ * time, any scalar for a plain argument; a currency argument without its currency adds an optional `currency`. The
+ * `validation.*` messages are left out.
+ * @param catalogs The messages, as {@link loadCatalogs} gives them.
+ * @param defaultLocale The default language tag, whose messages are declared.
+ * @param moduleName The module the application imports the i18n from, which the declaration augments:
+ * `'lakutata/com/i18n'` by default, `'@lakutata/i18n'` for the applications importing the package directly.
+ * @returns The source of a `.d.ts` file.
+ * @throws {I18nCatalogException} When the default language has no messages.
+ * @throws {I18nMessageSyntaxException} When a message of the default language is not valid ICU MessageFormat.
+ * @example
+ * ```typescript
+ * import {writeFile} from 'node:fs/promises'
+ * import {generateMessageTypes, loadCatalogs} from 'lakutata/com/i18n'
+ *
+ * await writeFile('src/i18n.d.ts', generateMessageTypes(await loadCatalogs(['./locales']), 'en'))
+ * ```
+ */
+export function generateMessageTypes(catalogs, defaultLocale, moduleName = 'lakutata/com/i18n') {
+    const base = normalizeLocale(defaultLocale) ?? defaultLocale;
+    const defaults = catalogs.get(base);
+    if (!defaults)
+        throw new I18nCatalogException(`There are no messages of the default language ${base}`);
+    const lines = [];
+    for (const key of [...defaults.keys()].filter((name) => !name.startsWith(VALIDATION_PREFIX)).sort()) {
+        const parts = parseMessage(defaults.get(key), `${base}: ${key}`);
+        const fields = [...messageArguments(parts)].map(([name, type]) => `${/^[A-Za-z_$][\w$]*$/.test(name) ? name : literal(name)}: ${argumentType(type)}`);
+        if (hasCurrency(parts) && !messageArguments(parts).has('currency'))
+            fields.push('currency?: string');
+        lines.push(`        ${literal(key)}: ${fields.length ? `{ ${fields.join(', ')} }` : 'Record<string, never>'}`);
+    }
+    return `//Generated by lakutata i18n types from the messages of ${base}: the keys of the messages and their arguments
+import ${literal(moduleName)}
+
+declare module ${literal(moduleName)} {
+    interface I18nMessages {
+${lines.join('\n')}
+    }
+}
+`;
+}

package/dist/esm/i18n/lib/Locale.js

@@ -0,0 +1,173 @@
+/**
+ * Give the canonical BCP 47 form of a language tag (`zh-cn` gives `zh-CN`, `iw` gives `he`). The POSIX locales of the
+ * environment are converted: their encoding and modifier dropped, `_` replaced by `-` (`zh_CN.UTF-8` gives `zh-CN`,
+ * `en_US@euro` gives `en-US`).
+ * @param tag The tag; surrounding spaces are ignored.
+ * @returns The canonical tag; `undefined` for an invalid tag, a tag whose language is not 2 or 3 letters, `C`,
+ * `POSIX`, `*` and the empty string.
+ * @example
+ * ```typescript
+ * import {normalizeLocale} from 'lakutata/com/i18n'
+ *
+ * console.log(normalizeLocale('zh_CN.UTF-8')) //zh-CN
+ * console.log(normalizeLocale('zh-hant-tw')) //zh-Hant-TW
+ * console.log(normalizeLocale('C')) //undefined
+ * ```
+ */
+export function normalizeLocale(tag) {
+    //The encoding and the modifier of the locales of the environment: zh_CN.UTF-8, de_DE@euro
+    const trimmed = tag.trim().replace(/[.@].*$/, '').replace(/_/g, '-');
+    if (!trimmed || trimmed === 'C' || trimmed === 'POSIX' || trimmed === '*')
+        return undefined;
+    //The languages are their codes of ISO 639 (2 or 3 letters): the longer subtags of BCP 47 are reserved
+    if (!/^[a-z]{2,3}(-|$)/i.test(trimmed))
+        return undefined;
+    try {
+        return Intl.getCanonicalLocales(trimmed)[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The language of a tag, without its script and region: zh-Hant-TW → zh
+ * @param locale
+ */
+export function languageOf(locale) {
+    return locale.split('-')[0].toLowerCase();
+}
+/**
+ * Read the languages of an `Accept-Language` header, preferred first: by decreasing quality (`q`, 1 when absent),
+ * then in their order in the header. The tags are normalized ({@link normalizeLocale}); the invalid ones, `*`, and the
+ * ones of quality 0 or an invalid quality are dropped.
+ * @param header The value of the header (`zh-CN,zh;q=0.9,en;q=0.8`).
+ * @returns The language tags, preferred first; empty without a header.
+ * @example
+ * ```typescript
+ * import {parseAcceptLanguage} from 'lakutata/com/i18n'
+ *
+ * console.log(parseAcceptLanguage('en;q=0.5,fr,*;q=0.1')) //['fr', 'en']
+ * ```
+ */
+export function parseAcceptLanguage(header) {
+    if (!header)
+        return [];
+    return header.split(',')
+        .map((part, index) => {
+        const [tag, ...parameters] = part.split(';');
+        const quality = parameters.map((parameter) => parameter.trim()).find((parameter) => parameter.startsWith('q='));
+        return { locale: normalizeLocale(tag), quality: quality === undefined ? 1 : Number(quality.slice(2)), index: index };
+    })
+        .filter((item) => item.locale !== undefined && item.quality > 0 && !Number.isNaN(item.quality))
+        //By quality, then in their order
+        .sort((a, b) => b.quality - a.quality || a.index - b.index)
+        .map((item) => item.locale);
+}
+/**
+ * Read the languages of a process environment, preferred first, as gettext does: the locale is the first of `LC_ALL`,
+ * `LC_MESSAGES` and `LANG` which is set; the colon-separated list of `LANGUAGE` comes before it, but only when that
+ * locale is set and valid (not `C` or `POSIX`). The tags are normalized ({@link normalizeLocale}), the invalid ones
+ * and the duplicates dropped.
+ * @param environment The environment variables: `process.env` by default.
+ * @returns The language tags, preferred first; empty when the environment gives none.
+ * @example
+ * ```typescript
+ * import {environmentLocales} from 'lakutata/com/i18n'
+ *
+ * console.log(environmentLocales({LANG: 'zh_CN.UTF-8', LANGUAGE: 'zh_TW:en'})) //['zh-TW', 'en', 'zh-CN']
+ * ```
+ */
+export function environmentLocales(environment = process.env) {
+    //LANGUAGE is used by gettext only when the locale is not C
+    const locale = environment.LC_ALL || environment.LC_MESSAGES || environment.LANG;
+    const list = locale && normalizeLocale(locale) !== undefined && environment.LANGUAGE ? environment.LANGUAGE.split(':') : [];
+    return unique([...list, ...(locale ? [locale] : [])].map(normalizeLocale).filter((tag) => tag !== undefined));
+}
+/**
+ * The languages of the process, preferred first: the one of an environment variable of the application
+ * (LAKUTATA_LANG), the ones of the environment (environmentLocales), the language of the process (of its ICU)
+ * @param variable the environment variable of the application
+ * @param environment
+ */
+export function processLocales(variable, environment = process.env) {
+    const own = variable ? normalizeLocale(environment[variable] ?? '') : undefined;
+    return unique([...(own ? [own] : []), ...environmentLocales(environment), new Intl.DateTimeFormat().resolvedOptions().locale]);
+}
+/**
+ * Choose the supported language for the requested ones. Each requested language is tried in turn, preferred first,
+ * and the first match wins: the same tag (case-insensitive), then its language alone (`en-GB` matches `en`), then
+ * another tag of its language (`pt-PT` matches `pt-BR`, the first one in the order of `supported`). The invalid
+ * requested tags are skipped.
+ * @param requested The requested language tags, preferred first (from {@link parseAcceptLanguage} or
+ * {@link environmentLocales}).
+ * @param supported The supported language tags.
+ * @param defaultLocale The language returned when none of the requested ones matches.
+ * @returns The matching tag as written in `supported`, or `defaultLocale`.
+ * @example
+ * ```typescript
+ * import {negotiateLocale} from 'lakutata/com/i18n'
+ *
+ * console.log(negotiateLocale(['pt-PT', 'en'], ['en', 'pt-BR'], 'en')) //pt-BR
+ * console.log(negotiateLocale(['de'], ['en', 'zh-CN'], 'en')) //en
+ * ```
+ */
+export function negotiateLocale(requested, supported, defaultLocale) {
+    const canonical = supported.map((tag) => normalizeLocale(tag) ?? tag);
+    const find = (predicate) => {
+        const index = canonical.findIndex(predicate);
+        return index < 0 ? undefined : supported[index];
+    };
+    for (const tag of requested) {
+        const locale = normalizeLocale(tag);
+        if (!locale)
+            continue;
+        const lower = locale.toLowerCase();
+        const language = languageOf(locale);
+        const matched = find((candidate) => candidate.toLowerCase() === lower) ??
+            find((candidate) => candidate.toLowerCase() === language) ??
+            find((candidate) => languageOf(candidate) === language);
+        if (matched)
+            return matched;
+    }
+    return defaultLocale;
+}
+/**
+ * List the languages a message of a language is looked up in, in their order, each once: the language, then each of
+ * its configured fallbacks (followed by their own fallbacks and less specific tags), then its less specific tags
+ * (`zh-Hant-TW`, `zh-Hant`, `zh`), then the default language (and its own fallbacks and less specific tags). The tags
+ * are not normalized: give canonical ones.
+ * @param locale The language tag of the message asked.
+ * @param fallbacks The configured fallbacks, by language tag.
+ * @param defaultLocale The default language tag.
+ * @returns The language tags, in lookup order.
+ * @example
+ * ```typescript
+ * import {fallbackChain} from 'lakutata/com/i18n'
+ *
+ * console.log(fallbackChain('zh-TW', {'zh-TW': ['zh-CN']}, 'en')) //['zh-TW', 'zh-CN', 'zh', 'en']
+ * console.log(fallbackChain('zh-Hant-TW', {}, 'en')) //['zh-Hant-TW', 'zh-Hant', 'zh', 'en']
+ * ```
+ */
+export function fallbackChain(locale, fallbacks, defaultLocale) {
+    const chain = [];
+    const visit = (tag) => {
+        if (chain.includes(tag))
+            return;
+        chain.push(tag);
+        for (const fallback of fallbacks[tag] ?? [])
+            visit(fallback);
+        const parts = tag.split('-');
+        if (parts.length > 1)
+            visit(parts.slice(0, -1).join('-'));
+    };
+    visit(locale);
+    visit(defaultLocale);
+    return chain;
+}
+/**
+ * The values once, in their order
+ * @param values
+ */
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/esm/i18n/lib/LocaleTranslator.js

@@ -0,0 +1,101 @@
+/**
+ * The messages of one language, without giving the language at each call: {@link I18n.translator} creates one, to use
+ * out of a request (a schedule, a singleton component, a background job). Its methods call the component's methods
+ * with its language, so the messages added later with {@link I18n.addMessages} are seen too. In a request, inject the
+ * {@link Translator} instead.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildI18nOptions, type I18n, type ITranslator} from 'lakutata/com/i18n'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'i18n.app',
+ *         name: 'I18n',
+ *         components: {
+ *             i18n: buildI18nOptions({
+ *                 messages: {
+ *                     'en': {order: {count: '{count, plural, =0 {No orders} one {# order} other {# orders}}'}},
+ *                     'de': {order: {count: '{count, plural, =0 {Keine Bestellungen} one {# Bestellung} other {# Bestellungen}}'}}
+ *                 }
+ *             })
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const i18n: I18n = await app.getObject('i18n')
+ *         const german: ITranslator = i18n.translator('de-DE')
+ *         console.log(german.locale) //de-DE, its messages looked up in de-DE, then de, then en
+ *         console.log(german.t('order.count', {count: 1000})) //1.000 Bestellungen
+ *         console.log(german.number(1234.5)) //1.234,5
+ *     })
+ * ```
+ */
+export class LocaleTranslator {
+    /**
+     * Create the translator of a language; {@link I18n.translator} does it, normalizing the language first.
+     * @param i18n The component holding the messages.
+     * @param locale The language tag, canonical.
+     */
+    constructor(i18n, locale) {
+        this.i18n = i18n;
+        this.locale = locale;
+    }
+    /**
+     * 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(key, params) {
+        return this.i18n.t(key, params, this.locale);
+    }
+    /**
+     * 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 LocaleTranslator.t} finds a message for the key.
+     */
+    has(key) {
+        return this.i18n.has(key, this.locale);
+    }
+    /**
+     * 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, params) {
+        return this.i18n.format(message, params, this.locale);
+    }
+    /**
+     * 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.
+     * @throws {RangeError} When the options are invalid (a currency style without its currency).
+     */
+    number(value, options) {
+        return new Intl.NumberFormat(this.locale, options).format(value);
+    }
+    /**
+     * 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.
+     * @throws {RangeError} When the date is invalid or the options are.
+     */
+    date(value, options) {
+        return new Intl.DateTimeFormat(this.locale, { timeZone: this.i18n.getTimeZone(), ...options }).format(value);
+    }
+}