@lakutata/i18n 3.0.0 → 3.1.0

package/README.md

@@ -1,11 +1,13 @@
 # @lakutata/i18n
 
-The internationalization component of the lakutata framework: the application's messages in each language, by key,
-written in [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) and formatted in their
-language by the `Intl` of Node.js (numbers, currencies, dates, plurals, selects), with no third-party library. It also
-provides the middleware choosing the language of each request (its `Translator`, its validation errors and its
-exceptions in that language), the translation of the Commander CLI help, and the tools checking the translations. The
-umbrella package `lakutata` re-exports it as `lakutata/com/i18n`.
+English | [中文](README.zh-CN.md)
+
+The internationalization component of the lakutata framework. It holds the application's messages for each language,
+by key, written in [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) and
+formatted for their language by the built-in `Intl` of Node.js (numbers, currencies, dates, plurals, selects), with no
+third-party library. It also provides the middleware that chooses the language of each request (so that the request's
+`Translator`, validation errors and exceptions are in that language), the translation of the Commander CLI help, and
+tools that check the translations. The umbrella package `lakutata` re-exports it as `lakutata/com/i18n`.
 
 ## Installation
 
@@ -13,25 +15,25 @@ umbrella package `lakutata` re-exports it as `lakutata/com/i18n`.
 npm install lakutata
 ```
 
-The component needs nothing more. `I18nMiddleware` and `commanderTranslator` use the entrypoint component
-(`lakutata/com/entrypoint`, the optional peer dependency `@lakutata/entrypoint`), included in `lakutata`.
+The component needs nothing else. `I18nMiddleware` and `commanderTranslator` use the entrypoint component
+(`lakutata/com/entrypoint`, the optional peer dependency `@lakutata/entrypoint`), which `lakutata` includes.
 
 ## Usage
 
 ### The component and its messages
 
-Register the component with `buildI18nOptions()` in the `components` of the application, named `i18n` (the name the
-middleware and `commanderTranslator` use), and give it its messages:
+Register the component with `buildI18nOptions()` in the application's `components`, under the name `i18n` (the name
+the middleware and `commanderTranslator` use), and give it its messages:
 
-- `directory`: one or several directories (a path, or an alias of the application such as `@locales`) read when the
-  component is created. A language is a JSON file named by its tag (`en.json`, `zh-CN.json`), or a directory named by
-  its tag whose files and subdirectories prefix their keys (`zh-TW/order.json` gives `order.*`,
+- `directory`: one or more directories (a path, or an application alias such as `@locales`), read when the component
+  is created. A language is either a JSON file named after its tag (`en.json`, `zh-CN.json`), or a directory named
+  after its tag, whose files and subdirectories prefix their keys (`zh-TW/order.json` gives `order.*`,
   `zh-TW/admin/user.json` gives `admin.user.*`). Both layouts can be mixed.
-- `messages`: the messages by language in the code (object literals or imported JSON), bundled with it; added after
-  the directories, they replace the same keys.
+- `messages`: the messages by language, in the code (object literals or imported JSON), so they are bundled with it.
+  They are added after the directories and replace the same keys.
 
-The nesting of the JSON is the one of the keys: `{"order": {"count": "..."}}` holds the key `order.count`; a key part
-cannot contain `.`.
+The nesting of the JSON gives the keys: `{"order": {"count": "..."}}` holds the key `order.count`. No part of a key can
+contain `.`.
 
 ```typescript
 import {Application} from 'lakutata'
@@ -55,7 +57,7 @@ Application
                 fallback: {'zh-TW': 'zh-CN'},
                 //The currency of {price, number, currency} when the message and its arguments give none
                 currency: 'CNY',
-                //The time zone of the dates and the times (the process's one by default)
+                //The time zone of dates and times (the process's by default)
                 timeZone: 'Asia/Shanghai'
             })
         }
@@ -71,34 +73,34 @@ Application
 
 | Option | Default | Description |
 |---|---|---|
-| `directory` | none | The directories of the messages, aliases accepted; the later ones replace the same keys |
-| `messages` | none | The messages by language given in the code, added after the directories |
+| `directory` | none | The message directories (aliases accepted); later ones replace the same keys |
+| `messages` | none | The messages by language, given in the code and added after the directories |
 | `locales` | the default language, then the languages of the messages (alphabetical) | The supported languages, which `negotiate()` chooses from |
 | `defaultLocale` | `'en'` | The default language |
-| `fallback` | none | The languages a message missing in a language is looked up in next (`{'zh-TW': 'zh-CN'}`, or a list) |
-| `missing` | `'throw'`, `'key'` when `NODE_ENV=production` | `'throw'` throws on a missing message, argument or currency; `'key'` gives the key, writes a missing argument as `{name}` and a currency argument without a currency as a plain number, each with a warning `I18nWarning` emitted once (per key, or per message and argument) |
+| `fallback` | none | The languages to look in next when a language lacks a message (`{'zh-TW': 'zh-CN'}`, or a list) |
+| `missing` | `'throw'`, `'key'` when `NODE_ENV=production` | `'throw'` throws on a missing message, argument or currency; `'key'` returns the key, writes a missing argument as `{name}` and a currency argument without a currency as a plain number, emitting an `I18nWarning` once for each (per key and language, or per message and argument) |
 | `currency` | none | The ISO 4217 currency of `{price, number, currency}` when neither the style nor a `currency` argument gives one (without it, such a message throws, or gives a plain number with `missing: 'key'`) |
