@lakutata/i18n 3.0.0-beta.0

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

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

package/dist/types/i18n/lib/CatalogTools.d.ts

@@ -0,0 +1,86 @@
+import { type Catalogs } from './Catalog.js';
+/**
+ * A problem found by {@link checkCatalogs} in the messages.
+ */
+export type CatalogIssue = {
+    /**
+     * `'error'` for a message which cannot be right (it fails or loses an argument when it is formatted), `'warning'`
+     * for a message to look at (missing, or not translated yet).
+     */
+    level: 'error' | 'warning';
+    /**
+     * The language tag of the message.
+     */
+    locale: string;
+    /**
+     * The key of the message (`order.count`); `''` when the default language has no messages at all.
+     */
+    key: string;
+    /**
+     * What is wrong, in English.
+     */
+    message: string;
+};
+/**
+ * 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 declare function loadCatalogs(directories: string[]): Promise<Catalogs>;
+/**
+ * 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 declare function checkCatalogs(catalogs: Catalogs, defaultLocale: string): CatalogIssue[];
+/**
+ * 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 declare function generateMessageTypes(catalogs: Catalogs, defaultLocale: string, moduleName?: string): string;

package/dist/types/i18n/lib/Locale.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 declare function normalizeLocale(tag: string): string | undefined;
+/**
+ * The language of a tag, without its script and region: zh-Hant-TW → zh
+ * @param locale
+ */
+export declare function languageOf(locale: string): string;
+/**
+ * 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 declare function parseAcceptLanguage(header: string | undefined): string[];
+/**
+ * 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 declare function environmentLocales(environment?: NodeJS.ProcessEnv): string[];
+/**
+ * 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 declare function processLocales(variable?: string, environment?: NodeJS.ProcessEnv): string[];
+/**
+ * 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 declare function negotiateLocale(requested: string[], supported: string[], defaultLocale: string): string;
+/**
+ * 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 declare function fallbackChain(locale: string, fallbacks: Record<string, string[]>, defaultLocale: string): string[];

package/dist/types/i18n/lib/LocaleTranslator.d.ts

@@ -0,0 +1,93 @@
+import type { I18n } from '../I18n.js';
+import type { ITranslator } from '../interfaces/ITranslator.js';
+import type { MessageKey, MessageParams } from '../types/I18nMessages.js';
+/**
+ * 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 declare class LocaleTranslator implements ITranslator {
+    protected readonly i18n: I18n;
+    readonly locale: string;
+    /**
+     * 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: I18n, 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 LocaleTranslator.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.
+     * @throws {RangeError} When the options are invalid (a currency style without its currency).
+     */
+    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.
+     * @throws {RangeError} When the date is invalid or the options are.
+     */
+    date(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+}

package/dist/types/i18n/lib/MessageFormat.d.ts

