@lakutata/i18n 3.0.0-beta.0

package/dist/cjs/i18n/middleware/I18nMiddleware.js

@@ -0,0 +1,210 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nMiddleware = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const entrypoint_1 = require("@lakutata/entrypoint");
+const Translator_js_1 = require("../Translator.js");
+const Locale_js_1 = require("../lib/Locale.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)]
+ *     }
+ * }
+ * ```
+ */
+class I18nMiddleware extends entrypoint_1.Middleware {
+    constructor() {
+        super(...arguments);
+        /**
+         * 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'
+         */
+        this.queryParameter = 'lang';
+        /**
+         * 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'
+         */
+        this.cookie = 'lang';
+    }
+    /**
+     * 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}.
+     */
+    async handle(invocation, next) {
+        const context = invocation.context;
+        const locale = this.i18n.negotiate(this.requested(context));
+        context.locale = locale;
+        //The translator of the request, shared by its objects
+        const translator = await invocation.container.getShared(Translator_js_1.Translator, { locale: locale, i18n: this.i18n });
+        //Its validations in its language
+        return await (0, core_1.runInValidationLanguage)(locale, async () => {
+            try {
+                return await next();
+            }
+            catch (error) {
+                throw this.translate(error, translator);
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    translate(error, translator) {
+        if (!(error instanceof core_1.Exception) || error.errno === undefined || error.errno === null)
+            return error;
+        const key = `errors.${error.errno}`;
+        if (!translator.has(key))
+            return error;
+        const params = (0, core_1.exceptionParams)(error);
+        let message;
+        try {
+            message = translator.t(key, Array.isArray(params) ? Object.fromEntries(params.map((value, index) => [String(index), value])) : params ?? {});
+        }
+        catch (failure) {
+            process.emitWarning(`The message ${key} of ${error.name} cannot be formatted: ${failure.message}`, 'I18nWarning');
+            return error;
+        }
+        error.message = message;
+        Reflect.set(error, 'errMsg', message);
+        return error;
+    }
+    /**
+     * 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.
+     */
+    requested(context) {
+        if (context.type === entrypoint_1.ContextType.HTTP)
+            return this.fromRequest(context.request);
+        if (context.type === entrypoint_1.ContextType.SERVICE) {
+            const handshake = context.socket?.handshake;
+            if (handshake)
+                return this.fromHeaders(handshake.query?.[this.queryParameter], handshake.headers ?? {});
+            //The HTTP service adapter, JSON-RPC over HTTP, and over WebSocket (the request upgraded)
+            const request = (0, entrypoint_1.httpRequestOfContext)(context);
+            if (request)
+                return this.fromRequest(request);
+        }
+        if (context.type === entrypoint_1.ContextType.CLI || context.type === entrypoint_1.ContextType.SERVICE) {
+            return (0, Locale_js_1.processLocales)(this.environmentVariable);
+        }
+        return [];
+    }
+    /**
+     * 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.
+     */
+    fromRequest(request) {
+        return this.fromHeaders(new URL(request.url ?? '/', 'http://localhost').searchParams.get(this.queryParameter), request.headers);
+    }
+    /**
+     * 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.
+     */
+    fromHeaders(query, headers) {
+        const single = (value) => Array.isArray(value) ? value[0] : value;
+        const requested = [];
+        if (typeof query === 'string' && (0, Locale_js_1.normalizeLocale)(query))
+            requested.push(query);
+        const cookie = this.cookieValue(single(headers.cookie));
+        if (cookie && (0, Locale_js_1.normalizeLocale)(cookie))
+            requested.push(cookie);
+        return [...requested, ...(0, Locale_js_1.parseAcceptLanguage)(single(headers['accept-language']))];
+    }
+    /**
+     * 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.
+     */
+    cookieValue(header) {
+        for (const part of header?.split(';') ?? []) {
+            const separator = part.indexOf('=');
+            if (separator < 0 || part.slice(0, separator).trim() !== this.cookie)
+                continue;
+            try {
+                return decodeURIComponent(part.slice(separator + 1).trim());
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+}
+exports.I18nMiddleware = I18nMiddleware;
+__decorate([
+    (0, di_1.Inject)('i18n'),
+    __metadata("design:type", Function)
+], I18nMiddleware.prototype, "i18n", void 0);

package/dist/cjs/i18n/types/I18nMessages.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The application's message keys and their arguments, declared by the application to type-check {@link I18n.t} and
+ * the translators: a wrong key or a missing argument is then a compilation error. `lakutata i18n types` (or
+ * {@link generateMessageTypes}) generates the declaration from the messages of the default language, or it is written
+ * by hand, in the module the application imports the i18n from:
+ *
+ *     declare module 'lakutata/com/i18n' {
+ *         interface I18nMessages {
+ *             'order.count': { count: number }
+ *         }
+ *     }
+ *
+ * Empty by default: any key and any arguments are then accepted.
+ */
+export interface I18nMessages {
+}
+/**
+ * A message key: one of the keys declared in {@link I18nMessages}, any string when none is declared.
+ */
+export type MessageKey = keyof I18nMessages extends never ? string : Extract<keyof I18nMessages, string>;
+/**
+ * The arguments of the message of a key: the ones declared in {@link I18nMessages}, any record for a key not declared.
+ */
+export type MessageParams<K extends string> = K extends keyof I18nMessages ? I18nMessages[K] : Record<string, unknown>;

package/dist/cjs/i18n/types/I18nMessages.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/exports/I18n.js

@@ -0,0 +1,14 @@
+export * from '../i18n/I18n.js';
+export * from '../i18n/Translator.js';
+export { LocaleTranslator } from '../i18n/lib/LocaleTranslator.js';
+export * from '../i18n/interfaces/I18nOptions.js';
+export * from '../i18n/interfaces/ITranslator.js';
+export * from '../i18n/types/I18nMessages.js';
+export { checkCatalogs, generateMessageTypes, loadCatalogs } from '../i18n/lib/CatalogTools.js';
+export { environmentLocales, fallbackChain, negotiateLocale, normalizeLocale, parseAcceptLanguage } from '../i18n/lib/Locale.js';
+export { messageArguments, parseMessage } from '../i18n/lib/MessageFormat.js';
+export * from '../i18n/exceptions/I18nCatalogException.js';
+export * from '../i18n/exceptions/I18nMessageSyntaxException.js';
+export * from '../i18n/exceptions/I18nMissingKeyException.js';
+export * from '../i18n/exceptions/I18nMissingParameterException.js';
+export * from '../i18n/exceptions/I18nTranslatorException.js';

package/dist/esm/exports/I18nMiddleware.js

@@ -0,0 +1,2 @@
+export * from '../i18n/middleware/I18nMiddleware.js';
+export * from '../i18n/middleware/CommanderTranslator.js';