lakutata 3.0.0 → 3.1.0

package/doc/en/I18n.md

@@ -1,13 +1,13 @@
 # Internationalization (i18n)
 
-`lakutata/com/i18n` (the `@lakutata/i18n` package) manages the messages of each language by their **keys**: the code
-uses a key, and each language gives the sentence of the key in its own file. The messages use the syntax of
-[ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/); their numbers, currencies, dates
-and plurals are formatted in their language by the `Intl` of Node.js, with no third-party library.
+`lakutata/com/i18n` (package `@lakutata/i18n`) manages the messages of an application by **keys**: the code uses a key,
+and each language gives the text of that key in its own file. The messages are written in [ICU
+MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/); their numbers, currencies, dates and
+plurals are formatted for the language by the built-in `Intl` of Node.js, with no third-party library.
 
-## The files of the messages
+## Message files
 
-A JSON file by language, named by its language tag (BCP 47: `en`, `zh-CN`, `zh-Hant-TW`):
+One JSON file per language, named after its language tag (BCP 47: `en`, `zh-CN`, `zh-Hant-TW`):
 
 ```
 locales/
@@ -24,10 +24,10 @@ locales/
 }
 ```
 
-The nesting of the JSON is the one of the keys: the keys above are `order.count` and `order.created`. A part of a key
-cannot contain `.`.
+The nesting of the JSON gives the keys: the keys above are `order.count` and `order.created`. No part of a key may
+contain `.`.
 
-A language can also be a directory, the names of its files (and of their directories) prefixing their keys:
+A language can also be a directory, in which the names of the files (and of the subdirectories) prefix their keys:
 
 ```
 locales/
@@ -36,7 +36,7 @@ locales/
     admin/user.json    → admin.user.*
 ```
 
-Both layouts can be mixed in a directory.
+Both layouts can be mixed in one directory.
 
 ## Configuration
 
@@ -53,9 +53,9 @@ Application
             i18n: buildI18nOptions({
                 directory: '@locales',               //an alias, or several directories
                 defaultLocale: 'en',                 //the default language, the last fallback (en by default)
-                fallback: {'zh-TW': 'zh-CN'},        //the messages missing in zh-TW are the ones of zh-CN
+                fallback: {'zh-TW': 'zh-CN'},        //the messages missing in zh-TW are taken from zh-CN
                 currency: 'CNY',                     //the currency of {price, number, currency}
-                timeZone: 'Asia/Shanghai'            //the time zone of the dates and the times (the process's by default)
+                timeZone: 'Asia/Shanghai'            //the time zone of dates and times (that of the process by default)
             })
         }
     }))
@@ -63,8 +63,9 @@ Application
 
 Name the component `i18n`: the middleware and `commanderTranslator` use that name.
 