-| `timeZone` | the process's | The IANA time zone of the dates and the times |
+| `timeZone` | the process's | The IANA time zone of dates and times |
 | `validationMessages` | `true` | Whether the built-in validation messages of the languages are registered |
 
-**Fallbacks.** A message missing in a language is looked up in its `fallback` languages (and theirs), then in its less
-specific tags (`zh-Hant-TW`, `zh-Hant`, `zh`), then in the default language. It is always formatted in the language
-asked: an English message given to a German request writes `1.000`. A key found nowhere throws
-`I18nMissingKeyException`, or gives the key itself with `missing: 'key'`.
+**Fallbacks.** A message missing in a language is looked up in its `fallback` languages (and in theirs), then in its
+less specific tags (for `zh-Hant-TW`: `zh-Hant`, then `zh`), then in the default language. It is always formatted in the
+requested language: an English message used for a German request writes `1.000`. A key found nowhere throws
+`I18nMissingKeyException`, or returns the key itself with `missing: 'key'`.
 
-**Out of a request** (a schedule, a singleton component), the component gives `t(key, params, locale)`,
-`has(key, locale)`, `format(message, params, locale)`, and `translator(locale)`, a translator of one language. None of
+**Outside a request** (in a schedule or a singleton component), the component provides `t(key, params, locale)`,
+`has(key, locale)`, `format(message, params, locale)`, and `translator(locale)`, a translator for one language. None of
 them negotiates the language: an unsupported language is looked up as given, then falls back.
 
 **At run time**, `addMessages(locale, messages)` adds or replaces messages. A new language becomes supported
-(`getLocales()`, `negotiate()`) unless the `locales` option lists the languages, and its validation messages are
-registered as at the creation; the promise it returns resolves once they are (the messages themselves are given by
-`t()` as soon as it returns).
+(`getLocales()`, `negotiate()`) unless the `locales` option lists the languages; its validation messages are registered
+as at creation in any case. The promise that `addMessages()` returns resolves once they are; `t()` gives the new
+messages as soon as `addMessages()` returns.
 
 ### The translator of a request
 
-With `I18nMiddleware` in the `middlewares` of the entrypoint, each request has a language, and its objects (the
-controller, the `@Scoped` providers, the access control rules) inject the same `Translator` of that language:
+With `I18nMiddleware` in the entrypoint's `middlewares`, each request has a language, and its objects (the controller,
+the `@Scoped` providers, the access control rules) inject the same `Translator` for that language:
 
 ```typescript
 import {Application} from 'lakutata'
@@ -142,30 +144,30 @@ Application.run(() => ({
 }))
 ```
 
-A translator (`Translator`, and the `ITranslator` of `translator(locale)`) has `locale`, `t(key, params)`, `has(key)`,
-`format(message, params)`, `number(value, options)` (`Intl.NumberFormat`) and `date(value, options)`
-(`Intl.DateTimeFormat`, in the `timeZone` option). The `Translator` of a request without the middleware throws
+A translator (`Translator`, and the `ITranslator` returned by `translator(locale)`) has `locale`, `t(key, params)`,
+`has(key)`, `format(message, params)`, `number(value, options)` (`Intl.NumberFormat`) and `date(value, options)`
+(`Intl.DateTimeFormat`, in the `timeZone` option). Without the middleware, a request's `Translator` throws
 `I18nTranslatorException`.
 
 ### The language of each request
 
-The middleware reads the languages a request asks for, preferred first, then negotiates them with the supported
-languages (the default language when none matches) and sets `context.locale`:
+The middleware reads the languages a request asks for, preferred first, negotiates them with the supported languages
+(the default language when none matches) and sets `context.locale`:
 
 | Transport | Languages read, preferred first |
 |---|---|
 | HTTP (Express, Fastify) | The query parameter `?lang=`, the cookie `lang`, then `Accept-Language` (by quality) |
-| Socket.IO | The query parameter `lang`, the cookie `lang` and `Accept-Language` of the connection's handshake |
-| HTTP service adapter, JSON-RPC adapter (HTTP, WebSocket) | The query parameter `lang`, the cookie `lang` and `Accept-Language` of the HTTP request (for WebSocket, of the request opening the connection) |
+| Socket.IO | The query parameter `lang`, the cookie `lang` and `Accept-Language` of the connection handshake |
+| HTTP service adapter, JSON-RPC adapter (HTTP, WebSocket) | The query parameter `lang`, the cookie `lang` and `Accept-Language` of the HTTP request (for WebSocket, of the request that opened the connection) |
 | Command line, Electron IPC, JSON-RPC over stdio | The variable named by `environmentVariable` (none by default), `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`, then the process's language |
 | Schedules | None: the default language |
 
-A query or cookie value which is not a language tag is skipped. The negotiation tries 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`, in
-the order of the supported languages).
+A query or cookie value that is not a language tag is skipped. Negotiation tries each requested language in turn: the
+same tag, then its language alone (`en-GB` gives `en`), then another tag of the same language (`pt-PT` gives `pt-BR`,
+in the order of the supported languages).
 
-A subclass changes the component (`@Inject('...') protected readonly i18n`), the names `queryParameter` and `cookie`,
-`environmentVariable`, or the languages read (`requested(context)`):
+A subclass can change the component (`@Inject('...') protected readonly i18n`), the `queryParameter` and `cookie`
+names, `environmentVariable`, or the languages read (`requested(context)`):
 
 ```typescript
 import {type BaseContext} from 'lakutata/com/entrypoint'
