@lakutata/i18n 3.0.0-beta.0

package/dist/cjs/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/cjs/i18n/lib/LocaleTranslator.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocaleTranslator = void 0;
+/**
+ * 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
+ *     })
+ * ```
+ */
+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);
+    }
+}
+exports.LocaleTranslator = LocaleTranslator;

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