-The messages can also be given in the code instead of a directory: the `messages` option gives them by language, as
-object literals or imported JSON. They are then bundled with the code (`lakutata package bundle`), no file read at run time:
+The messages can also be given in the code instead of a directory: the `messages` option takes them by language, as
+object literals or imported JSON. They are then bundled with the code (`lakutata package bundle`), and no file is read
+at run time:
 
 ```typescript
 import {buildI18nOptions} from 'lakutata/com/i18n'
@@ -82,15 +83,15 @@ const i18n = buildI18nOptions({
 
 | Option | Description |
 |---|---|
-| `directory` | The directories of the messages; aliases accepted |
-| `locales` | The supported languages, which `negotiate()` chooses from; by default the default language, then the languages of the messages |
+| `directory` | The directories of the message files; aliases are accepted |
+| `locales` | The supported languages, which `negotiate()` chooses from; by default, the default language followed by the languages found in the messages |
 | `defaultLocale` | The default language, `en` by default |
-| `fallback` | The languages a message missing in a language is looked up in next (`{'zh-TW': 'zh-CN'}`, or a list) |
-| `messages` | Messages by language given in the code, loaded after the directories (the same keys replaced); no `directory` is needed with them |
-| `missing` | A missing message or argument: `'throw'` throws; `'key'` gives its key (the argument as `{name}`) and warns once. Thrown by default, the key given when `NODE_ENV=production` |
+| `fallback` | Where to look next when a language lacks a message (`{'zh-TW': 'zh-CN'}`, or a list) |
+| `messages` | Messages by language given in the code, loaded after the directories (replacing the same keys); with them, `directory` is not needed |
+| `missing` | What happens to a missing message or argument: `'throw'` throws; `'key'` returns the key (and leaves a missing argument as `{name}`), with a warning the first time. `'throw'` by default, `'key'` when `NODE_ENV=production` |
 | `currency` | The currency when neither the message nor its arguments give one (ISO 4217) |
-| `timeZone` | The time zone of the dates and the times (IANA) |
-| `validationMessages` | Whether the built-in validation messages of the supported languages are registered, `true` by default (see "The errors of the validation") |
+| `timeZone` | The time zone of dates and times (IANA) |
+| `validationMessages` | Whether to register the built-in validation messages of the supported languages, `true` by default (see "Validation errors") |
 
 ## Usage
 
@@ -111,22 +112,22 @@ class OrderService extends Provider {
 
 | Method | Description |
 |---|---|
-| `t(key, params?, locale?)` | The message of a key in a language, formatted with its arguments; the default language by default |
+| `t(key, params?, locale?)` | The message of a key in a language, formatted with the arguments; in the default language when none is given |
 | `has(key, locale?)` | Whether a language (or the ones it falls back to) has a key |
-| `format(message, params?, locale?)` | Format an ICU message which is not in the files |
-| `translator(locale)` | A translator of a language (`ITranslator`), which does not need the language each time |
-| `negotiate(requested)` | The supported language for the requested ones (preferred first), the default one when none is supported |
-| `addMessages(locale, messages)` | Add messages of a language at run time, the same keys replaced |
-| `getLocales()`, `getDefaultLocale()`, `getKeys(locale)`, `getTimeZone()` | The supported languages, the default one, the own keys of a language, the time zone |
+| `format(message, params?, locale?)` | Formats an ICU message that is not in the files |
+| `translator(locale)` | A translator bound to a language (`ITranslator`), so that the language is not passed each time |
+| `negotiate(requested)` | The supported language that best matches the requested ones (preferred first); the default language when none is supported |
+| `addMessages(locale, messages)` | Adds messages to a language at run time, replacing the same keys |
+| `getLocales()`, `getDefaultLocale()`, `getKeys(locale)`, `getTimeZone()` | The supported languages, the default language, the keys a language defines itself, the time zone |
 
-`t()`, `has()`, `format()` and `translator()` do not negotiate the language: an unsupported language is looked up as
-given, then falls back. `addMessages()` returns a promise resolved once the validation messages of a new language are
-registered (the messages themselves are given by `t()` as soon as it returns).
+`t()`, `has()`, `format()` and `translator()` do not negotiate: a language that is not supported is looked up as given,
+then falls back. `addMessages()` returns a promise that resolves once the validation messages of a new language are
+registered; `t()` gives the new messages as soon as `addMessages()` returns.
 
 ### Answering a request in its language
 
-With the `I18nMiddleware` on the entrypoint, each request has its language; the objects of the request inject the
-`Translator`, the messages of that language:
+With the `I18nMiddleware` on the entrypoint, each request gets a language; the objects of the request inject the
+`Translator`, which gives the messages in that language:
 
 ```typescript
 import {Application} from 'lakutata'
