npm - @nxgt/mail-i18n - Versions diffs - 0.1.0 - Mend

@nxgt/mail-i18n 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/LICENSE +21 -0
package/README.md +470 -0
package/dist/catalogues.d.ts +40 -0
package/dist/catalogues.d.ts.map +1 -0
package/dist/index.d.ts +26 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +675 -0
package/dist/index.js.map +17 -0
package/dist/manifest.d.ts +45 -0
package/dist/manifest.d.ts.map +1 -0
package/dist/plugin.d.ts +55 -0
package/dist/plugin.d.ts.map +1 -0
package/dist/sources.d.ts +19 -0
package/dist/sources.d.ts.map +1 -0
package/dist/template.d.ts +22 -0
package/dist/template.d.ts.map +1 -0
package/dist/translator.d.ts +31 -0
package/dist/translator.d.ts.map +1 -0
package/dist/types.d.ts +31 -0
package/dist/types.d.ts.map +1 -0
package/dist/vue.d.ts +44 -0
package/dist/vue.d.ts.map +1 -0
package/dist/wrappers.d.ts +62 -0
package/dist/wrappers.d.ts.map +1 -0
package/docs/README.md +17 -0
package/docs/guide/catalogues.md +354 -0
package/docs/guide/editor.md +215 -0
package/docs/guide/manifest.md +343 -0
package/docs/guide/templates.md +421 -0
package/docs/guide/translator.md +170 -0
package/docs/roadmap.md +91 -0
package/docs/troubleshooting.md +1096 -0
package/package.json +71 -0

package/docs/guide/templates.md ADDED Viewed

