@lakutata/i18n 3.0.0-beta.0

package/dist/cjs/i18n/lib/MessageFormat.js

@@ -0,0 +1,372 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMessage = parseMessage;
+exports.messageArguments = messageArguments;
+exports.formatMessage = formatMessage;
+const I18nMessageSyntaxException_js_1 = require("../exceptions/I18nMessageSyntaxException.js");
+const I18nMissingParameterException_js_1 = require("../exceptions/I18nMissingParameterException.js");
+const NUMBER_STYLES = /^(integer|percent|currency|currency\/[A-Z]{3})$/;
+const DATE_STYLES = new Set(['short', 'medium', 'long', 'full']);
+/**
+ * The parser of the messages of ICU MessageFormat: the texts (the apostrophe quoting of ICU), the arguments, the
+ * number, date and time arguments, the plural, selectordinal and select choices
+ */
+class MessageParser {
+    constructor(message, source) {
+        this.message = message;
+        this.source = source;
+        this.offset = 0;
+    }
+    error(message, offset = this.offset) {
+        throw new I18nMessageSyntaxException_js_1.I18nMessageSyntaxException(`${this.source}: ${message} at ${offset + 1}: ${this.message}`);
+    }
+    parse() {
+        const parts = this.parts(false, false);
+        if (this.offset < this.message.length)
+            this.error('unexpected "}"');
+        return parts;
+    }
+    spaces() {
+        while (/\s/.test(this.message[this.offset] ?? ''))
+            this.offset++;
+    }
+    /**
+     * The parts of a message, until its end or the closing brace of the option it is in
+     * @param nested whether the message is the one of an option
+     * @param inPlural whether # is the number of a plural
+     */
+    parts(nested, inPlural) {
+        const parts = [];
+        let text = '';
+        const flush = () => {
+            if (text)
+                parts.push(text);
+            text = '';
+        };
+        while (this.offset < this.message.length) {
+            const char = this.message[this.offset];
+            if (char === '{') {
+                flush();
+                parts.push(this.argument(inPlural));
+            }
+            else if (char === '}') {
+                if (!nested)
+                    break;
+                flush();
+                return parts;
+            }
+            else if (char === '#' && inPlural) {
+                flush();
+                parts.push({ type: 'pound' });
+                this.offset++;
+            }
+            else if (char === '\'') {
+                text += this.apostrophe(inPlural);
+            }
+            else {
+                text += char;
+                this.offset++;
+            }
+        }
+        if (nested)
+            this.error('unterminated option, expected "}"');
+        flush();
+        return parts;
+    }
+    /**
+     * An apostrophe: '' is one apostrophe, '{…}' quotes the syntax characters ({, }, # in a plural), any other one is
+     * itself
+     * @param inPlural
+     */
+    apostrophe(inPlural) {
+        const next = this.message[this.offset + 1];
+        if (next === '\'') {
+            this.offset += 2;
+            return '\'';
+        }
+        if (next !== '{' && next !== '}' && !(next === '#' && inPlural)) {
+            this.offset++;
+            return '\'';
+        }
+        //Quoted until the next single apostrophe (or the end of the message)
+        this.offset++;
+        let quoted = '';
+        while (this.offset < this.message.length) {
+            const char = this.message[this.offset];
+            if (char === '\'') {
+                if (this.message[this.offset + 1] === '\'') {
+                    quoted += '\'';
+                    this.offset += 2;
+                    continue;
+                }
+                this.offset++;
+                return quoted;
+            }
+            quoted += char;
+            this.offset++;
+        }
+        return quoted;
+    }
+    name() {
+        const matched = /^[^\s{}#,'=]+/.exec(this.message.slice(this.offset));
+        if (!matched)
+            this.error('expected the name of an argument');
+        this.offset += matched[0].length;
+        return matched[0];
+    }
+    expect(char) {
+        this.spaces();
+        if (this.message[this.offset] !== char)
+            this.error(`expected "${char}"`);
+        this.offset++;
+    }
+    /**
+     * An argument: {name}, {name, type}, {name, type, style}, {name, plural|selectordinal|select, options}
+     * @param inPlural
+     */
+    argument(inPlural) {
+        const start = this.offset;
+        this.offset++;
+        this.spaces();
+        const name = this.name();
+        this.spaces();
+        if (this.offset >= this.message.length)
+            this.error('unterminated argument', start);
+        if (this.message[this.offset] === '}') {
+            this.offset++;
+            return { type: 'argument', name: name };
+        }
+        this.expect(',');
+        this.spaces();
+        const typeStart = this.offset;
+        const type = this.name();
+        this.spaces();
+        switch (type) {
+            case 'number':
+            case 'date':
+            case 'time': {
+                if (this.message[this.offset] === '}') {
+                    this.offset++;
+                    return { type: type, name: name };
+                }
+                this.expect(',');
+                const styleStart = this.offset;
+                const close = this.message.indexOf('}', this.offset);
+                if (close < 0)
+                    this.error('unterminated argument', start);
+                const style = this.message.slice(this.offset, close).trim();
+                if (type === 'number' ? !NUMBER_STYLES.test(style) : !DATE_STYLES.has(style)) {
+                    this.error(`unknown ${type} style "${style}" (${type === 'number' ? 'integer, percent, currency, currency/XXX' : 'short, medium, long, full'})`, styleStart);
+                }
+                this.offset = close + 1;
+                return { type: type, name: name, style: style };
+            }
+            case 'plural':
+            case 'selectordinal': {
+                this.expect(',');
+                this.spaces();
+                let offset = 0;
+                const matched = /^offset:\s*(\d+)/.exec(this.message.slice(this.offset));
+                if (matched) {
+                    offset = Number(matched[1]);
+                    this.offset += matched[0].length;
+                }
+                return { type: type, name: name, offset: offset, options: this.options(true, start) };
+            }
+            case 'select': {
+                this.expect(',');
+                return { type: type, name: name, options: this.options(inPlural, start) };
+            }
+            default:
+                this.error(`unknown argument type "${type}" (number, date, time, plural, selectordinal, select)`, typeStart);
+        }
+    }
+    /**
+     * The options of a choice, until its closing brace: selector {message}, the "other" one required
+     * @param inPlural
+     * @param start
+     */
+    options(inPlural, start) {
+        const options = {};
+        for (;;) {
+            this.spaces();
+            if (this.offset >= this.message.length)
+                this.error('unterminated argument', start);
+            if (this.message[this.offset] === '}') {
+                this.offset++;
+                break;
+            }
+            const selectorStart = this.offset;
+            const matched = /^=?[^\s{}]+/.exec(this.message.slice(this.offset));
+            if (!matched)
+                this.error('expected a selector');
+            this.offset += matched[0].length;
+            if (matched[0] in options)
+                this.error(`selector "${matched[0]}" repeated`, selectorStart);
+            this.expect('{');
+            options[matched[0]] = this.parts(true, inPlural);
+            this.offset++;
+        }
+        if (!('other' in options))
+            this.error('the "other" option is required', start);
+        return options;
+    }
+}
+/**
+ * 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
+ * ```
+ */
+function parseMessage(message, source = 'message') {
+    return new MessageParser(message, source).parse();
+}
+/**
+ * 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']]
+ * ```
+ */
+function messageArguments(parts) {
+    const names = new Map();
+    const visit = (items) => {
+        for (const part of items) {
+            if (typeof part === 'string' || part.type === 'pound')
+                continue;
+            if (!names.has(part.name))
+                names.set(part.name, part.type);
+            if ('options' in part)
+                Object.values(part.options).forEach(visit);
+        }
+    };
+    visit(parts);
+    return names;
+}
+/**
+ * The formatters of Intl, created once by their locale and options
+ */
+const FORMATTERS = new Map();
+function cachedFormatter(kind, locale, options) {
+    const key = `${kind.name}|${locale}|${JSON.stringify(options)}`;
+    let formatter = FORMATTERS.get(key);
+    if (!formatter) {
+        formatter = new kind(locale, options);
+        FORMATTERS.set(key, formatter);
+    }
+    return formatter;
+}
+/**
+ * A date of a value: a Date, a timestamp, a date string, or an object giving one (lakutata Time: valueOf)
+ * @param value
+ */
+function dateOf(value) {
+    if (value instanceof Date)
+        return value;
+    if (value !== null && typeof value === 'object' && typeof value.toDate === 'function')
+        return value.toDate();
+    return new Date(value);
+}
+/**
+ * Format a parsed message
+ * @param parts
+ * @param params
+ * @param context
+ * @param source where the message is (its key), for the errors
+ */
+function formatMessage(parts, params, context, source = 'message') {
+    const format = (items, pound) => {
+        let text = '';
+        for (const part of items) {
+            if (typeof part === 'string') {
+                text += part;
+                continue;
+            }
+            if (part.type === 'pound') {
+                text += cachedFormatter(Intl.NumberFormat, context.locale, {}).format(pound ?? 0);
+                continue;
+            }
+            const value = params[part.name];
+            if (value === undefined) {
+                const missing = `${source}: the argument "${part.name}" is missing`;
+                if (context.missing === 'throw')
+                    throw new I18nMissingParameterException_js_1.I18nMissingParameterException(missing);
+                context.warn?.(missing);
+                text += `{${part.name}}`;
+                continue;
+            }
+            switch (part.type) {
+                case 'argument':
+                    text += typeof value === 'number' || typeof value === 'bigint'
+                        ? cachedFormatter(Intl.NumberFormat, context.locale, {}).format(value)
+                        : value instanceof Date ? cachedFormatter(Intl.DateTimeFormat, context.locale, { timeZone: context.timeZone }).format(value) : String(value);
+                    break;
+                case 'number':
+                    text += cachedFormatter(Intl.NumberFormat, context.locale, numberOptions(part.style, params, context, source)).format(value);
+                    break;
+                case 'date':
+                case 'time':
+                    text += cachedFormatter(Intl.DateTimeFormat, context.locale, { [part.type === 'date' ? 'dateStyle' : 'timeStyle']: part.style ?? 'medium', timeZone: context.timeZone }).format(dateOf(value));
+                    break;
+                case 'plural':
+                case 'selectordinal': {
+                    const count = Number(value);
+                    const exact = part.options[`=${count}`];
+                    const rule = cachedFormatter(Intl.PluralRules, context.locale, { type: part.type === 'plural' ? 'cardinal' : 'ordinal' }).select(count - part.offset);
+                    text += format(exact ?? part.options[rule] ?? part.options.other, count - part.offset);
+                    break;
+                }
+                case 'select':
+                    text += format(part.options[String(value)] ?? part.options.other, pound);
+                    break;
+            }
+        }
+        return text;
+    };
+    return format(parts);
+}
+/**
+ * The options of Intl.NumberFormat of a style of a number argument
+ * @param style
+ * @param params
+ * @param context
+ * @param source
+ */
+function numberOptions(style, params, context, source) {
+    if (style === 'integer')
+        return { maximumFractionDigits: 0 };
+    if (style === 'percent')
+        return { style: 'percent' };
+    if (style?.startsWith('currency')) {
+        //The currency of the style, of the parameters, of the configuration
+        const currency = style.split('/')[1] ?? params.currency ?? context.currency;
+        if (typeof currency === 'string')
+            return { style: 'currency', currency: currency };
+        const missing = `${source}: the currency is missing (currency/XXX, the "currency" argument, or the currency of the configuration)`;
+        if (context.missing === 'throw')
+            throw new I18nMissingParameterException_js_1.I18nMissingParameterException(missing);
+        //Kept: the number without currency
+        context.warn?.(missing);
+    }
+    return {};
+}

package/dist/cjs/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/cjs/i18n/middleware/CommanderTranslator.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commanderTranslator = commanderTranslator;
+const Locale_js_1 = require("../lib/Locale.js");
+/**
+ * The English text of a text, its arguments filled
+ * @param text
+ */
+function english(text) {
+    return text.text.replace(/\{(\w+)\}/g, (all, name) => text.params?.[name] ?? all);
+}
+/**
+ * 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']
+ * }))
+ * ```
+ */
+function commanderTranslator(options = {}) {
+    const prefix = options.prefix ?? 'cli';
+    return async (module) => {
+        const i18n = await module.getObject(options.component ?? 'i18n');
+        const translator = i18n.translator(i18n.negotiate((0, Locale_js_1.processLocales)(options.environment)));
+        return (text) => {
+            const key = prefix ? `${prefix}.${text.key}` : text.key;
+            return translator.has(key) ? translator.t(key, text.params) : english(text);
+        };
+    };
+}

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