@@ -165,8 +166,8 @@ Application.run(() => ({
 }))
 ```
 
-The languages a request asks for are read in this order, then negotiated with the supported ones (see below), the
-default language when none is supported:
+The languages a request asks for are read from the sources below, in order, then negotiated with the supported languages
+(see "Negotiation and fallbacks"); when none is supported, the request gets the default language:
 
 | Entrypoint | Sources (preferred first) |
 |---|---|
@@ -179,11 +180,11 @@ default language when none is supported:
 A query or cookie value that is not a language tag is skipped.
 
 - The objects of a request (the controller, the `@Scoped` providers, the access control rules) inject the same
-  `Translator`; `translator.locale` is the language of the request, so is `context.locale`.
-- The middleware uses the component named `i18n`. To use another one (`@Inject('...') protected readonly i18n`), other
-  names of the query parameter or of the cookie (`queryParameter`, `cookie`), an environment variable
-  (`environmentVariable`), or another way to choose the language (the one saved by the signed-in user), extend
-  `I18nMiddleware`:
+  `Translator`; `translator.locale` and `context.locale` are the language of the request.
+- The middleware uses the component named `i18n`. Extend `I18nMiddleware` to use another component
+  (`@Inject('...') protected readonly i18n`), to rename the query parameter or the cookie (`queryParameter`, `cookie`),
+  to read an environment variable (`environmentVariable`), or to choose the language another way (for example, the
+  language the signed-in user saved):
 
   ```typescript
   import {type BaseContext} from 'lakutata/com/entrypoint'
@@ -202,21 +203,22 @@ A query or cookie value that is not a language tag is skipped.
   }
   ```
 
-- The `Translator` of a request without the `I18nMiddleware` throws an `I18nTranslatorException`.
+- Without the `I18nMiddleware`, the methods of the `Translator` throw an `I18nTranslatorException`.
 - A translator (the `Translator`, and the `ITranslator` of `translator(locale)`) has `locale`, `t(key, params)`,
   `has(key)`, `format(message, params)`, `number(value, options)` and `date(value, options)`.
-- Out of a request (the schedules, the singleton components), the component gives `t(key, params, locale)` and
-  `translator(locale)`.
-- To handle the languages yourself, `parseAcceptLanguage(header)` reads `Accept-Language` and `environmentLocales()`
-  the languages of the environment (`zh_CN.UTF-8` becomes `zh-CN`), for `negotiate()`.
+- Outside a request (in the schedules or the singleton components), use the `t(key, params, locale)` and
+  `translator(locale)` of the component.
+- To choose the language yourself, `parseAcceptLanguage(header)` reads an `Accept-Language` header and
+  `environmentLocales()` reads the languages of the environment (`zh_CN.UTF-8` becomes `zh-CN`); pass their result to
+  `negotiate()`.
 
-## The help and the prompts of a command line tool
+## Help and prompts of a command line tool
 
-The `translate` option of the Commander adapter (`lakutata/adapter/commander`) gives the help and the prompts of a
-command line tool in the language of the user: the descriptions of the program and of its commands, of their arguments
-and options, the hints of the defaults and of the choices, the titles of the help (Usage:, Options:), the descriptions
-of `--help` and `--version`, and the questions asked for the missing required options. The names of the commands and of
-the options are not translated.
+The `translate` option of the Commander adapter (`lakutata/adapter/commander`) shows the help and the prompts of a
+command line tool in the language of the user: the descriptions of the program, of its commands and of their arguments
+and options, the hints about defaults and choices, the headings of the help (Usage:, Options:), the descriptions of
+`--help` and `--version`, and the questions asked for missing required options. The names of commands and options are
+not translated.
 
 `commanderTranslator()` translates them with the messages of an i18n component:
 
@@ -242,7 +244,7 @@ Application.run(() => ({
         i18n: buildI18nOptions({messages: {'zh-CN': zhCN}}),
         entrypoint: buildEntrypoints({
             controllers: [GreetController],
-            //The Translator of the controllers running the commands has the same language
+            //The controllers that run the commands get a Translator in the same language
             middlewares: [I18nMiddleware],
             //TOOL_LANG=zh-CN tool --help, or LANG=zh_CN.UTF-8
             cli: commanderCLIEntrypoint({bin: 'tool', translate: commanderTranslator({environment: 'TOOL_LANG'})})
@@ -268,39 +270,40 @@ Application.run(() => ({
 }
 ```
 