@@ -0,0 +1,144 @@
+/**
+ * A part of a message parsed by {@link parseMessage}: a literal text (a string, its quoting already removed), a plain
+ * argument (`{name}`), a number argument (`{n, number, percent}`), a date or time argument (`{at, date, short}`), a
+ * choice (`plural`, `selectordinal`, `select`), or the `#` of a plural (its number).
+ */
+export type MessagePart = string | {
+    /**
+     * A plain argument, `{name}`: a number formatted in the language, a `Date` as a date, anything else as a string.
+     */
+    type: 'argument';
+    /**
+     * The name of the argument.
+     */
+    name: string;
+} | {
+    /**
+     * A number argument, `{name, number}` or `{name, number, style}`.
+     */
+    type: 'number';
+    /**
+     * The name of the argument.
+     */
+    name: string;
+    /**
+     * The style: `integer`, `percent`, `currency` or `currency/XXX` (an ISO 4217 code); absent for a plain number.
+     */
+    style?: string;
+} | {
+    /**
+     * A date argument (`{name, date, style}`) or a time argument (`{name, time, style}`).
+     */
+    type: 'date' | 'time';
+    /**
+     * The name of the argument.
+     */
+    name: string;
+    /**
+     * The style: `short`, `medium`, `long` or `full`; absent for `medium`.
+     */
+    style?: string;
+} | {
+    /**
+     * A cardinal (`plural`) or ordinal (`selectordinal`) choice on a number argument.
+     */
+    type: 'plural' | 'selectordinal';
+    /**
+     * The name of the argument.
+     */
+    name: string;
+    /**
+     * The `offset:` of the choice, subtracted from the number before its plural rule and its `#`; 0 without it.
+     */
+    offset: number;
+    /**
+     * The messages by selector: `=0` (an exact value, matched before the offset), a plural category of the
+     * language (`zero`, `one`, `two`, `few`, `many`), and the required `other`.
+     */
+    options: Record<string, MessagePart[]>;
+} | {
+    /**
+     * A choice on the string value of an argument, `{name, select, admin {...} other {...}}`.
+     */
+    type: 'select';
+    /**
+     * The name of the argument.
+     */
+    name: string;
+    /**
+     * The messages by value of the argument, and the required `other`.
+     */
+    options: Record<string, MessagePart[]>;
+} | {
+    /**
+     * The `#` of a plural: the number of the closest enclosing `plural` or `selectordinal` (minus its offset),
+     * formatted in the language.
+     */
+    type: 'pound';
+};
+/**
+ * How a message is formatted
+ */
+export type FormatContext = {
+    locale: string;
+    /**
+     * The currency of {price, number, currency} (ISO 4217)
+     */
+    currency?: string;
+    /**
+     * The time zone of the dates and the times (IANA)
+     */
+    timeZone?: string;
+    /**
+     * An argument or a currency missing: thrown, or kept (the argument as it is written, {name}; the number without
+     * currency) with a warning
+     */
+    missing: 'throw' | 'keep';
+    /**
+     * Told what is kept when missing is 'keep'
+     */
+    warn?: (warning: string) => void;
+};
+/**
+ * Parse an ICU MessageFormat message into its parts, to inspect it (its arguments: {@link messageArguments}). The
+ * syntax: `{name}`; `{name, number}` with the styles `integer`, `percent`, `currency`, `currency/XXX`; `{name, date}`
+ * and `{name, time}` with the styles `short`, `medium`, `long`, `full`; `{name, plural, ...}` (with `offset:n`),
+ * `{name, selectordinal, ...}` and `{name, select, ...}`, each requiring an `other` option; `#` in a plural; `''` for
+ * an apostrophe and `'{...}'` to quote the braces (and `#` in a plural). Other argument types and the skeletons
+ * (`::currency/EUR`) are not supported.
+ * @param message The message.
+ * @param source Where the message comes from (`zh-CN: order.count`), the prefix of the error messages: `'message'` by
+ * default.
+ * @returns The parts of the message.
+ * @throws {I18nMessageSyntaxException} When the message is not valid, with the source and the position.
+ * @example
+ * ```typescript
+ * import {parseMessage, type MessagePart} from 'lakutata/com/i18n'
+ *
+ * const parts: MessagePart[] = parseMessage('{count, plural, one {# order} other {# orders}} for {customer}')
+ * console.log(parts.length) //3
+ * ```
+ */
+export declare function parseMessage(message: string, source?: string): MessagePart[];
+/**
+ * List the arguments a parsed message uses, nested choices included, with the type of their first use: `argument`,
+ * `number`, `date`, `time`, `plural`, `selectordinal` or `select`.
+ * @param parts The parts of the message, from {@link parseMessage}.
+ * @returns The argument types by argument name, in their order in the message.
+ * @example
+ * ```typescript
+ * import {messageArguments, parseMessage} from 'lakutata/com/i18n'
+ *
+ * const args: Map<string, string> = messageArguments(parseMessage('{count, plural, other {# orders}} for {customer}'))
+ * console.log([...args]) //[['count', 'plural'], ['customer', 'argument']]
+ * ```
+ */
+export declare function messageArguments(parts: MessagePart[]): Map<string, string>;
+/**
+ * Format a parsed message
+ * @param parts
+ * @param params
+ * @param context
+ * @param source where the message is (its key), for the errors
+ */
+export declare function formatMessage(parts: MessagePart[], params: Record<string, unknown>, context: FormatContext, source?: string): string;

package/dist/types/i18n/middleware/CommanderTranslator.d.ts