@@ -0,0 +1,421 @@
+# Templates
+This page is for writing a template once for every locale: what `t`, `locale`
+and `placeholder` do, how templates a package ships are built with yours,
+what fails the build, and what `maizzle serve` and `maizzle build` do with it.
+```vue
+<!-- emails/verify-email.vue -->
+<template>
+  <Html :lang="locale">
+    <Body>
+      <Container>
+        <Heading>{{ t('verifyEmail.title') }}</Heading>
+        <Text>{{ t('verifyEmail.greeting', { name: placeholder('name') }) }}</Text>
+        <Text>{{ t('verifyEmail.expires', { minutes: 15 }) }}</Text>
+        <Text>{{ t('verifyEmail.sentOn', { at: new Date(Date.UTC(2026, 0, 2, 12)) }) }}</Text>
+        <Button :href="placeholder('link')">{{ t('verifyEmail.action') }}</Button>
+      </Container>
+    </Body>
+  </Html>
+</template>
+```
+With the catalogues of [Catalogues](catalogues.md), `maizzle build` writes, in
+`dist/fr/verify-email.html`:
+```html
+<html lang="fr" …>
+  <h1>Confirmez votre adresse e-mail</h1>
+  <p>Bonjour {{ name }},</p>
+  <p>Le lien expire dans 15 minutes.</p>
+  <p>Envoyé le 2 janvier 2026.</p>
+  <a href="{{ link }}">… Confirmer mon adresse …</a>
+```
+and the same in English in `dist/en/verify-email.html`, each with its `.txt`.
+Plurals and dates are formatted by each locale's rules.
+## What a template gets
+The plugin sets three global properties before each render. They need no
+import:
+```ts
+// what the package declares for Vue's template checker
+declare module 'vue' {
+	interface ComponentCustomProperties {
+		t<K extends TemplateKey>(key: K, ...args: TemplateArgs<K>): string;
+		readonly locale: string;
+		placeholder(name: string): string;
+	}
+}
+```
+`TemplateKey` is a key of your catalogues, and `TemplateArgs<K>` its
+arguments, once the plugin has written their types — see
+[Editor and type checking](editor.md). Before that, the template checker does
+not know `t` at all; the build is not affected.
+A component used by the template sees them too: they are global, and they
+hold the locale being built.
+### `t(key, args?)`
+Formats the message `key` in the locale being built. It checks each call
+against the fallback locale's message, which declares every argument:
+- the key must exist;
+- every argument the message declares must be passed, even one this
+  locale's translation leaves out;
+- no argument may be passed that the message does not use;
+- each argument must be of its kind: a number for `{n, number}` or a plural,
+  a `Date` or a timestamp for a date, a string or a number for the rest. See
+  [Arguments](catalogues.md#arguments).
+```vue
+<Text>{{ t('verifyEmail.expires', { minutes: 15 }) }}</Text>
+<!-- 'The link expires in 15 minutes.' / 'Le lien expire dans 15 minutes.' -->
+```
+The formatted message is text: Vue escapes it where it is written, as it
+escapes any `{{ }}`.
+### `locale`
+The locale this build of the template is in: `'en'`, `'fr'`, `'pt-BR'`.
+Read it; never assign it.
+```vue
+<Html :lang="locale">
+```
+```vue
+<img :src="`/images/banner-${locale}.png`" alt="">
+```
+### `placeholder(name)`
+Answers `{{ name }}`, a mark kept as it is through inlining, minification and
+plain text, for the sending side to fill with a value only known then: a
+name, a link, a code. `name` is `camelCase`.
+**In text:**
+```vue
+<Text>{{ placeholder('code') }}</Text>
+<!-- <p>{{ code }}</p> -->
+```
+**In an attribute** — bind it, with `:`:
+```vue
+<Button :href="placeholder('link')">{{ t('verifyEmail.action') }}</Button>
+<!-- <a href="{{ link }}"> -->
+```
+A placeholder that starts the value of an `href`, a `src`, a `background`, a
+`poster` or an `action` is recorded as a URL variable in the
+[manifest](manifest.md). The sending side must fill it with a URL. One later
+in the value, as `?token={{ token }}`, is an ordinary variable.
+**In the text part only**: a placeholder inside Maizzle's `<Plaintext>`
+block is in the `.txt` file alone, and is still one of the e-mail's
+variables.
+<a id="a-placeholder-as-an-argument"></a>
+**As an argument** of a message, where the message uses it as a string:
+```vue
+<Text>{{ t('verifyEmail.greeting', { name: placeholder('name') }) }}</Text>
+<!-- <p>Bonjour {{ name }},</p> -->
+```
+A placeholder is a string. It cannot fill a `number` or `date` argument,
+because the plural rule or the date format would have to be applied to a
+value that does not exist yet — nor an argument a `select` chooses on, which
+would always choose `other`. Format those at build time, or write the value
+outside the message.
+**Never write `{{ name }}` yourself.** Vue would evaluate `name` as an
+expression, at build time, and the mark would never reach the built file. **Never branch on a placeholder** either:
+`v-if="placeholder('link').startsWith('https:')"` is decided on the string
+`{{ link }}`, once, at build time.
+Keep Maizzle's `url.base` off for links: it would turn `href="{{ link }}"` into
+`href="https://cdn.example.com/{{ link }}"`.
+## Template names
+A template's path under `emails/` names the e-mail: `emails/verify-email.vue`
+is `verify-email`, and `emails/auth/reset-password.vue` is
+`auth/reset-password`. Every segment is kebab-case: lower-case letters and
+digits, joined by single dashes.
+The name also gives the key of its subject, `verifyEmail.subject`, through
+[`emailKey`](catalogues.md#the-subject).
+## Templates from a package
+A package can ship templates as well as messages — `@nxgt/mail-presets`
+ships nine ready e-mails. The `templates` option builds a package's folder
+with yours, once per locale, into the same output and the same manifest:
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { i18n } from '@nxgt/mail-i18n';
+import { presets } from '@nxgt/mail-presets';
+import { ui, uiCatalogues } from '@nxgt/mail-ui';
+const mails = presets({ only: ['verify-email', 'welcome'] });
+export default defineMailConfig({
+	plugins: [
+		ui({ brand: { name: 'Acme' } }),
+		i18n({
+			locales: ['en', 'fr'],
+			catalogues: [uiCatalogues, mails.catalogues],
+			templates: [mails.templates],
+		}),
+	],
+});
+```
+```ts
+interface I18nOptions {
+	// …
+	readonly templates?: readonly TemplateSource[]; // default []
+}
+interface TemplateSource {
+	/** The folder, absolute. */
+	readonly dir: string;
+	/** The e-mails of the folder to build, as ['verify-email']. Default every one. */
+	readonly emails?: readonly [string, ...string[]]; // at least one
+}
+```
+A package answers its `TemplateSource` from a function, as `presets()` does,
+so you rarely write one. By hand, `dir` is absolute — a package finds its own
+with `fileURLToPath(new URL('../emails', import.meta.url))` — and `emails`
+names templates of that folder as the plugin names them, `auth/reset-password`
+for `auth/reset-password.vue`:
+```ts
+import type { TemplateSource } from '@nxgt/mail-i18n';
+import { TEMPLATES_DIR } from '@nxgt/mail-presets';
+const two: TemplateSource = { dir: TEMPLATES_DIR, emails: ['sign-in-code', 'magic-link'] };
+```
+### Which template is built
+Your `emails/` is read first, then each source as listed:
+- **Your template replaces a package's.** With `emails/welcome.vue` in your
+  project, `welcome` is built from yours; the package's `welcome.vue` is
+  never read.
+- **Two sources with the same e-mail are refused.** Neither would be the
+  obvious one, so the build stops rather than pick: keep one with `emails`,
+  or write your own in `emails/`.
+- **`emails` keeps only those.** A source's other templates are not built,
+  and are not in the manifest. Leave it out for every one; an empty list does
+  not compile, and is refused at run time. Your own `emails/` is always built
+  whole.
+- **A source must hold templates.** A `dir` that is missing or has no `.vue`
+  file is refused — usually a path to the package rather than to its
+  e-mails folder.
+```ts
+import { i18n } from '@nxgt/mail-i18n';
+// the e-mails folders of two packages that both ship welcome.vue
+declare const accountEmails: string;
+declare const otherEmails: string;
+// keep the first one's welcome
+i18n({
+	locales: ['en', 'fr'],
+	templates: [
+		{ dir: accountEmails, emails: ['welcome', 'verify-email'] },
+		{ dir: otherEmails, emails: ['invitation'] },
+	],
+});
+```
+The wrapper of a package's template imports it from where it is:
+```vue
+<!-- .maizzle/i18n/fr/verify-email.vue, generated; the path follows your install -->
+<script setup>
+import Email from '../../../node_modules/@nxgt/mail-presets/emails/verify-email.vue';
+</script>
+<template><Email /></template>
+```
+A package's template is built like yours: it calls `t` on the catalogues you
+give the plugin, so its package's messages go in `catalogues` — see
+[Catalogues from a package](catalogues.md#catalogues-from-a-package) — and
+its placeholders are recorded in the manifest. Its names are checked for
+kebab-case like yours, reported as `templates[0]/…`. `maizzle serve` watches
+your `emails/` for added and removed templates, not a package's folder.
+The tags of a template under `node_modules` are not resolved by Maizzle,
+which skips that folder. The plugin that ships the components resolves them —
+`@nxgt/mail-ui`'s `ui()` does, for its `Nx*` components and Maizzle's
+built-ins, so list it in `plugins`. A tag left unresolved renders nothing,
+and the build fails on the empty e-mail (see
+[What fails the build](#what-fails-the-build)).
+### Its errors
+| Error | When |
+| --- | --- |
+| `TypeError: i18n: templates must be a list of template folders, as [{ dir: '/abs/path/emails' }] — emails, when given, names at least one, each once` | When the config loads: `templates` not a list (`templates: mails.templates`), a `dir` that is not absolute, or `emails` that is not a list of names, is empty, or names one twice |
+| `Error: i18n: templates[0] has no template sign-in.vue — name one of its e-mails` | When the config loads: a name in `emails` the folder does not have. `templates[0]` is the source's place in the list |
+| `Error: i18n: templates[0] holds no template — is /…/emails the folder of a package's e-mails?` | When the config loads: a `dir` that does not exist, or holds no `.vue` file |
+| `Error: i18n: templates[0] and templates[1] both have welcome.vue — keep one with emails: [...], or write the project's own in its folder` | When the config loads: two sources ship an e-mail of the same name, and your `emails/` does not have it |
+```ts
+i18n({ locales: ['en'], templates: [{ dir: 'node_modules/@nxgt/mail-presets/emails' }] });
+// TypeError: i18n: templates must be a list of template folders, as [{ dir: '/abs/path/emails' }] — emails, when given, names at least one, each once
+```
+## What fails the build
+A template that cannot be right stops the build. The message names the
+locale, the e-mail and the key. Maizzle builds the locales in no set order, so
+either locale may be the one reported. Each is a plain `Error`: a mistake in
+the template or the catalogues, to fix, not a condition to catch.
+| Build failure | Cause |
+| --- | --- |
+| `i18n: fr: verify-email calls t('verifyEmail.titel'), which is not a key of the catalogues` | A key that does not exist |
+| `i18n: en: verify-email calls t('verifyEmail.expires') without {minutes}` | An argument the message declares, not passed |
+| `i18n: fr: verify-email passes {minutes} to verifyEmail.expires as a string — the message uses it as a number` | An argument of the wrong kind; here, a placeholder where a plural needs a number |
+| `i18n: en: verify-email passes {name} to verifyEmail.title, which does not use it` | An argument the message does not use |
+| `i18n: en: verify-email passes a placeholder to {plan}, which verifyEmail.title chooses on with a select — a placeholder always chooses other` | `placeholder()` passed to an argument the message chooses on with a `select`: it would always choose `other`. Pass a value the build knows |
+| `i18n: en: verify-email calls t('verifyEmail.title') with arguments that are not an object, as { name: placeholder('name') }` | `t('verifyEmail.greeting', placeholder('name'))`: the arguments go in an object |
+| `i18n: fr: verify-email calls placeholder() with a name that is not camelCase — as placeholder('firstName')` | `placeholder('first name')`, `placeholder('first_name')` |
+| `i18n: fr: verifyEmail.sentOn could not be formatted` | The formatter refused the value, such as a date that is `NaN`; its error is the `cause` |
+| `i18n: templates[0] has no template sign-in.vue — name one of its e-mails` | A [package's source](#templates-from-a-package) lists, in `emails`, a template its folder does not have; checked when the config loads |
+| `i18n: templates[0] holds no template — is /…/emails the folder of a package's e-mails?` | A package's source whose `dir` is missing or has no template; checked when the config loads |
+| `i18n: templates[0] and templates[1] both have welcome.vue — keep one with emails: [...], or write the project's own in its folder` | Two package sources ship the same e-mail; checked when the config loads |
+| `i18n: fr/welcome.html is empty — a tag of its template resolved to no component; list the plugin that brings it, as ui()` | The e-mail rendered nothing but the doctype: a tag of its template, usually the layout, matched no component, and Vue renders an unknown component as nothing. Typically `ui()` is missing from `plugins`, or a package's template uses a component no plugin brings. Reported when the manifest is written |
+| `i18n: emails/Welcome.vue is not a kebab-case name — name a template as verify-email.vue` | A template whose path is not kebab-case, checked when the config loads. Under `maizzle serve`, one added while the server runs is printed with `console.error`, and the server keeps running |
+| `i18n: welcome has no subject — add welcome.subject to the catalogues` | The e-mail has no subject message; reported when the manifest is written, at the end of the build. The other manifest failures, including an output path set in a template, are in [The manifest](manifest.md#where-it-is-written) |
+| `i18n: emails/verify-email.vue is not built through the i18n plugin — leave content to it, and put templates in emails/` | Maizzle rendered a template directly: the project set its own `content` |
+The last one comes from replacing the plugin's `content`:
+```ts
+// maizzle.config.ts — wrong: content replaces the plugin's, which points at the generated files
+export default defineMailConfig({
+	plugins: [i18n({ locales: ['en', 'fr'] })],
+	content: ['emails/**/*.vue'],
+});
+// right: templates live in `emails` (or the folder named by the `emails` option)
+export default defineMailConfig({
+	plugins: [i18n({ locales: ['en', 'fr'] })],
+});
+```
+## What the build writes
+For each template and locale, the plugin generates a small file, a
+**wrapper**, under `.maizzle/i18n/`. The wrapper imports the template and
+nothing else, and the plugin points Maizzle's `content` at these files. One
+`maizzle build` then renders every template once per locale, and `t` knows
+which locale each render is for.
+```vue
+<!-- .maizzle/i18n/fr/verify-email.vue, generated -->
+<!-- Generated by @nxgt/mail-i18n: one per template and locale. Never edited, never committed. -->
+<script setup>
+import Email from '../../../emails/verify-email.vue';
+</script>
+<template><Email /></template>
+```
+Wrappers are written when the config loads, only when their text changed, and
+only on the main thread: above 50 wrappers (templates × locales; Maizzle's
+`parallel.threshold`) Maizzle builds in parallel, each worker loads the
+config again, and the workers do not write. A parallel build
+writes the same files and the same manifest, which the package's specs check. A wrapper whose template is gone is removed.
+`.maizzle/` belongs in `.gitignore`.
+The output follows the wrappers, under Maizzle's `output.path` (`dist` by
+default):
+| `layout` | Wrapper | Built files |
+| --- | --- | --- |
+| `'nested'` (default) | `.maizzle/i18n/fr/auth/reset-password.vue` | `dist/fr/auth/reset-password.html`, `.txt` |
+| `'flat'` | `.maizzle/i18n/auth/reset-password.fr.vue` | `dist/auth/reset-password.fr.html`, `.txt` |
+```ts
+// maizzle.config.ts — the fixture's flat build, in its own folder
+import { defineMailConfig } from '@nxgt/mail-config';
+import { i18n } from '@nxgt/mail-i18n';
+export default defineMailConfig({
+	plugins: [i18n({ locales: ['en', 'fr'], layout: 'flat' })],
+	output: { path: 'dist-flat' },
+});
+```
+Then the plugin writes `mail-manifest.json` next to them. See
+[The manifest](manifest.md).
+## `maizzle serve`
+The dev UI lists each template once per locale, by its wrapper:
+```text
+.maizzle/i18n/en/auth/reset-password.vue
+.maizzle/i18n/en/verify-email.vue
+.maizzle/i18n/fr/auth/reset-password.vue
+.maizzle/i18n/fr/verify-email.vue
+```
+Placeholders show as they are, `Bonjour {{ name }},`: the preview is the file
+that will be built.
+While it runs:
+- **Editing a template** refreshes every locale of it: each wrapper imports
+  it.
+- **Adding or removing a template** under `emails/` writes or removes its
+  wrappers, and the list follows. A template added with a name that is not
+  kebab-case is reported with `console.error`, and the server keeps
+  running; `maizzle build` fails on it.
+- **Saving a catalogue** reloads the config, which checks the catalogues
+  again. Maizzle watches `locales/`; when `dir` names another folder, the
+  plugin adds it to `server.watch`.
+A failure in `t` shows in the preview of that template and locale, with the
+same message, instead of the e-mail. `maizzle serve` does not write the
+manifest, so a missing subject is only reported by `maizzle build`.
+## Typing templates
+`i18n()` writes `.maizzle/nxgt-mail-i18n.d.ts` each time the config loads, so
+Vue's language tools complete a key of `t` and flag an unknown key or a wrong
+argument in the editor and in `vue-tsc`:
+```vue
+<Text>{{ t('verifyEmail.titel') }}</Text>
+<!-- Argument of type '"verifyEmail.titel"' is not assignable to parameter of type 'keyof TemplateMessages'. -->
+```
+The setup, what the file holds, and each kind of argument are in
+[Editor and type checking](editor.md).
+## See also
+- [Catalogues](catalogues.md) — the messages `t` reads, and the kinds of
+  argument.
+- [Editor and type checking](editor.md) — `t`'s keys and arguments, typed
+  from the catalogues.
+- [The manifest](manifest.md) — what the build records about placeholders.

package/docs/guide/translator.md ADDED Viewed

@@ -0,0 +1,170 @@
+# Translating outside templates
+This page is for using the project's catalogues from your application's own
+code, with `createTranslator`. Typical uses are the text of a notification, a
+text message, a string a test compares with, or a subject built outside
+Maizzle.
+```ts
+import { pickLocale } from '@nxgt/mail';
+import { createTranslator } from '@nxgt/mail-i18n';
+import en from './locales/en.json';
+import fr from './locales/fr.json';
+declare const user: { locale: string | null };
+const t = createTranslator({ en, fr }, () => pickLocale(user.locale, ['en', 'fr'], 'en'));
+t('verifyEmail.expires', { minutes: 15 }); // 'The link expires in 15 minutes.' for an English user
+```
+`pickLocale` comes from `@nxgt/mail` (`bun add @nxgt/mail`, a package with
+no dependency). It answers the first of the user's locales that the
+catalogues have, or the fallback. It picks `fr` for `fr-CA`, and `en` for
+`null` or `de`. Put it in the language provider, and `t` never meets a
+language it has no catalogue for. Any function that returns one of the
+catalogues' locales works as well: `() => (user.locale === 'fr' ? 'fr' : 'en')`.
+## The signature
+```ts
+import type { Catalogues } from '@nxgt/mail-i18n';
+type LanguageProvider = string | (() => string);
+type MessageArgs = Readonly<Record<string, string | number | Date>>;
+type Translate = (key: string, args?: MessageArgs, language?: LanguageProvider) => string;
+function createTranslator(catalogues: Catalogues, getLanguage: LanguageProvider): Translate;
+```
+| Parameter | Type | Effect |
+| --- | --- | --- |
+| `catalogues` | `Catalogues` | The catalogues by locale, `{ en, fr }`, as written in `locales/`. A JSON import is accepted as it is |
+| `getLanguage` | `string \| () => string` | The language of every call that does not name one. A function is called **at each call**, so it can read the current user or request |
+`t(key, args?, language?)`:
+| Argument | Effect |
+| --- | --- |
+| `key` | The dotted key, `verifyEmail.title` |
+| `args` | The message's arguments: a string, a number or a `Date` each |
+| `language` | This call's language, a locale or a function: overrides `getLanguage` |
+```ts
+const t = createTranslator({ en, fr }, 'fr');
+t('verifyEmail.expires', { minutes: 1 }); // 'Le lien expire dans 1 minute.'
+t('verifyEmail.expires', { minutes: 1 }, 'en'); // 'The link expires in 1 minute.'
+t('verifyEmail.expires', { minutes: 1 }, () => 'en'); // 'The link expires in 1 minute.'
+```
+Compiled messages are cached per locale and key, so calling `t` in a loop is
+cheap.
+## How it differs from `@nxgt/i18n`
+The shape is the same: `createTranslator(resources, getLanguage)` answers
+`t(key, args, language?)`, and a language is a string or a function that
+answers one. The difference is what happens when a translation cannot be
+right:
+| Situation | `@nxgt/i18n` | `@nxgt/mail-i18n` |
+| --- | --- | --- |
+| A key the language's catalogue does not have | Answers the key, `'verifyEmail.titel'` | **Throws** `t: fr: verifyEmail.titel is not a key`. So does a key that names a group of messages, `verifyEmail` |
+| A language with no catalogue | Answers the key | **Throws** `t: the language is not a locale of the catalogues — pick one with pickLocale` |
+| A message that does not format (an argument missing) | Logs, and answers the raw message with `{name}` in it | **Throws** `t: en: common.greeting could not be formatted`, the formatter's error as `cause` |
+A web page can show a key for a moment and correct it on the next deploy. An
+e-mail cannot be corrected once it has gone out, and one with `{link}` in it
+is worse than none. So this `t` refuses, and the caller decides what to do.
+The error never names the language itself when it is unknown: a language
+often comes from a user's profile, and a message reports a shape, never a
+value.
+## Errors
+A `TypeError` when the translator is created with the wrong arguments, a
+plain `Error` when `t` refuses. Neither has a `code`: each is a mistake in the
+code or the catalogues, to fix, never a condition to `switch` on.
+| Thrown | When | Message |
+| --- | --- | --- |
+| `TypeError` | `createTranslator` is called | `createTranslator: catalogues must be an object of catalogues by locale, as { en, fr }` |
+| `TypeError` | `createTranslator` is called | `createTranslator: getLanguage must be a locale or a function that answers one` |
+| `Error` | `t` is called | `t: the language is not a locale of the catalogues — pick one with pickLocale` |
+| `Error` | `t` is called | `t: fr: common.greting is not a key` |
+| `Error` | `t` is called | `t: en: common.greeting could not be formatted` (with `cause`) |
+The error's own message names the locale and the key, never the text of the
+message. Its `cause`, the formatter's error, may quote that text: it is kept
+for debugging, and a catalogue's text is not a secret.
+```ts
+const t = createTranslator({ en, fr }, () => 'de');
+t('verifyEmail.title'); // Error: t: the language is not a locale of the catalogues — pick one with pickLocale
+```
+## What it does not check
+`createTranslator` reads the catalogues it is given. It does not run the
+checks of the build: that every locale has the fallback's keys, that the
+arguments agree. The build has run them on the same files, so import the
+catalogues the project builds from. An argument passed and not used is
+ignored. An argument the message needs and did not get is the formatting
+failure above.
+## A realistic use
+A reminder sent as a text message, in the recipient's locale, from the same
+catalogues as the e-mails:
+```ts
+// reminders.ts, in the application
+import { pickLocale } from '@nxgt/mail';
+import { createTranslator } from '@nxgt/mail-i18n';
+import en from './locales/en.json';
+import fr from './locales/fr.json';
+const locales = ['en', 'fr'] as const;
+const t = createTranslator({ en, fr }, 'en');
+interface User {
+	readonly phone: string;
+	readonly locale: string | null;
+}
+export function reminderText(user: User, minutes: number): string {
+	const language = pickLocale(user.locale, locales, 'en');
+	return t('verifyEmail.expires', { minutes }, language);
+}
+```
+The recipient's locale is a field of the user, not the language of the
+request that triggers the send. A language per call keeps one translator for
+the whole application.
+In a test, `t` gives the string a built e-mail should contain, in the
+locale under test:
+```ts
+import { expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { createTranslator } from '@nxgt/mail-i18n';
+import en from './locales/en.json';
+import fr from './locales/fr.json';
+const t = createTranslator({ en, fr }, 'en');
+test.each(['en', 'fr'])('the %s verification e-mail says when the link expires', (locale) => {
+	const html = readFileSync(`dist/${locale}/verify-email.html`, 'utf8');
+	expect(html).toContain(t('verifyEmail.expires', { minutes: 15 }, locale));
+});
+```
+## See also
+- [Catalogues](catalogues.md) — the format `createTranslator` reads.
+- [Templates](templates.md) — `t` inside a template, which also checks the
+  arguments against the fallback locale.

package/docs/roadmap.md ADDED Viewed

@@ -0,0 +1,91 @@
+# Roadmap
+Where `@nxgt/mail-i18n` is heading. A direction, not a commitment: there are
+no dates here, and the version something shipped in is the only number.
+## Now
+Nothing between releases.
+## Next
+Nothing yet.
+## Later
+Nothing yet. A request is welcome as an
+[issue](https://github.com/softistx/nxgt-mail/issues).
+## Not planned
+- **Answering the key on a missing message** — `@nxgt/i18n` answers the key
+  when a message is missing; here a missing key, a language with no catalogue
+  or a formatting failure throws, in templates and in `createTranslator`
+  alike. An e-mail must never go out with `verifyEmail.title` or `{link}` in
+  it, so the failure belongs at build time.
+- **A template engine at run time** — templates are built by `maizzle build`;
+  at send time only `{{ name }}` placeholders are filled in the built files.
+  No Handlebars, no MJML, no Maizzle in your server.
+- **One HTML file per language, written by hand** — one template per e-mail,
+  its text keys into catalogues; building one file per locale is this
+  plugin's job.
+- **A translation-management integration** — the catalogues are JSON files in
+  your project, in the `@nxgt/i18n` layout; syncing them with a translation
+  service is left to your own tooling.
+## Shipped
+The last ten, newest first, each with the version it came in. Everything
+before is in the [CHANGELOG](../CHANGELOG.md).
+- **i18n as a plugin, v0.1.0** — `i18n({ locales, fallbackLocale })`, listed in
+  `defineMailConfig`'s `plugins`: one template per e-mail, its text keys into
+  `locales/<locale>.json` ICU catalogues, and one output per locale from a
+  single `maizzle build` — `dist/<locale>/<template>.html`, or
+  `dist/<template>.<locale>.html` with `layout: 'flat'`. `maizzle serve` lists
+  every locale, and picks up a template added or removed.
+- **Catalogues checked at build time, v0.1.0** — a missing or broken catalogue, a key
+  that is not camelCase, a message that does not parse, a key missing in one
+  locale, an argument a translation invents or types differently: the build
+  fails, naming the locale and the key.
+- **`t`, `locale` and `placeholder` in templates, v0.1.0** — `{{ t('verifyEmail.title')
+  }}` translates in the template's locale, and fails the build on an unknown
+  key or a wrong, missing or unused argument; `placeholder('name')` writes
+  `{{ name }}` for a value only known at send time, and can be passed as an
+  ICU argument.
+- **The manifest, v0.1.0** — `dist/mail-manifest.json`: per e-mail, its variables and
+  the ones a URL attribute starts with (so they decide the scheme), its subject per locale (the
+  required `<email>.subject` message) and its files per locale — what
+  `createMailRenderer` from `@nxgt/mail/renderer` reads to send the built
+  `html` and `text` of a locale, every placeholder filled and escaped at send
+  time.
+- **Catalogues from a package, v0.1.0** — `i18n({ catalogues: [uiCatalogues] })`:
+  catalogues a package ships, as `@nxgt/mail-ui`'s shared messages, merged key
+  by key under your project's `locales/<locale>.json`, which overrides any of
+  them, and checked with it.
+- **Templates from a package, v0.1.0** — `i18n({ templates: [{ dir, emails }] })`:
+  folders of templates a package ships, as `@nxgt/mail-presets`' ready
+  e-mails, built with your project's own; `dir` is absolute, `emails` keeps
+  the ones you name, and a template of the same name in your project's
+  `emails/` replaces a package's.
+- **`createTranslator` outside templates, v0.1.0** — `createTranslator(catalogues,
+  getLanguage)` and `t(key, args, language?)`, shaped like `@nxgt/i18n`, for a
+  message an application formats itself.
+- **Typed templates and `t` in the editor, v0.1.0** — `t`, `locale` and
+  `placeholder` are known to Vue's template checker, so a template that calls
+  them type-checks. The plugin writes `.maizzle/nxgt-mail-i18n.d.ts` from the
+  catalogues each time the config loads, so an editor completes `t('…')` and
+  flags an unknown key or a wrong argument, and `vue-tsc` checks templates in
+  CI.
+- **The renderer typed by the build, v0.1.0** — after each `maizzle build`, the
+  plugin writes `generated/mail.ts`: `MailEmails`, each e-mail with the
+  variables it takes, a URL variable as a `string`. Committed, it lets
+  `createMailRenderer<MailEmails>` from `@nxgt/mail/renderer` refuse an
+  unknown e-mail, a missing or unknown variable, or a number for a URL at
+  compile time, without a build in CI. Rewritten only when it changes;
+  `rendererTypes` moves it, or `false` turns it off.
+- **A starter project, with v0.1.0** — the official Maizzle starter with
+  `defineMailConfig`, the i18n and the UI plugins wired in as the READMEs
+  say, built, rendered in `en` and `fr` and served in CI, so the snippets are
+  known to work: [`examples/starter`](https://github.com/softistx/nxgt-mail/tree/develop/examples/starter).
+  In the repository; its README says how to start your own from npm.