-- The keys (prefixed by `cli.` by default, the `prefix` option changes it):
+- The keys (with the prefix `cli.` by default, which the `prefix` option changes):
   - the program: `description`; the commands: `commands.<command>.description`, `commands.<command>.arguments.<name>`,
     `commands.<command>.options.<property>`;
   - the help: `help.usage`, `help.arguments`, `help.options`, `help.commands`, `help.helpOption`, `help.helpCommand`,
     `help.versionOption`;
   - the hints: `help.default` (`default: {value}`), `help.choices` (`choices: {choices}`), `help.hints` (` ({hints})`,
-    the hints after a description), `help.separator` (`, `), `help.negate` (`Turn off {flag}`);
+    how the hints follow a description), `help.separator` (`, `), `help.negate` (`Turn off {flag}`);
   - the questions: `prompt.json` (`Not a JSON object`).
-- A text without a message is the English one of the code: only the other languages need messages.
-- The language is chosen once, when the adapter starts: the environment variable of the `environment` option, then the
-  environment (`LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`), then the language of the process, negotiated with the
-  supported languages.
-- The wide characters (Chinese, Japanese, Korean) take two columns: the long lines of the help are wrapped between them,
-  no punctuation starting a line.
+- A text without a message stays in the English of the code, so only the other languages need messages.
+- The language is chosen once, when the adapter starts: from the variable named by the `environment` option, then
+  `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`, then the language of the process, and negotiated with the supported
+  languages.
+- Wide characters (Chinese, Japanese, Korean) count as two columns; the long lines of the help can break between them,
+  and no line starts with punctuation.
 - `translate` can be given a function too: `translate: () => (text) => messages[text.key] ?? text.text`.
 
-## The errors of the validation
+## Validation errors
 
-With the `I18nMiddleware`, the errors of the validations of a request are in the language of the request: its input
-(the DTO of `@HTTPAction`, `@CLIAction`, `@ServiceAction`), the arguments and the results of the methods it calls
-(`@Accept`, `@Return`), and the validations of its code (`DTO.validate`, `DTO.validateAsync`).
+With the `I18nMiddleware`, the validation errors of a request are in its language: the errors of its input (the DTO of
+`@HTTPAction`, `@CLIAction`, `@ServiceAction`), of the arguments and results of the methods it calls (`@Accept`,
+`@Return`), and of the validations its code runs (`DTO.validate`, `DTO.validateAsync`).
 
-The validation messages of 20 languages are built in; the component registers the ones of its supported languages when
-it starts (the languages used only are loaded):
+Validation messages for 20 languages are built in; when it starts, the component registers those of its supported
+languages (only the languages in use are loaded):
 
-`en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `fr`, `de`, `es`, `pt-BR`, `it`, `nl`, `pl`, `ru`, `uk`, `tr`, `vi`, `th`, `id`, `hi`, `ar`
+`en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `fr`, `de`, `es`, `pt-BR`, `it`, `nl`, `pl`, `ru`, `uk`, `tr`, `vi`, `th`, `id`,
+`hi`, `ar`
 
-A supported language uses the closest built-in one: `zh`, `zh-Hans`, `zh-SG` use `zh-CN`; `zh-Hant`, `zh-HK`, `zh-MO`
-use `zh-TW`; the others match by their language (`pt-PT` uses `pt-BR`, `fr-CA` uses `fr`). A language without built-in
-messages uses the ones of the languages it falls back to, then English.
+Each supported language uses the closest built-in one: `zh`, `zh-Hans`, `zh-SG` use `zh-CN`; `zh-Hant`, `zh-HK`, `zh-MO`
+use `zh-TW`; other tags match by their language part (`pt-PT` uses `pt-BR`, `fr-CA` uses `fr`). A language without
+built-in messages uses those of the languages it falls back to, then English.
 