@@ -0,0 +1,71 @@
+import type { Module } from '@lakutata/core';
+import type { CLITranslate } from '@lakutata/entrypoint/adapter/commander';
+/**
+ * The options of {@link commanderTranslator}.
+ */
+export type CommanderTranslatorOptions = {
+    /**
+     * The name the {@link I18n} component is registered under.
+     * @default 'i18n'
+     */
+    component?: string;
+    /**
+     * The prefix of the message keys of the texts: with `'cli'`, the description of the command `greet` is the message
+     * `cli.commands.greet.description`; `''` for no prefix.
+     * @default 'cli'
+     */
+    prefix?: string;
+    /**
+     * The name of an environment variable (`LAKUTATA_LANG`) whose language is preferred to the ones of the environment.
+     * @default none
+     */
+    environment?: string;
+};
+/**
+ * Translate the help and the prompts of the Commander CLI adapter with the messages of an {@link I18n} component: give
+ * it to the `translate` option of `commanderCLIEntrypoint()`. Each text is the message of its key under the prefix
+ * (`cli.description`, `cli.commands.<command>.description`, `cli.commands.<command>.arguments.<name>`,
+ * `cli.commands.<command>.options.<property>`, `cli.help.usage`, `cli.help.options`, `cli.help.default`,
+ * `cli.prompt.json`…), formatted with the text's parameters (`{value}`); a text without a message keeps its English
+ * text. The language is chosen once, when the adapter starts: the environment variable of the `environment` option,
+ * the environment ({@link environmentLocales}), then the process's language, negotiated with the component's
+ * supported languages. The names of the commands and of the options are never translated.
+ * @param options The component, the key prefix and the environment variable.
+ * @returns The `translate` function of the adapter, which gets the component from the application's module.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {commanderCLIEntrypoint} from 'lakutata/adapter/commander'
+ * import {CLIAction} from 'lakutata/decorator/ctrl'
+ * import {buildI18nOptions, commanderTranslator, I18nMiddleware} from 'lakutata/com/i18n'
+ *
+ * class GreetController extends Controller {
+ *     @CLIAction('greet', {description: 'Greet someone'})
+ *     public async greet(): Promise<string> {
+ *         return 'Hello'
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'tool.app',
+ *     name: 'Tool',
+ *     components: {
+ *         i18n: buildI18nOptions({
+ *             messages: {
+ *                 'zh-CN': {cli: {commands: {greet: {description: '问候某人'}}, help: {usage: '用法：', options: '选项：'}}}
+ *             }
+ *         }),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [GreetController],
+ *             //The controllers' Translator in the same language
+ *             middlewares: [I18nMiddleware],
+ *             //LANG=zh_CN.UTF-8 tool --help: the help in Chinese
+ *             cli: commanderCLIEntrypoint({bin: 'tool', translate: commanderTranslator({environment: 'TOOL_LANG'})})
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+export declare function commanderTranslator(options?: CommanderTranslatorOptions): (module: Module) => Promise<CLITranslate>;

package/dist/types/i18n/middleware/I18nMiddleware.d.ts

@@ -0,0 +1,126 @@
+import type { IncomingMessage } from 'node:http';
+import { Middleware, type ActionInvocation, type BaseContext, type Next } from '@lakutata/entrypoint';
+import type { I18n } from '../I18n.js';
+import { Translator } from '../Translator.js';
+/**
+ * The entrypoint middleware choosing the language of each request. Add it to the `middlewares` of
+ * `buildEntrypoints()`. For each request, it reads the languages the request asks for ({@link I18nMiddleware.requested}),
+ * negotiates them with the supported languages of the {@link I18n} component ({@link I18n.negotiate}, the default
+ * language when none matches), and makes the result:
+ * - the request's `context.locale`;
+ * - the language of the {@link Translator} the request's objects inject;
+ * - the language of the validation errors of the request (its input, `@Accept`/`@Return`, the `DTO.validate` calls of
+ *   its code);
+ * - the language of the exceptions it throws: a lakutata `Exception` whose `errno` has a message `errors.<errno>`
+ *   (`errors.E_ORDER_NOT_FOUND`) gets that message, formatted with the exception's template parameters.
+ *
+ * The languages are read, preferred first: for HTTP, the `lang` query parameter, the `lang` cookie, then
+ * `Accept-Language`; for Socket.IO, the same from the connection's handshake; for the HTTP service adapter and the
+ * JSON-RPC adapter over HTTP or WebSocket, the same from the HTTP request (for WebSocket, the request opening the
+ * connection); for the command line and the other service transports, the process's environment
+ * ({@link environmentLocales}) then the process's language; for the schedules, none. It uses the component registered as `i18n`; a subclass changes the component, the names of the query
+ * parameter and of the cookie, or the languages read (`requested()`).
+ * @example
+ * ```typescript
+ * import {type BaseContext} from 'lakutata/com/entrypoint'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {I18nMiddleware, type I18n} from 'lakutata/com/i18n'
+ *
+ * //BuildEntrypoints({middlewares: [LanguageMiddleware], ...}) in place of I18nMiddleware
+ * export class LanguageMiddleware extends I18nMiddleware {
+ *     //The component registered as "lang"
+ *     @Inject('lang')
+ *     protected readonly i18n: I18n
+ *
+ *     //?locale=zh-CN
+ *     protected readonly queryParameter: string = 'locale'
+ *
+ *     protected readonly environmentVariable: string = 'SHOP_LANG'
+ *
+ *     //The language saved by the signed-in user first
+ *     protected requested(context: BaseContext): string[] {
+ *         const saved: unknown = context.data.userLanguage
+ *         return [...(typeof saved === 'string' ? [saved] : []), ...super.requested(context)]
+ *     }
+ * }
+ * ```
+ */
+export declare class I18nMiddleware extends Middleware {
+    /**
+     * The {@link I18n} component giving the supported languages and the messages: the object registered as `i18n`.
+     */
+    protected readonly i18n: I18n;
+    /**
+     * The name of the query parameter giving the language of an HTTP request (of the HTTP channel, the HTTP service and
+     * JSON-RPC adapters) or a Socket.IO connection (`?lang=zh-CN`); a value which is not a language tag is ignored.
+     * @default 'lang'
+     */
+    protected readonly queryParameter: string;
+    /**
+     * The name of the cookie giving the language of an HTTP request (of the HTTP channel, the HTTP service and JSON-RPC
+     * adapters) or a Socket.IO connection; a value which is not a language tag is ignored.
+     * @default 'lang'
+     */
+    protected readonly cookie: string;
+    /**
+     * The name of an environment variable (`SHOP_LANG`) whose language is preferred to the ones of the environment, for
+     * the command line and the service transports reading the process's languages.
+     * @default none
+     */
+    protected readonly environmentVariable?: string;
+    /**
+     * Negotiate the request's language, set `context.locale`, create the request's {@link Translator}, then run the
+     * next middlewares and the action with the validations in that language, translating the exception they throw.
+     * @param invocation The action invocation: its context and its container.
+     * @param next Runs the rest of the chain.
+     * @returns The result of the rest of the chain; an exception it throws is rethrown, its message translated by
+     * {@link I18nMiddleware.translate}.
+     */
+    handle(invocation: ActionInvocation, next: Next): Promise<unknown>;
+    /**
+     * Translate an exception thrown by a request into the request's language. A lakutata `Exception` with an `errno`
+     * whose key `errors.<errno>` has a message (`errors.E_ORDER_NOT_FOUND`) gets that message as its `message` and
+     * `errMsg`, formatted with the parameters of its template (`{id}` for named ones, `{0}`, `{1}` for the ones given one
+     * by one); its `errno` and its other properties are kept. The other errors, the exceptions without such a message,
+     * and the ones whose message cannot be formatted (a process warning `I18nWarning` is then emitted) are returned
+     * unchanged.
+     * @param error The thrown value.
+     * @param translator The request's translator.
+     * @returns The same value, its message replaced when it is translated.
+     */
+    protected translate(error: unknown, translator: Translator): unknown;
+    /**
+     * Read the languages a request asks for, preferred first:
+     * - HTTP: the query parameter, the cookie, then `Accept-Language`;
+     * - Socket.IO: the query parameter, the cookie and `Accept-Language` of the connection's handshake;
+     * - the HTTP service adapter, and the JSON-RPC adapter over HTTP or WebSocket: the query parameter, the cookie and
+     *   `Accept-Language` of the HTTP request (for WebSocket, the request opening the connection);
+     * - the command line and the other service transports (Electron IPC, JSON-RPC over stdio): the environment variable
+     *   of `environmentVariable`, the environment (`LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`), then the process's
+     *   language;
+     * - the schedules and the other contexts: none (the default language is chosen).
+     * @param context The request's context.
+     * @returns The requested language tags, preferred first.
+     */
+    protected requested(context: BaseContext): string[];
+    /**
+     * Read the languages of an HTTP request: its query parameter, its cookie, then its `Accept-Language`.
+     * @param request The Node.js HTTP request.
+     * @returns The language tags, preferred first.
+     */
+    protected fromRequest(request: IncomingMessage): string[];
+    /**
+     * Read the languages of a query parameter, the cookie and `Accept-Language`, in that order; the query and cookie
+     * values which are not language tags are skipped.
+     * @param query The value of the query parameter; ignored unless it is a string.
+     * @param headers The request headers, by lower-case name; for a repeated header, its first value is read.
+     * @returns The language tags, preferred first.
+     */
+    protected fromHeaders(query: unknown, headers: Record<string, string | string[] | undefined>): string[];
+    /**
+     * Read the value of the language cookie (named by `cookie`) in a `Cookie` header, URI-decoded.
+     * @param header The value of the `Cookie` header.
+     * @returns The value of the first cookie of that name; `undefined` without it, or when it cannot be decoded.
+     */
+    protected cookieValue(header: string | undefined): string | undefined;
+}