@lakutata/i18n 3.0.0-beta.0

package/dist/cjs/i18n/I18n.d.ts

@@ -0,0 +1,313 @@
+import { Component, type ComponentOptionsBuilder } from '@lakutata/core';
+import type { I18nOptions } from './interfaces/I18nOptions.js';
+import { type NestedMessages } from './lib/Catalog.js';
+import { type FormatContext, type MessagePart } from './lib/MessageFormat.js';
+import type { ITranslator } from './interfaces/ITranslator.js';
+import type { MessageKey, MessageParams } from './types/I18nMessages.js';
+/**
+ * Build the component options of an {@link I18n} component, to register it in the `components` of an application.
+ * Name it `i18n`: the {@link I18nMiddleware} and {@link commanderTranslator} use the component of that name by
+ * default. The options are validated when the component is created, not here.
+ * @param options Where the messages come from (`directory`, `messages`), the default language, the fallbacks, the
+ * behavior on a missing message, the currency and time zone of the formatted arguments, the validation messages.
+ * Without options, the component has no messages and its default language is `en`.
+ * @returns The component options (`{class: I18n, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildI18nOptions, type I18n} from 'lakutata/com/i18n'
+ *
+ * Application
+ *     .alias({'@locales': '/srv/shop/locales'})
+ *     .run(() => ({
+ *         id: 'shop.app',
+ *         name: 'Shop',
+ *         components: {
+ *             i18n: buildI18nOptions({
+ *                 //locales/en.json, locales/zh-CN.json, or a directory per language
+ *                 directory: '@locales',
+ *                 defaultLocale: 'en',
+ *                 //A message missing in zh-TW is looked up in zh-CN, then zh, then en
+ *                 fallback: {'zh-TW': 'zh-CN'},
+ *                 currency: 'CNY',
+ *                 timeZone: 'Asia/Shanghai'
+ *             })
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const i18n: I18n = await app.getObject('i18n')
+ *         console.log(i18n.getLocales())
+ *     })
+ * ```
+ */
+export declare const buildI18nOptions: ComponentOptionsBuilder<I18nOptions>;
+/**
+ * The internationalization component: the application's messages in each language, by key, written in ICU
+ * MessageFormat (arguments, numbers, currencies, dates, plurals, selects), formatted in their language by the `Intl`
+ * of Node.js. Register it in the `components` of an application with {@link buildI18nOptions}, named `i18n`, and get
+ * it with `getObject()` or `@Inject('i18n')`. In a request, inject the {@link Translator} instead (the
+ * {@link I18nMiddleware} gives it the request's language); out of a request, call {@link I18n.t} with a language or
+ * use {@link I18n.translator}.
+ *
+ * When it is created, the component loads the messages of its `directory` option, then adds the ones of its `messages`
+ * option, and registers the validation messages of its languages. A message missing in a language is looked up in the
+ * languages it falls back to: its `fallback` languages, its less specific tags (`zh-Hant-TW`, `zh-Hant`, `zh`), then
+ * the default language (see {@link fallbackChain}). A message is always formatted in the language asked, even when it
+ * comes from a fallback. A key found nowhere throws {@link I18nMissingKeyException}, or gives the key itself with the
+ * `missing: 'key'` option (the default when `NODE_ENV` is `production`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildI18nOptions, type I18n} from 'lakutata/com/i18n'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'shop.app',
+ *         name: 'Shop',
+ *         components: {
+ *             i18n: buildI18nOptions({
+ *                 messages: {
+ *                     'en': {order: {count: '{count, plural, =0 {No orders} one {# order} other {# orders}}', total: 'Total: {price, number, currency}'}},
+ *                     'zh-CN': {order: {count: '{count, plural, =0 {暂无订单} other {# 个订单}}'}}
+ *                 },
+ *                 currency: 'CNY'
+ *             })
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const i18n: I18n = await app.getObject('i18n')
+ *         console.log(i18n.t('order.count', {count: 1200})) //1,200 orders
+ *         console.log(i18n.t('order.count', {count: 0}, 'zh-CN')) //暂无订单
+ *         //Missing in zh-CN: the English message, formatted in Chinese
+ *         console.log(i18n.t('order.total', {price: 9.5}, 'zh-CN')) //Total: ¥9.50
+ *         console.log(i18n.negotiate(['zh-TW', 'en'])) //zh-CN
+ *     })
+ * ```
+ */
+export declare class I18n extends Component {
+    #private;
+    /**
+     * The directories holding the messages, read when the component is created (see {@link I18nOptions.directory}):
+     * a path, an alias of the application (`@locales`), or several, the later ones replacing the same keys.
+     * @default none
+     */
+    protected readonly directory?: string | string[];
+    /**
+     * The languages {@link I18n.negotiate} chooses from, as language tags.
+     * @default the default language, then the languages of the messages in alphabetical order
+     */
+    protected readonly locales?: string[];
+    /**
+     * The default language: the last one a message is looked up in, the one of the calls without a language, and the
+     * one chosen when no requested language is supported.
+     * @default 'en'
+     */
+    protected readonly defaultLocale: string;
+    /**
+     * The languages a message missing in a language is looked up in next, by language (`{'zh-TW': 'zh-CN'}`).
+     * @default none
+     */
+    protected readonly fallback?: Record<string, string | string[]>;
+    /**
+     * The messages given in the code, by language tag, added after the ones of `directory` and replacing their keys.
+     * @default none
+     */
+    protected readonly messages?: Record<string, NestedMessages>;
+    /**
+     * What a missing message or argument does: `'throw'` throws; `'key'` gives the key, writes the argument as
+     * `{name}`, or formats a `{price, number, currency}` without a currency as a plain number, with a warning, once
+     * per message and key, argument or currency.
+     * @default 'throw', and 'key' when NODE_ENV is 'production'
+     */
+    protected readonly missing?: 'throw' | 'key';
+    /**
+     * The currency (ISO 4217) of the `{price, number, currency}` arguments whose style and arguments give none.
+     * @default none
+     */
+    protected readonly currency?: string;
+    /**
+     * The time zone (IANA) of the formatted dates and times.
+     * @default the process's time zone
+     */
+    protected readonly timeZone?: string;
+    /**
+     * Whether the built-in validation error messages of the languages are registered.
+     * @default true
+     */
+    protected readonly validationMessages: boolean;
+    /**
+     * Load the messages (the directories, then the `messages` option), compute the supported languages and register
+     * the validation messages; called when the component is created.
+     * @throws {I18nCatalogException} When a directory, a file, a key or a language tag of the options is invalid.
+     */
+    protected init(): Promise<void>;
+    /**
+     * Give the supported languages without the `locales` option: the default language, then the languages having
+     * messages, in alphabetical order.
+     * @returns The canonical tags.
+     */
+    protected discovered(): string[];
+    /**
+     * Register the validation error messages of languages, so that the validations run in that language give them. A
+     * language's messages are layered from the end of its fallback chain to itself: for each language of the chain,
+     * its built-in messages (unless `validationMessages` is `false`), then the application's `validation.<code>`
+     * messages (`validation.any.required`), the later ones replacing the earlier ones. Called by `init()` for all the
+     * languages, and by {@link I18n.addMessages} for the languages its messages change.
+     * @param locales The canonical tags of the languages to register: by default, each supported language and each
+     * language having messages.
+     * @throws {SchemaDefinitionException} When a `validation.*` message is not a valid template.
+     */
+    protected registerValidationMessages(locales?: Iterable<string>): Promise<void>;
+    /**
+     * Normalize a language tag given in the configuration.
+     * @param tag The language tag.
+     * @param option The name of the option giving it, for the error message.
+     * @returns The canonical tag.
+     * @throws {I18nCatalogException} When the tag is not a language tag.
+     */
+    protected locale(tag: string, option: string): string;
+    /**
+     * Resolve a directory of the configuration to an absolute path: an alias (`@locales/en`) by the application
+     * holding the component, any other path from the working directory.
+     * @param directory The path or the alias.
+     * @returns The absolute path.
+     * @throws {I18nCatalogException} When an alias is given and no enclosing module resolves aliases.
+     */
+    protected resolvePath(directory: string): string;
+    /**
+     * Tell what a missing message or argument does: the `missing` option, else `'key'` when `NODE_ENV` is
+     * `production` and `'throw'` otherwise (read at each call).
+     * @returns `'throw'` or `'key'`.
+     */
+    protected missingMode(): 'throw' | 'key';
+    /**
+     * Emit a process warning of type `I18nWarning`, once per distinct text for the component's lifetime.
+     * @param warning The text of the warning.
+     */
+    protected warn(warning: string): void;
+    /**
+     * Give the formatting settings of a language: the language, the configured currency and time zone, and what a
+     * missing argument or currency does (thrown, or kept with a warning emitted once by {@link I18n.warn}).
+     * @param locale The canonical language tag the message is formatted in.
+     * @returns The formatting settings.
+     */
+    protected context(locale: string): FormatContext;
+    /**
+     * Give the supported languages: the `locales` option, or the default language then the languages having messages
+     * (the ones added by {@link I18n.addMessages} included), in alphabetical order.
+     * @returns A copy of the canonical tags.
+     */
+    getLocales(): string[];
+    /**
+     * Give the default language.
+     * @returns The canonical tag of the `defaultLocale` option (`en` by default).
+     */
+    getDefaultLocale(): string;
+    /**
+     * Give the time zone the dates and the times are formatted in.
+     * @returns The `timeZone` option; `undefined` when it is not set (the process's time zone is then used).
+     */
+    getTimeZone(): string | undefined;
+    /**
+     * List the keys a language has messages for: its own keys, not the ones of the languages it falls back to.
+     * @param locale The language tag (normalized; `zh_CN` is `zh-CN`).
+     * @returns The full keys (`order.count`), in their loading order; empty for a language without messages.
+     */
+    getKeys(locale: string): string[];
+    /**
+     * Add messages to a language at run time, replacing the messages of the same keys; {@link I18n.t} gives them as
+     * soon as it returns. As for the messages loaded at the creation, a new language is added to the supported
+     * languages ({@link I18n.getLocales}, {@link I18n.negotiate}) unless the `locales` option lists them, and the
+     * validation messages of the new language (its built-in ones) and of the `validation.*` messages added are
+     * registered, for the language and the languages falling back to it.
+     * @param locale The language tag (normalized).
+     * @param messages The messages, nested by the parts of their keys (`{order: {count: '...'}}`).
+     * @returns A promise resolved once the validation messages are registered (the built-in ones of a language are
+     * loaded on demand); it rejects with a `SchemaDefinitionException` when a `validation.*` message is not a valid
+     * template.
+     * @throws {I18nCatalogException} When the tag is not a language tag, or a key or a value is invalid: thrown by the
+     * call, nothing added.
+     * @example
+     * ```typescript
+     * import {type I18n} from 'lakutata/com/i18n'
+     *
+     * declare const i18n: I18n
+     *
+     * await i18n.addMessages('fr', {order: {created: 'Commande créée pour {customer}'}, validation: {any: {required: '{{#label}} est obligatoire'}}})
+     * console.log(i18n.negotiate(['fr-CA'])) //fr
+     * console.log(i18n.t('order.created', {customer: 'Ada'}, 'fr')) //Commande créée pour Ada
+     * ```
+     */
+    addMessages(locale: string, messages: NestedMessages): Promise<void>;
+    /**
+     * Merge messages into the catalog of a language, its cached parsed messages dropped.
+     * @param locale The language tag.
+     * @param messages The nested messages.
+     * @returns The messages merged, by full key.
+     * @throws {I18nCatalogException} When the tag is not a language tag, or a key or a value is invalid.
+     */
+    protected merge(locale: string, messages: NestedMessages): Map<string, string>;
+    /**
+     * Choose the supported language for the requested ones (see {@link negotiateLocale}): for each requested language
+     * in turn, the same tag, then its language alone (`en-GB` gives `en`), then another tag of its language (`pt-PT`
+     * gives `pt-BR`).
+     * @param requested The requested language tags, preferred first; the invalid ones are skipped.
+     * @returns A supported language, or the default language when none matches.
+     */
+    negotiate(requested: string[]): string;
+    /**
+     * Find the message of a key in a language or the languages it falls back to, parsed once and cached.
+     * @param key The key of the message.
+     * @param locale The canonical language tag.
+     * @returns The parsed message and the language it was found in; `undefined` when no language of the chain has it.
+     * @throws {I18nMessageSyntaxException} When the message found is not valid ICU MessageFormat.
+     */
+    protected message(key: string, locale: string): {
+        parts: MessagePart[];
+        locale: string;
+    } | undefined;
+    /**
+     * Tell whether a key has a message in a language or in the languages it falls back to.
+     * @param key The key of the message.
+     * @param locale The language tag: the default language by default, and when it is not a language tag.
+     * @returns `true` when {@link I18n.t} finds a message for the key in that language.
+     */
+    has(key: string, locale?: string): boolean;
+    /**
+     * Give the message of a key in a language, formatted with its arguments. The language is not negotiated: the
+     * message is looked up in the language given, then in the languages it falls back to (see {@link I18n}), and is
+     * formatted in the language given (its numbers, dates and plural rules) even when it comes from a fallback.
+     * @param key The key of the message (`order.count`).
+     * @param params The arguments of the message, by their names: the numbers and the bigints are formatted in the
+     * language, the `Date` objects as dates. A `currency` argument gives the currency of `{price, number, currency}`.
+     * @param locale The language tag: the default language by default, and when it is not a language tag.
+     * @returns The formatted message. With `missing: 'key'`, the key itself when no message has it, `{name}` in place
+     * of a missing argument, and a plain number for a currency argument without a currency, each with a warning
+     * emitted once (per key, or per message and argument).
+     * @throws {I18nMissingKeyException} When no message has the key and the `missing` mode is `'throw'`.
+     * @throws {I18nMissingParameterException} When an argument is missing, or a currency argument has no currency, and
+     * the `missing` mode is `'throw'`.
+     * @throws {I18nMessageSyntaxException} When the message is not valid ICU MessageFormat.
+     */
+    t<K extends MessageKey>(key: K, params?: MessageParams<K>, locale?: string): string;
+    /**
+     * Format an ICU MessageFormat message which is not in the catalogs (parsed at each call).
+     * @param message The message (`Hello, {name}`).
+     * @param params The arguments of the message, by their names.
+     * @param locale The language tag it is formatted in: the default language by default, and when it is not a
+     * language tag.
+     * @returns The formatted message. With `missing: 'key'`, `{name}` in place of a missing argument and a plain
+     * number for a currency argument without a currency, each with a warning emitted once per message and argument.
+     * @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` mode is `'throw'`.
+     */
+    format(message: string, params?: Record<string, unknown>, locale?: string): string;
+    /**
+     * Create a translator of a language, which gives its messages without the language at each call. The language is
+     * not negotiated: it is used as given (its messages falling back as in {@link I18n.t}).
+     * @param locale The language tag (normalized): the default language when it is not a language tag.
+     * @returns The translator, a {@link LocaleTranslator}.
+     */
+    translator(locale: string): ITranslator;
+}