-An application replaces or adds validation messages in its messages: under `validation`, by the codes of the errors, in
-the syntax of the templates of the validation (`{{#label}}`, `{{#limit}}`), not ICU:
+An application can replace or add validation messages in its own messages: under `validation`, keyed by error code, and
+written in the template syntax of the validation (`{{#label}}`, `{{#limit}}`) rather than ICU:
 
 ```json
 {
@@ -311,23 +314,23 @@ the syntax of the templates of the validation (`{{#label}}`, `{{#limit}}`), not
 }
 ```
 
-- The validation messages of a language are layered: the built-in and the application messages of the languages it
-  falls back to, then its own built-in and application messages, the later ones replacing the earlier ones.
-- `validationMessages: false` registers no built-in messages, the `validation` messages of the application only.
-- The input of a request is validated as before; only an invalid input is validated again in the language of the
-  request, for its messages. A valid input is not affected at all.
-- A few messages contain English given by the validation itself: the sort order (`ascending`), the reason of a
+- The validation messages of a language are layered: first the built-in and application messages of the languages it
+  falls back to, then its own built-in and application messages; later layers replace earlier ones.
+- `validationMessages: false` registers no built-in messages, only the `validation` messages of the application.
+- The input of a request is validated as usual; only invalid input is validated a second time, in the language of the
+  request, to get the messages. Valid input is not affected at all.
+- A few messages contain English text from the validation library itself: the sort order (`ascending`), the reason for a
   reference error, the message of a custom assertion. These parts stay in English in every language.
-- Without the i18n component, the functions of `lakutata` do it: `loadValidationMessages(language)` loads the built-in
-  messages of a language, `registerValidationMessages(language, messages)` registers them, and a validation gives them
-  with its `{errors: {language}}` option, or `runInValidationLanguage(language, fn)` gives the language to every
-  validation of a code (its asynchronous calls too).
+- Without the i18n component, use the functions of `lakutata`: `loadValidationMessages(language)` loads the built-in
+  messages of a language and `registerValidationMessages(language, messages)` registers them. A validation then chooses
+  a language with its `{errors: {language}}` option, or `runInValidationLanguage(language, fn)` sets the language of
+  every validation that `fn` runs, its asynchronous calls included.
 
-## The messages of the exceptions
+## Exception messages
 
-With the `I18nMiddleware`, an exception thrown by a request whose message is in the messages of the application is
-given the message in the language of the request: its key is `errors.<the errno of the exception>`, formatted with the
-parameters of the template of the exception:
+With the `I18nMiddleware`, when a request throws an exception that has a message among the messages of the application,
+the exception gets that message in the language of the request. The key is `errors.<errno of the exception>`, and the
+message is formatted with the parameters of the template of the exception:
 
 ```typescript
 import {Exception} from 'lakutata'
@@ -343,45 +346,46 @@ throw new OrderNotFoundException('Order {id} not found', {id: 7})
 {"errors": {"E_ORDER_NOT_FOUND": "订单 {id} 不存在"}}
 ```
 
-- A request in Chinese gets `订单 7 不存在`, a request in English the original `Order 7 not found`; the `errno` and
-  the other properties are not changed.
-- The parameters given one by one (`new XxxException('{0} of {1}', a, b)`) are `{0}`, `{1}` in the message.
-- An exception without a message is as it is; so is one whose message cannot be formatted (a missing parameter), with a
-  warning.
-- Out of a request, `exceptionParams(exception)` (from `lakutata`) gives the parameters of an exception, to translate
-  it.
+- A request in Chinese gets `订单 7 不存在`, a request in English the original `Order 7 not found`; the `errno` and the other
+  properties stay unchanged.
+- Parameters passed one by one (`new XxxException('{0} of {1}', a, b)`) are referred to as `{0}`, `{1}` in the message.
+- An exception that has no message in the application stays as it is; so does one whose message cannot be formatted
+  (because of a missing parameter, for example), with a warning.
+- Outside a request, `exceptionParams(exception)` (from `lakutata`) gives the parameters of an exception, so that you
+  can translate it yourself.
 
 ## Negotiation and fallbacks
 
-**Negotiation** (`negotiate`): for each requested language in turn, the same tag, then its language alone
-(`en-GB` → `en`), then another region of its language (`pt-PT` → `pt-BR`, in the order of the supported languages); the
-default language when none matches.
+**Negotiation** (`negotiate`) tries each requested language in turn: the same tag, then its language alone (`en-GB` →
+`en`), then another region of the same language (`pt-PT` → `pt-BR`, in the order of the supported languages). When none
+matches, it returns the default language.
 
-**Fallbacks**: a message missing in a language is looked up in the languages of its `fallback`, then in the tags it is
-more specific than (`zh-Hant-TW` → `zh-Hant` → `zh`), then in the default language. A message is always formatted in
-the **language asked**: an English message falling back in a German request still writes `1.000`.
+**Fallbacks**: when a language lacks a message, the message is looked up in the languages of its `fallback`, then in its
+shorter tags (`zh-Hant-TW` → `zh-Hant` → `zh`), then in the default language. A message is always formatted in the
+**requested language**: an English message used as the fallback for a German request still writes `1.000`.
 
-## The syntax of the messages
+## Message syntax
 
 | 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 of the `currency` argument or of the configuration), `{price, number, currency/EUR}` |
 | Date, time | `{at, date, short}`, `{at, time, long}`, 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 `=value` first, then the plural rules of the language; `#` is the number formatted; `offset:1` supported |
+| Plural | `{count, plural, =0 {none} one {# item} other {# items}}`: the `=value` cases first, then the plural rules of the language; `#` is the formatted number; `offset:1` is supported |
 | Ordinal | `{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}` |
 | Select | `{role, select, admin {Administrator} other {User}}` |
 | Quoting | `''` is an apostrophe; `'{literal}'` writes the braces (`'#'` writes `#` in a plural) |
 
 `plural`, `selectordinal` and `select` need an `other` option. A message is parsed once, when it is first used; a syntax
-error throws an `I18nMessageSyntaxException` telling its language, its key and its position, e.g. `zh-CN: order.count: the "other" option is required at 1`.
+error throws an `I18nMessageSyntaxException` that gives the language, the key and the position, e.g.
+`zh-CN: order.count: the "other" option is required at 1`.
 
-## The types of the keys
+## Typed keys
 
-An application can declare its keys and their arguments: a wrong key or a missing argument is then an error of the
-compilation. `lakutata i18n types` generates the declaration from the messages of the default language (see below), or
-it is written by hand:
+An application can declare its keys and their arguments; a wrong key or a missing argument then fails the compilation.
+`lakutata i18n types` generates the declaration from the messages of the default language (see below), or you can write
+it by hand:
 
 ```typescript
 //src/i18n.d.ts
@@ -397,18 +401,18 @@ declare module 'lakutata/com/i18n' {
 
 Without them, `t()` accepts any key and any arguments.
 
-## The command line tools
+## Command line tools
 
-The `lakutata` command line (`@lakutata/cli`) handles the directories of the messages (`--dir`, `locales` by default;
-several separated by commas):
+The `lakutata` command line (`@lakutata/cli`) works on the message directories (`--dir`, `locales` by default; separate
+several with commas):
 
 | Command | Description |
 |---|---|
-| `lakutata i18n check` | Checks the messages of the languages against the default language (`--default`, `en` by default). Errors: a syntax error of ICU, a key the default language does not have, an argument the default message does not have, an unknown validation code or a variable of another code; warnings: a missing message (falling back), an argument not used, a message the same as the default one (not translated yet). It fails on the errors, on the warnings too with `--strict`, for the CI |
-| `lakutata i18n types` | Declares the keys of the messages of the default language and their arguments (`--out`, `src/i18n.d.ts` by default); `--module @lakutata/i18n` for the applications importing `@lakutata/i18n` |
-| `lakutata i18n add <locale>` | Adds a language made of the messages of the default language (a file or a directory, as the default language has; its `validation` part left, the language having its built-in validation messages), to be translated |
+| `lakutata i18n check` | Checks the messages of each language against the default language (`--default`, `en` by default). Errors: an ICU syntax error, a key the default language does not have, an argument the default message does not have, an unknown validation code, or a variable that belongs to another code. Warnings: a missing message (which falls back), an unused argument, a message identical to the default one (probably not translated yet). It fails on errors, and also on warnings with `--strict`, for CI |
+| `lakutata i18n types` | Writes the type declaration of the keys of the default language and their arguments (`--out`, `src/i18n.d.ts` by default); add `--module @lakutata/i18n` for applications that import `@lakutata/i18n` |
+| `lakutata i18n add <locale>` | Adds a language as a copy of the messages of the default language, ready to translate: a file or a directory, like the default language, without the `validation` part (the new language uses its built-in validation messages) |
 
-The checks are functions of the code too: `loadCatalogs(directories)`, `checkCatalogs(catalogs, defaultLocale)`,
+The checks are also available as functions: `loadCatalogs(directories)`, `checkCatalogs(catalogs, defaultLocale)`,
 `generateMessageTypes(catalogs, defaultLocale)`.
 
 ## Exceptions
@@ -416,7 +420,7 @@ The checks are functions of the code too: `loadCatalogs(directories)`, `checkCat
 | Exception | When |
 |---|---|
 | `I18nCatalogException` | An invalid file or configuration: invalid JSON, a file name which is not a language tag, a missing directory, an alias not resolved |
-| `I18nMessageSyntaxException` | The syntax of a message is wrong |
+| `I18nMessageSyntaxException` | A message has a syntax error |
 | `I18nMissingKeyException` | A key is missing (`missing: 'throw'`) |
 | `I18nMissingParameterException` | An argument is missing (`missing: 'throw'`), or a currency message has no currency |
-| `I18nTranslatorException` | The `Translator` used without the `I18nMiddleware`, or out of a request |
+| `I18nTranslatorException` | The `Translator` is used without the `I18nMiddleware`, or outside a request |

package/doc/en/Injection.md

@@ -0,0 +1,144 @@
+# Lakutata Dependency Injection
+
+An object does not create the objects it uses: it declares them, and the container provides them when it creates the
+object. This page covers `@Inject` and `@Autoload`, the options of objects (`@Configurable`), and sharing a feature
+between applications as a package. [Decorator](Decorator.md), section 1, gives every rule of these decorators.
+
+## 1. Injecting objects
+
+`@Inject` (from `lakutata/decorator/di`) sets a property when the object is created, before `init()`:
+
+- `@Inject()`: the object registered under the property name;
+- `@Inject('name')` or `@Inject(symbol)`: the object registered under that name;
+- `@Inject(SomeClass)`: the object registered for the class (`@Inject(Application)` gives the application);
+- `@Inject('name', transform)`: the value returned by `transform(object)` (it may be async).
+
+A class marked `@Autoload()` is registered the first time it is requested, instead of failing: a singleton in the root
+container, a scoped class in the nearest scope, a transient class in the container that requested it. A dependency that
+cannot be resolved fails the creation with a `DependencyInjectionException`.
+
+```typescript
+import {Application, Component, Provider} from 'lakutata'
+import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
+
+//Not declared in the application: registered the first time it is injected
+@Autoload()
+@Scoped()
+class RequestClock extends Provider {
+    public readonly startedAt: number = Date.now()
+}
+
+class Reports extends Component {
+    @Inject(RequestClock)
+    protected readonly clock: RequestClock
+
+    @Inject(Application)
+    protected readonly app: Application
+
+    public elapsed(): number {
+        return Date.now() - this.clock.startedAt
+    }
+}
+```
+
+Code that is not itself an object of the container (an `onLaunched` handler, for example) gets objects with
+`app.getObject(name)`; `app.getObject(SomeClass)` works for a class registered on its own, such as an autoloaded class,
+not for a component declared under a name.
+
+## 2. Options
+
+`@Configurable(schema, fn?)` turns a property into an option of the object. Its value comes from the object's
+declaration (`{class: Mailer, host: 'smtp.example.com'}`) or from the second argument of `getObject()`; the schema
+validates it, and `fn`, when given, transforms it. The application checks the options of the objects it declares when
+it launches: an invalid value stops the launch with an `InvalidObjectOptionsException`, and an option that matches no
+configurable property produces a warning.
+
+```typescript
+import {Application, Component, DTO, type ILogger} from 'lakutata'
+import {Configurable, Inject} from 'lakutata/decorator/di'
+
+class Mailer extends Component {
+    //An option, set by the component's declaration in the application options
+    @Configurable(DTO.String().required())
+    protected readonly host: string
+
+    //25 unless configured: the initializer is the default and is validated like a configured value
+    @Configurable(DTO.Number().integer().min(1).max(65535))
+    protected readonly port: number = 25
+
+    //The logger preset by the lakutata package as the "log" component
+    @Inject('log')
+    protected readonly log: ILogger
+
+    protected async init(): Promise<void> {
+        this.log.info('Mailer connected to %s:%d', this.host, this.port)
+    }
+
+    public async send(to: string, text: string): Promise<void> {
+        this.log.info('Mail to %s: %s', to, text)
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'com.example.app',
+        name: 'Example',
+        components: {
+            mailer: {class: Mailer, host: 'smtp.example.com'}
+        },
+        bootstrap: ['mailer']
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const mailer: Mailer = await app.getObject<Mailer>('mailer')
+        await mailer.send('someone@example.com', 'Hello')
+    })
+```
+
+[Decorator](Decorator.md), section 1.2, gives the order in which a value is chosen (the configured value, the
+initializer, the default of the schema) and the checks made at launch.
+
+## 3. Sharing features between applications
+
+To use a feature in several applications, put it in a package. The package exports a `Component` (or a `Provider`) and
+a function that builds its declaration, the way the packages of the framework do (`buildDatabaseOptions` of
+`lakutata/com/database`, `buildQueueOptions` of `lakutata/com/queue`). The application declares the component under a
+name of its choice and passes the options to the function. The component's `@Configurable` schemas check the options
+when the application launches, and the other objects inject the component by its name.
+
+```typescript
+import {Application, Component, type ComponentOptions, DTO} from 'lakutata'
+import {Configurable, Inject} from 'lakutata/decorator/di'
+
+//In the package: the component, and the function that builds its declaration
+export interface BillingOptions {
+    currency: string
+}
+
+export class Billing extends Component {
+    @Configurable(DTO.String().length(3).required())
+    public readonly currency: string
+
+    public charge(amount: number): string {
+        return `Charged ${amount} ${this.currency}`
+    }
+}
+
+export function buildBillingOptions(options: BillingOptions): ComponentOptions<BillingOptions> {
+    return {class: Billing, ...options}
+}
+
+//In the application
+class Checkout extends Component {
+    @Inject('billing')
+    protected readonly billing: Billing
+}
+
+Application.run(() => ({
+    id: 'shop.app',
+    name: 'Shop',
+    components: {
+        billing: buildBillingOptions({currency: 'EUR'}),
+        checkout: {class: Checkout}
+    }
+}))
+```