@@ -188,20 +190,20 @@ export class LanguageMiddleware extends I18nMiddleware {
 
 | Syntax | Example |
 |---|---|
-| Argument | `Hello, {name}`: a number is formatted in the language, a `Date` as a date, the rest as a string |
+| Argument | `Hello, {name}`: a number is formatted for the language, a `Date` as a date, anything else as a string |
 | Number | `{n, number}`, `{n, number, integer}`, `{n, number, percent}` |
-| Currency | `{price, number, currency}` (the `currency` argument, else the `currency` option), `{price, number, currency/EUR}` |
+| Currency | `{price, number, currency}` (the `currency` argument, or else the `currency` option), `{price, number, currency/EUR}` |
 | Date, time | `{at, date, short}`, `{at, time, long}`; the styles `short`, `medium` (the default), `long`, `full`; a `Date`, a timestamp, a date string or an object with `toDate()` |
-| Plural | `{count, plural, =0 {none} one {# item} other {# items}}`: the `=n` options first, then the plural rules of the language; `#` is the number; `offset:1` supported |
+| Plural | `{count, plural, =0 {none} one {# item} other {# items}}`: the `=n` options first, then the plural rules of the language; `#` is the number; `offset:1` is supported |
 | Ordinal | `{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}` |
 | Select | `{role, select, admin {Administrator} other {User}}` |
 | Quoting | `''` writes an apostrophe; `'{literal}'` writes braces (`'#'` writes `#` in a plural) |
 
 `plural`, `selectordinal` and `select` need an `other` option. A message is parsed the first time it is used; a syntax
-error throws `I18nMessageSyntaxException` naming its language, key and position.
+error throws `I18nMessageSyntaxException`, which names its language, key and position.
 
-The application can declare its keys and their arguments, so that a wrong key or a missing argument fails the
-compilation (`lakutata i18n types` generates it from the default language; without it, any key is accepted):
+The application can declare its keys and their arguments, so that a wrong key or a missing argument fails compilation
+(`lakutata i18n types` generates the declaration from the default language; without it, any key is accepted):
 
 ```text
 //src/i18n.d.ts
@@ -217,11 +219,11 @@ declare module 'lakutata/com/i18n' {
 
 ### The validation messages and the exceptions
 
-With the middleware, the validation errors of a request (its input DTO, `@Accept`/`@Return`, the `DTO.validate` calls
-of its code) are in its language. The component registers, when it is created (and for a language added by
-`addMessages()`), the built-in validation messages of its languages (20 languages are built in: `en`, `zh-CN`,
-`zh-TW`, `ja`, `ko`, `fr`, `de`, `es`, `pt-BR`, `it`, `nl`, `pl`, `ru`, `uk`, `tr`, `vi`, `th`, `id`, `hi`, `ar`), layered with the application's messages under `validation`, by error
-code, in the syntax of the validation templates (not ICU):
+With the middleware, a request's validation errors (from its input DTO, `@Accept`/`@Return`, and the `DTO.validate`
+calls in its code) are in its language. When it is created (and for a language added by `addMessages()`), the component
+registers the built-in validation messages of its languages. 20 languages are built in: `en`, `zh-CN`, `zh-TW`, `ja`,
+`ko`, `fr`, `de`, `es`, `pt-BR`, `it`, `nl`, `pl`, `ru`, `uk`, `tr`, `vi`, `th`, `id`, `hi`, `ar`. The application's
+messages under `validation` are layered on top, by error code, in the syntax of the validation templates (not ICU):
 
 ```json
 {
@@ -232,12 +234,12 @@ code, in the syntax of the validation templates (not ICU):
 }
 ```
 
-A language's validation messages are those of the languages it falls back to, replaced by its own built-in ones, then
-by its own application messages. `validationMessages: false` registers the application's messages only.
+A language's validation messages are those of the languages it falls back to, replaced by its own built-in messages,
+then by its own application messages. `validationMessages: false` registers only the application's messages.
 
-An exception thrown by a request whose `errno` has a message `errors.<errno>` gets that message in the request's
-language, formatted with the parameters of its template (`{id}`, or `{0}`, `{1}` for the parameters given one by one);
-its `errno` is unchanged:
+When a request throws an exception whose `errno` has a message under `errors.<errno>`, the exception gets that message
+in the request's language, formatted with the parameters of its template (`{id}`, or `{0}`, `{1}` for parameters
+passed one by one); its `errno` stays unchanged:
 
 ```typescript
 import {Exception} from 'lakutata'
@@ -294,7 +296,7 @@ Application.run(() => ({
 ### Checking the translations
 
 `loadCatalogs`, `checkCatalogs` and `generateMessageTypes` are the functions behind `lakutata i18n check` and
-`lakutata i18n types`, for a script or the CI:
+`lakutata i18n types`, for use in a script or in CI:
 
 ```typescript
 import {checkCatalogs, loadCatalogs, type CatalogIssue, type Catalogs} from 'lakutata/com/i18n'
@@ -310,38 +312,39 @@ if (issues.some((issue: CatalogIssue): boolean => issue.level === 'error')) proc
 | Export | What it is |
 |---|---|
 | `I18n` | The component: `t`, `has`, `format`, `translator`, `negotiate`, `addMessages`, `getLocales`, `getDefaultLocale`, `getKeys`, `getTimeZone` |
-| `buildI18nOptions` | Builds the component options of `I18n` |
+| `buildI18nOptions` | Builds the component options for `I18n` |
 | `I18nOptions` | The options: `directory`, `messages`, `locales`, `defaultLocale`, `fallback`, `missing`, `currency`, `timeZone`, `validationMessages` |
-| `Translator` | The scoped provider injected in the objects of a request, in the request's language |
-| `ITranslator` | A translator of one language: `locale`, `t`, `has`, `format`, `number`, `date` |
-| `LocaleTranslator` | The `ITranslator` given by `I18n.translator()` |
-| `I18nMiddleware` | The entrypoint middleware choosing the language of each request (`lakutata/com/i18n`, `@lakutata/i18n/middleware`) |
+| `Translator` | The scoped provider injected into the objects of a request, in the request's language |
+| `ITranslator` | A translator for one language: `locale`, `t`, `has`, `format`, `number`, `date` |
+| `LocaleTranslator` | The `ITranslator` returned by `I18n.translator()` |
+| `I18nMiddleware` | The entrypoint middleware that chooses the language of each request (`lakutata/com/i18n`, `@lakutata/i18n/middleware`) |
 | `commanderTranslator`, `CommanderTranslatorOptions` | The translation of the Commander CLI help, and its options (`lakutata/com/i18n`, `@lakutata/i18n/middleware`) |
 | `I18nMessages`, `MessageKey`, `MessageParams` | The declaration of the application's keys and arguments, and the types derived from it |
-| `NestedMessages`, `Catalogs` | The messages of a language nested by key parts; the loaded messages by language and key |
+| `NestedMessages`, `Catalogs` | A language's messages, nested by key part; the loaded messages by language and key |
 | `loadCatalogs`, `checkCatalogs`, `CatalogIssue`, `generateMessageTypes` | Load the message directories, check the translations, generate the key types |
-| `normalizeLocale`, `parseAcceptLanguage`, `environmentLocales`, `negotiateLocale`, `fallbackChain` | The language tag helpers |
-| `parseMessage`, `messageArguments`, `MessagePart` | The ICU MessageFormat parser and the arguments of a message |
+| `normalizeLocale`, `parseAcceptLanguage`, `environmentLocales`, `negotiateLocale`, `fallbackChain` | Language tag helpers |
+| `parseMessage`, `messageArguments`, `MessagePart` | The ICU MessageFormat parser, and the arguments of a message |
 | `I18nCatalogException`, `I18nMessageSyntaxException`, `I18nMissingKeyException`, `I18nMissingParameterException`, `I18nTranslatorException` | The exceptions |
 
-All are exported by `lakutata/com/i18n`; `@lakutata/i18n` exports them except the middleware ones, exported by
-`@lakutata/i18n/middleware`. The typings document each declaration with examples.
+All are exported by `lakutata/com/i18n`; `@lakutata/i18n` exports all but the middleware ones, which
+`@lakutata/i18n/middleware` exports. The typings document each declaration, with examples.
 
 ## Errors
 
 | Exception | When |
 |---|---|
-| `I18nCatalogException` (`E_I18N_CATALOG`) | The component's creation, `addMessages()` or `loadCatalogs()`: a missing directory, invalid JSON, a file or directory name which is not a language tag, an invalid key or value, an option which is not a language tag, an alias without an application; `generateMessageTypes()`: the default language has no messages |
-| `I18nMessageSyntaxException` (`E_I18N_MESSAGE_SYNTAX`) | A message is not valid ICU MessageFormat, when it is first used (or parsed by `format()`, `parseMessage()`, `generateMessageTypes()`) |
+| `I18nCatalogException` (`E_I18N_CATALOG`) | Creating the component, `addMessages()` or `loadCatalogs()`: a missing directory, invalid JSON, a file or directory name that is not a language tag, an invalid key or value, an option that is not a language tag, an alias without an application; `generateMessageTypes()`: the default language has no messages |
+| `I18nMessageSyntaxException` (`E_I18N_MESSAGE_SYNTAX`) | A message is not valid ICU MessageFormat, when it is first used (or parsed by `format()`, `parseMessage()` or `generateMessageTypes()`) |
 | `I18nMissingKeyException` (`E_I18N_MISSING_KEY`) | `t()`: no message has the key, with `missing: 'throw'` |
 | `I18nMissingParameterException` (`E_I18N_MISSING_PARAMETER`) | `t()`, `format()`: an argument is missing, or a currency argument has no currency, with `missing: 'throw'` |
-| `I18nTranslatorException` (`E_I18N_TRANSLATOR`) | The `Translator` is used without the `I18nMiddleware`, or out of a request |
+| `I18nTranslatorException` (`E_I18N_TRANSLATOR`) | The `Translator` is used without the `I18nMiddleware`, or outside a request |
 | `InvalidValueException` (from `lakutata`) | The component's options are invalid, when it is created |
 
 ## See also
 
-- `doc/en/I18n.md` of the package `lakutata` (Chinese in `doc/zh`): the guide of the internationalization.
-- `@lakutata/entrypoint` (`lakutata/com/entrypoint`): the controllers, the middlewares and the adapters.
-- `@lakutata/core` (`lakutata`): the components, `Application`, the DTO validation and its languages
+- The guide on the website: [Internationalization (i18n)](https://lakutata.com/guide/I18n).
+- `doc/en/I18n.md` in the `lakutata` package (Chinese version in `doc/zh`): the internationalization guide.
+- `@lakutata/entrypoint` (`lakutata/com/entrypoint`): controllers, middlewares and adapters.
+- `@lakutata/core` (`lakutata`): components, `Application`, DTO validation and its languages
   (`loadValidationMessages`, `registerValidationMessages`, `runInValidationLanguage`).
 - `@lakutata/cli`: the `lakutata i18n check`, `lakutata i18n types` and `lakutata i18n add` commands.

package/README.zh-CN.md

@@ -0,0 +1,307 @@
+# @lakutata/i18n
+
+[English](README.md) | 中文
+
+lakutata 框架的国际化组件。它按键名保存应用在各种语言下的消息，消息使用 [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) 的语法，由 Node.js 内置的 `Intl` 按各自的语言格式化（数字、货币、日期、复数、选择），不依赖第三方库。它还提供为每个请求确定语言的中间件（这样请求的 `Translator`、校验错误和异常都使用这种语言）、Commander 命令行帮助的翻译，以及检查翻译的工具。`lakutata` 包把它重新导出为 `lakutata/com/i18n`。
+
+## 安装
+
+```shell
+npm install lakutata
+```
+
+组件不需要其他包。`I18nMiddleware` 和 `commanderTranslator` 用到入口组件（`lakutata/com/entrypoint`，即可选的 peer 依赖 `@lakutata/entrypoint`），`lakutata` 包已经包含了它。
+
+## 用法
+
+### 组件和消息
+
+用 `buildI18nOptions()` 把组件注册到应用的 `components` 中，名字为 `i18n`（中间件和 `commanderTranslator` 使用这个名字），并给出它的消息：
+
+- `directory`：一个或多个目录（路径，或者 `@locales` 这样的应用别名），在组件创建时读取。一种语言可以是一个以语言标签命名的 JSON 文件（`en.json`、`zh-CN.json`），也可以是一个以语言标签命名的目录，目录里的文件名和子目录名作为键名的前缀（`zh-TW/order.json` 对应 `order.*`，`zh-TW/admin/user.json` 对应 `admin.user.*`）。两种布局可以混用。
+- `messages`：在代码里按语言给出的消息（对象字面量或导入的 JSON），因此会和代码一起打包。它们在目录之后加入，会覆盖目录中同名的键。
+
+JSON 的嵌套就是键名的层级：`{"order": {"count": "..."}}` 包含键 `order.count`。键名的每一段都不能包含 `.`。
+
+```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({
+                directory: '@locales',
+                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 {# 个订单}}'}}
+                },
+                //默认语言：最后的回退语言，也是请求的语言都不支持时选用的语言
+                defaultLocale: 'en',
+                //zh-TW 缺少的消息依次到 zh-CN、zh、en 中查找
+                fallback: {'zh-TW': 'zh-CN'},
+                //消息和参数都没有给出货币时，{price, number, currency} 使用的货币
+                currency: 'CNY',
+                //日期和时间的时区（默认是进程的时区）
+                timeZone: 'Asia/Shanghai'
+            })
+        }
+    }))
+    .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')) //暂无订单
+        //zh-CN 中没有这条消息：使用英文消息，按中文格式化
+        console.log(i18n.t('order.total', {price: 9.5}, 'zh-CN')) //Total: ¥9.50
+    })
+```
+
+| 选项 | 默认值 | 说明 |
+|---|---|---|
+| `directory` | 无 | 消息所在的目录（支持别名）；后面的目录覆盖前面目录中同名的键 |
+| `messages` | 无 | 在代码里按语言给出的消息，在目录之后加入 |
+| `locales` | 默认语言，加上消息中出现的语言（按字母顺序） | 支持的语言，`negotiate()` 从中选择 |
+| `defaultLocale` | `'en'` | 默认语言 |
+| `fallback` | 无 | 某种语言缺少消息时，接着去哪些语言里找（`{'zh-TW': 'zh-CN'}`，或一个列表） |
+| `missing` | `'throw'`；`NODE_ENV=production` 时为 `'key'` | `'throw'`：缺少消息、参数或货币时抛出异常；`'key'`：返回键名，把缺少的参数写成 `{name}`，把没有货币的货币参数写成普通数字，每种情况只发出一次 `I18nWarning`（按键名和语言，或者按消息和参数计） |
+| `currency` | 无 | 样式和 `currency` 参数都没有给出货币时，`{price, number, currency}` 使用的 ISO 4217 货币（不设置时，这样的消息会抛出异常；`missing: 'key'` 时得到普通数字） |
+| `timeZone` | 进程的时区 | 日期和时间的 IANA 时区 |
+| `validationMessages` | `true` | 是否为各种语言注册内置的校验消息 |
+
+**回退。** 某种语言里缺少的消息，依次到它的 `fallback` 语言（以及这些语言的 `fallback` 语言）、范围更宽的标签（对 `zh-Hant-TW` 来说，先 `zh-Hant`，再 `zh`）和默认语言中查找。消息总是按请求的语言格式化：德语请求用到英文消息时，数字写成 `1.000`。哪里都找不到的键会抛出 `I18nMissingKeyException`；`missing: 'key'` 时返回键名本身。
+
+**在请求之外**（定时任务或单例组件中），使用组件的 `t(key, params, locale)`、`has(key, locale)`、`format(message, params, locale)`，以及得到某种语言翻译器的 `translator(locale)`。它们都不做语言协商：不支持的语言按原样查找，然后回退。
+
+**运行时**，`addMessages(locale, messages)` 添加或覆盖消息。新的语言会成为支持的语言（`getLocales()`、`negotiate()`），除非 `locales` 选项已经列出了支持的语言；无论如何，它的校验消息都会像创建时一样注册。`addMessages()` 返回的 Promise 在校验消息注册完成后才完成；而 `addMessages()` 一返回，`t()` 就能取得新消息。
+
+### 请求的翻译器
+
+把 `I18nMiddleware` 加到入口的 `middlewares` 中，每个请求就有了自己的语言；请求中的对象（控制器、`@Scoped` 的提供者、访问控制规则）注入的是同一个使用这种语言的 `Translator`：
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {CLIAction, GET} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+import {buildI18nOptions, I18nMiddleware, Translator} from 'lakutata/com/i18n'
+
+class OrderController extends Controller {
+    @Inject(Translator)
+    protected readonly translator: Translator
+
+    @GET('/orders/summary')
+    @CLIAction('order-summary')
+    public async summary(): Promise<string> {
+        const count: string = this.translator.t('order.count', {count: 3})
+        const total: string = this.translator.number(1234.5, {style: 'currency', currency: 'EUR'})
+        const today: string = this.translator.date(new Date(), {dateStyle: 'long'})
+        return `${this.translator.locale}: ${count}, ${total}, ${today}`
+    }
+}
+
+Application.run(() => ({
+    id: 'shop.app',
+    name: 'Shop',
+    components: {
+        i18n: buildI18nOptions({
+            messages: {
+                'en': {order: {count: '{count, plural, one {# order} other {# orders}}'}},
+                'zh-CN': {order: {count: '{count} 个订单'}}
+            }
+        }),
+        entrypoint: buildEntrypoints({
+            controllers: [OrderController],
+            middlewares: [I18nMiddleware],
+            http: expressHTTPEntrypoint({port: 3000})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+翻译器（`Translator`，以及 `translator(locale)` 返回的 `ITranslator`）有 `locale`、`t(key, params)`、`has(key)`、`format(message, params)`、`number(value, options)`（`Intl.NumberFormat`）和 `date(value, options)`（`Intl.DateTimeFormat`，使用 `timeZone` 选项的时区）。没有配置中间件时，请求的 `Translator` 会抛出 `I18nTranslatorException`。
+
+### 每个请求的语言
+
+中间件读取请求方希望使用的语言（优先的在前），和支持的语言协商（都不匹配时用默认语言），然后设置 `context.locale`：
+
+| 传输方式 | 读取的语言（优先的在前） |
+|---|---|
+| HTTP（Express、Fastify） | Query 参数 `?lang=`、Cookie `lang`，然后是 `Accept-Language`（按权重） |
+| Socket.IO | 连接握手时的 Query 参数 `lang`、Cookie `lang` 和 `Accept-Language` |
+| HTTP 服务适配器、JSON-RPC 适配器（HTTP、WebSocket） | HTTP 请求（WebSocket 为建立连接的请求）的 Query 参数 `lang`、Cookie `lang` 和 `Accept-Language` |
+| 命令行、Electron IPC、stdio 上的 JSON-RPC | `environmentVariable` 指定的环境变量（默认没有）、`LANGUAGE`、`LC_ALL`、`LC_MESSAGES`、`LANG`，最后是进程的语言 |
+| 定时任务 | 无：使用默认语言 |
+
+不是语言标签的 Query 参数或 Cookie 值会被跳过。协商时依次尝试请求的每一种语言：先找完全相同的标签，再找只有语言部分的标签（`en-GB` 得到 `en`），再找同一语言的其他标签（`pt-PT` 得到 `pt-BR`，按支持的语言的顺序）。
+
+子类可以换用别的组件（`@Inject('...') protected readonly i18n`），修改 `queryParameter` 和 `cookie` 的名字以及 `environmentVariable`，或者改变读取的语言（`requested(context)`）：
+
+```typescript
+import {type BaseContext} from 'lakutata/com/entrypoint'
+import {I18nMiddleware} from 'lakutata/com/i18n'
+
+export class LanguageMiddleware extends I18nMiddleware {
+    protected readonly queryParameter: string = 'locale'
+
+    protected readonly environmentVariable: string = 'SHOP_LANG'
+
+    //优先使用登录用户保存的语言
+    protected requested(context: BaseContext): string[] {
+        const saved: unknown = context.data.userLanguage
+        return [...(typeof saved === 'string' ? [saved] : []), ...super.requested(context)]
+    }
+}
+```
+
+### 消息：插值、复数和格式化
+
+| 语法 | 例子 |
+|---|---|
+| 参数 | `Hello, {name}`：数字按语言格式化，`Date` 按日期格式化，其他值转为字符串 |
+| 数字 | `{n, number}`、`{n, number, integer}`、`{n, number, percent}` |
+| 货币 | `{price, number, currency}`（货币来自 `currency` 参数，否则来自 `currency` 选项）、`{price, number, currency/EUR}` |
+| 日期、时间 | `{at, date, short}`、`{at, time, long}`；样式为 `short`、`medium`（默认）、`long`、`full`；值可以是 `Date`、时间戳、日期字符串或有 `toDate()` 的对象 |
+| 复数 | `{count, plural, =0 {none} one {# item} other {# items}}`：先匹配 `=n` 选项，再按该语言的复数规则；`#` 是数字；支持 `offset:1` |
+| 序数 | `{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}` |
+| 选择 | `{role, select, admin {Administrator} other {User}}` |
+| 转义 | `''` 输出一个撇号；`'{literal}'` 原样输出花括号（复数里的 `'#'` 输出 `#`） |
+
+`plural`、`selectordinal` 和 `select` 必须有 `other` 选项。消息在第一次使用时解析；语法错误会抛出 `I18nMessageSyntaxException`，异常中指出了消息所在的语言、键名和出错的位置。
+
+应用可以声明键名和它们的参数，这样写错键名或漏掉参数时，编译就会失败（`lakutata i18n types` 根据默认语言生成这份声明；没有声明时，接受任意键名）：
+
+```text
+//src/i18n.d.ts
+import 'lakutata/com/i18n'
+
+declare module 'lakutata/com/i18n' {
+    interface I18nMessages {
+        'order.count': { count: number }
+        'order.total': { price: number | bigint, currency?: string }
+    }
+}
+```
+
+### 校验消息和异常
+
+配置了中间件时，请求的校验错误（来自输入 DTO、`@Accept`/`@Return`，以及处理请求时代码里调用的 `DTO.validate`）使用请求的语言。组件在创建时（以及 `addMessages()` 添加新语言时）为它的各种语言注册内置的校验消息。内置了 20 种语言：`en`、`zh-CN`、`zh-TW`、`ja`、`ko`、`fr`、`de`、`es`、`pt-BR`、`it`、`nl`、`pl`、`ru`、`uk`、`tr`、`vi`、`th`、`id`、`hi`、`ar`。应用写在 `validation` 下的消息按错误码叠加在上面，使用校验模板的语法（不是 ICU）：
+
+```json
+{
+  "validation": {
+    "any": {"required": "Please enter {{#label}}"},
+    "string": {"min": "{{#label}} needs {{#limit}} characters at least"}
+  }
+}
+```
+
+某种语言的校验消息以它回退到的语言的消息为基础，先用它自己的内置消息覆盖，再用它自己的应用消息覆盖。`validationMessages: false` 时只注册应用的消息。
+
+请求中抛出异常时，如果 `errors.<errno>` 下有这个 `errno` 对应的消息，异常就会改用这条消息（取请求所用语言的版本），并用异常模板的参数格式化（`{id}`，逐个传入的参数用 `{0}`、`{1}`）；`errno` 保持不变：
+
+```typescript
+import {Exception} from 'lakutata'
+
+//有消息 {"errors": {"E_ORDER_NOT_FOUND": "订单 {id} 不存在"}} 时，中文请求得到 "订单 7 不存在"
+export class OrderNotFoundException extends Exception {
+    public errno: string = 'E_ORDER_NOT_FOUND'
+}
+
+throw new OrderNotFoundException('Order {id} not found', {id: 7})
+```
+
+### 命令行帮助
+
+`commanderTranslator()` 用 `cli` 下的消息（`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`……）按运行环境的语言翻译 Commander 适配器的帮助和提示；没有消息的文字保持英文：
+
+```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],
+            middlewares: [I18nMiddleware],
+            //TOOL_LANG=zh-CN tool --help，或 LANG=zh_CN.UTF-8
+            cli: commanderCLIEntrypoint({bin: 'tool', translate: commanderTranslator({environment: 'TOOL_LANG'})})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+### 检查翻译
+
+`lakutata i18n check` 和 `lakutata i18n types` 背后就是 `loadCatalogs`、`checkCatalogs` 和 `generateMessageTypes` 这几个函数，脚本或 CI 中也可以直接调用：
+
+```typescript
+import {checkCatalogs, loadCatalogs, type CatalogIssue, type Catalogs} from 'lakutata/com/i18n'
+
+const catalogs: Catalogs = await loadCatalogs(['./locales'])
+const issues: CatalogIssue[] = checkCatalogs(catalogs, '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
+```
+
+## API
+
+| 导出 | 说明 |
+|---|---|
+| `I18n` | 组件：`t`、`has`、`format`、`translator`、`negotiate`、`addMessages`、`getLocales`、`getDefaultLocale`、`getKeys`、`getTimeZone` |
+| `buildI18nOptions` | 构造 `I18n` 的组件选项 |
+| `I18nOptions` | 选项：`directory`、`messages`、`locales`、`defaultLocale`、`fallback`、`missing`、`currency`、`timeZone`、`validationMessages` |
+| `Translator` | 作用域提供者，注入到请求中的各个对象里，使用请求的语言 |
+| `ITranslator` | 某一种语言的翻译器：`locale`、`t`、`has`、`format`、`number`、`date` |
+| `LocaleTranslator` | `I18n.translator()` 返回的 `ITranslator` |
+| `I18nMiddleware` | 为每个请求确定语言的入口中间件（`lakutata/com/i18n`、`@lakutata/i18n/middleware`） |
+| `commanderTranslator`、`CommanderTranslatorOptions` | Commander 命令行帮助的翻译及其选项（`lakutata/com/i18n`、`@lakutata/i18n/middleware`） |
+| `I18nMessages`、`MessageKey`、`MessageParams` | 应用的键名和参数的声明，以及由它推导出的类型 |
+| `NestedMessages`、`Catalogs` | 一种语言的消息，按键名的各段嵌套；已加载的消息，按语言和键名组织 |
+| `loadCatalogs`、`checkCatalogs`、`CatalogIssue`、`generateMessageTypes` | 加载消息目录、检查翻译、生成键名的类型 |
+| `normalizeLocale`、`parseAcceptLanguage`、`environmentLocales`、`negotiateLocale`、`fallbackChain` | 处理语言标签的辅助函数 |
+| `parseMessage`、`messageArguments`、`MessagePart` | ICU MessageFormat 解析器，以及消息的参数 |
+| `I18nCatalogException`、`I18nMessageSyntaxException`、`I18nMissingKeyException`、`I18nMissingParameterException`、`I18nTranslatorException` | 异常 |
+
+以上全部由 `lakutata/com/i18n` 导出；`@lakutata/i18n` 导出除中间件相关以外的全部内容，中间件相关的由 `@lakutata/i18n/middleware` 导出。类型声明中的每一项都附有说明和示例。
+
+## 错误
+
+| 异常 | 什么时候 |
+|---|---|
+| `I18nCatalogException`（`E_I18N_CATALOG`） | 创建组件、`addMessages()` 或 `loadCatalogs()` 时：目录不存在、JSON 无效、文件名或目录名不是语言标签、键或值无效、选项不是语言标签、在没有应用时使用别名；`generateMessageTypes()`：默认语言没有消息 |
+| `I18nMessageSyntaxException`（`E_I18N_MESSAGE_SYNTAX`） | 消息不是有效的 ICU MessageFormat，在第一次使用时（或者由 `format()`、`parseMessage()`、`generateMessageTypes()` 解析时）抛出 |
+| `I18nMissingKeyException`（`E_I18N_MISSING_KEY`） | `t()`：找不到这个键的消息，且 `missing: 'throw'` |
+| `I18nMissingParameterException`（`E_I18N_MISSING_PARAMETER`） | `t()`、`format()`：缺少参数，或者货币参数没有货币，且 `missing: 'throw'` |
+| `I18nTranslatorException`（`E_I18N_TRANSLATOR`） | 没有配置 `I18nMiddleware` 就使用 `Translator`，或者在请求之外使用它 |
+| `InvalidValueException`（来自 `lakutata`） | 创建组件时，组件的选项无效 |
+
+## 另见
+
+- 网站上的指南：[国际化（i18n）](https://lakutata.com/zh/guide/I18n)。
+- `lakutata` 包中的 `doc/zh/I18n.md`：国际化指南。
+- `@lakutata/entrypoint`（`lakutata/com/entrypoint`）：控制器、中间件和适配器。
+- `@lakutata/core`（`lakutata`）：组件、`Application`、DTO 校验及其语言（`loadValidationMessages`、`registerValidationMessages`、`runInValidationLanguage`）。
+- `@lakutata/cli`：`lakutata i18n check`、`lakutata i18n types` 和 `lakutata i18n add` 命令。

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

@@ -283,7 +283,7 @@ export declare class I18n extends Component {
      * @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).
+     * emitted once (per key and language, 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'`.

package/dist/cjs/i18n/I18n.js

@@ -378,7 +378,7 @@ class I18n extends core_1.Component {
      * @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).
+     * emitted once (per key and language, 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'`.

package/dist/esm/i18n/I18n.js

@@ -371,7 +371,7 @@ export class I18n extends Component {
      * @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).
+     * emitted once (per key and language, 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'`.

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

@@ -283,7 +283,7 @@ export declare class I18n extends Component {
      * @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).
+     * emitted once (per key and language, 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'`.

package/package.json

@@ -1,7 +1,29 @@
 {
   "name": "@lakutata/i18n",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "The internationalization of the lakutata framework: the messages of each language by their keys (ICU MessageFormat), the language of each request, the messages of the validation.",
+  "keywords": [
+    "lakutata",
+    "i18n",
+    "internationalization",
+    "localization",
+    "icu",
+    "messageformat",
+    "translation",
+    "typescript"
+  ],
+  "homepage": "https://lakutata.com/packages/i18n",
+  "bugs": {
+    "url": "https://github.com/lakutata/lakutata/issues",
+    "email": "admin@lakutata.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lakutata/lakutata.git",
+    "directory": "packages/i18n"
+  },
+  "author": "alex.ma",
+  "license": "MIT",
   "type": "module",
   "main": "./dist/cjs/exports/I18n.js",
   "types": "./dist/cjs/exports/I18n.d.ts",
@@ -39,8 +61,8 @@
     "test:unit": "npm run compile && node --test \"dist/esm/tests/*.spec.js\""
   },
   "peerDependencies": {
-    "@lakutata/core": "3.0.0",
-    "@lakutata/entrypoint": "3.0.0"
+    "@lakutata/core": "3.1.0",
+    "@lakutata/entrypoint": "3.1.0"
   },
   "peerDependenciesMeta": {
     "@lakutata/entrypoint": {
@@ -48,7 +70,7 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.13.0 || >=24.11.0"
   },
   "files": [
     "dist",