@zerotal/arch 1.7.0 → 1.7.3

package/docs/i18n.md

@@ -1,13 +1,23 @@
 ---
 title: Internationalization
-description: Resolve each visitor's locale automatically, then translate keys with interpolation, pluralization, and fallback.
+description: Resolve each visitor's locale automatically, then translate English source strings with interpolation, pluralization, and fallback.
 ---
 
 # Internationalization
 
 Request-scoped localization: resolve each visitor's locale automatically, then
-translate keys with interpolation, pluralization, and fallback — without threading
-the locale through every function call.
+translate with interpolation, pluralization, and fallback — without threading the
+locale through every function call.
+
+The string you pass to `__()` is the English sentence, not a name for it:
+
+```typescript
+__("Email"); // not __("auth.email")
+```
+
+English is the source language, so the source text _is_ the key. That one
+decision removes the `en.json` file, the naming argument, and the class of bug
+where a screen ships reading `auth.email` because somebody mistyped a key.
 
 ## Getting Started
 
@@ -37,7 +47,7 @@ Registering the provider switches on the following:
 - `onRegister` — binds the translation service as the lazy `i18n` singleton (a
   `Translator` loaded from your catalogs).
 - `onBooting` — configures and registers `LocaleMiddleware` via `app.useOnce()`,
-  so every request resolves a locale and gains `ctx.locale` + `ctx.t()`.
+  so every request resolves a locale and gains `ctx.locale` + `ctx.__()`.
 
 ## Configuration
 
@@ -52,7 +62,7 @@ import { env } from "zerotal";
 export default I18nConfig({
   defaultLocale: env("APP_LOCALE", "en"),
   fallbackLocale: env("APP_FALLBACK_LOCALE", "en"),
-  supportedLocales: ["en"],
+  supportedLocales: ["en", "fr"],
   resolvers: ["query", "cookie", "accept-header"], // tried in order
   queryKey: "lang", // ?lang=fr
   cookieKey: "locale", // locale=fr cookie
@@ -75,68 +85,201 @@ export default I18nConfig({
 > `satisfies I18nConfigShape` for the same type-checking — but then every field is
 > required, since the helper is what supplies the defaults above.
 
-Catalog files live under `loadPath`, one JSON file per locale:
+List your source language in `supportedLocales`, but write no catalog for it:
 
-```
+```text
 resources/lang/
-├── en.json
 ├── fr.json
 └── es.json
 ```
 
+There is no `en.json`, and adding one would only map 200 English strings to
+themselves. An unmatched lookup returns the key, and the key is the English.
+
 ## Basic usage
 
 `LocaleMiddleware` resolves the locale for every request and exposes `ctx.locale`
-and `ctx.t()` on the request context:
+and `ctx.__()` on the request context:
 
 ```typescript
 // in a controller
 async show(ctx: HttpContext) {
-  ctx.t("welcome.greeting", { name: "Alice" });       // active locale
-  ctx.t("welcome.greeting", { name: "Alice" }, "fr");  // explicit locale
+  ctx.__("Hello, {name}!", { name: "Alice" });       // active locale
+  ctx.__("Hello, {name}!", { name: "Alice" }, "fr");  // explicit locale
   return ctx.json({ locale: ctx.locale });
 }
 ```
 
-Outside a controller — in a service, job, or view — use the `Lang` facade or the
-global `t()` helper. Both read the active request locale from `I18nContext`, so no
-locale needs to be passed around:
+Outside a controller — in a service, job, or view — call `__()`. It reads the
+active request locale from `I18nContext`, so no locale is passed around, and
+**it needs no import**: `I18nProvider` puts it on `globalThis` when it boots.
+
+```typescript
+// anywhere in the request's async tree — no import line
+__("Sign in");
+```
+
+It is installed at boot rather than at module load because that is the moment
+there is a translator behind it. A global resolving against an unbound container
+would answer every string with itself, which reads as "not translated yet"
+rather than as "i18n is not installed".
+
+The declaration that types it ships with the package, so an editor completes it
+and a wrong argument still fails the build. `__` also remains a named export,
+which is what a library — unable to assume an application has booted — should
+import:
+
+```typescript
+import { Lang, __ } from "@zerotal/i18n";
+
+Lang.translate("Sign in"); // the facade, when you want the instance
+```
+
+## Translating in the browser
+
+A React interface cannot reach the server's `Translator`, so the active locale's
+catalog travels to it as a shared Inertia prop:
+
+```typescript
+// bootstrap/app.ts
+import { share } from "@zerotal/inertia";
+import fr from "../resources/lang/fr.json";
+
+const CATALOGS: Record<string, Record<string, unknown>> = { fr };
+
+share("locale", () => activeLocale());
+// `{}` for the source language: every string resolves to itself.
+share("messages", () => CATALOGS[activeLocale()] ?? {});
+```
+
+Client-side, keep the catalog in module state and hand it to the translator from
+`resolve()`. Inertia calls `resolve` with the incoming page **before** it swaps
+the component in, which is what makes the first render after a language change
+come out in the new language:
+
+```tsx
+// resources/js/app.tsx
+createInertiaApp({
+  resolve: async (name, incoming) => {
+    syncTranslations(incoming);
+    return (await pages[name]!()).default;
+  },
+  // …
+});
+```
+
+Have that module install the global too — the browser has no provider to boot,
+so it does it itself, and importing the module for `syncTranslations` is what
+guarantees the assignment has run:
 
 ```typescript
-// anywhere in the request's async tree
-import { Lang, t } from "@zerotal/i18n";
+// resources/js/lib/i18n.ts
+(globalThis as { __?: typeof __ }).__ = __;
+```
+
+A component then calls it with no import and no hook:
 
-Lang.translate("auth.login.title");
-t("dashboard.welcome");
+```tsx
+// resources/js/pages/login.tsx
+<TextField label={__("Email")} type="email" />
 ```
 
-## Keys, interpolation, pluralization
+> **Note** — declare no second ambient `__` for the browser. An app is one
+> TypeScript program, so `@zerotal/i18n`'s declaration already covers these call
+> sites; a second `var __` is a duplicate identifier, not an override.
+
+> **Note** — do not sync from `router.on("navigate")`. That event fires _after_
+> the component swap, so the first render of a new page still carries the
+> previous locale's catalog — visible as one flash of the old language every time
+> someone switches.
+
+Because it is a plain function, `__()` also works in the places a hook cannot go:
+module-level option arrays, `Page.layout` assignments, and helpers that never
+receive props. Those are exactly the spots that tend to ship untranslated.
+
+> **Note** — module state is per-tab in a browser, which is what makes this safe.
+> Under Inertia SSR the same module is shared by concurrent requests, so an app
+> that adds SSR must move the catalog into per-render context instead.
+
+## Writing a catalog
 
-Catalogs may use nested objects or flat dotted keys — both resolve:
+A catalog maps the English string to its translation. It is flat, because the
+keys are sentences rather than paths:
 
 ```json
-// resources/lang/en.json
+// resources/lang/fr.json
 {
-  "welcome": { "greeting": "Hello, {name}!" },
-  "validation.required": "The :field field is required.",
-  "apples": "no apples | one apple | {count} apples"
+  "Sign in": "Se connecter",
+  "Forgot your password?": "Mot de passe oublié ?",
+  "Hello, {name}!": "Bonjour, {name} !",
+  "The {field} field is required.": "Le champ {field} est obligatoire.",
+  "no apples|one apple|{count} apples": "aucune pomme|une pomme|{count} pommes"
 }
 ```
 
+A key is looked up flat first, then as a dot-path. Flat has to win, because an
+English sentence contains dots that are punctuation: `"Signed out."` must not be
+split into a `Signed out` → `` lookup. Nested catalogs still resolve, so an
+existing app can move over one screen at a time.
+
+## Interpolation, pluralization, fallback
+
 - **Interpolation** — `{name}` and `:name` are both replaced from the
   replacements object.
 - **Pluralization** — pipe-separated segments are chosen by `count`: two segments
   are `singular | plural` (`count === 1` → first); three or more are
   `zero | one | many` (`0` → first, `1` → second, otherwise last).
-- **Fallback** — a key missing in the active locale is looked up in
-  `fallbackLocale`; if still missing, the key itself is returned, so gaps are
-  visible and never throw.
+- **Fallback** — a string missing in the active locale is looked up in
+  `fallbackLocale`; if it is still missing, the key is used as the message — and
+  is then interpolated and pluralized like any other hit.
+
+That last point is what lets the source language skip having a catalog:
 
 ```typescript
-t("apples", { count: 0 }); // "no apples"
-t("apples", { count: 5 }); // "5 apples"
+__("Hello, {name}!", { name: "Alice" }); // "Hello, Alice!" — with no en.json
+__("{count} apple|{count} apples", { count: 5 }); // "5 apples"
 ```
 
+A string nobody has translated yet renders as the English that was typed, on the
+day it was typed, in every locale. Untranslated is not the same as broken.
+
+## Two English strings, one translation
+
+Identical English collapses to one catalog entry. Usually that is the point —
+"Sign in" on the button and "Sign in" in the nav want the same translation, and
+under dotted keys they were two entries that could drift apart.
+
+Where it bites is a word doing two jobs. "Unassigned" describing a count of
+issues and "Unassigned" describing a missing person are one key here, and a
+language that renders them differently cannot express both. The fix is to make
+the English say what it means:
+
+```typescript
+__("Unassigned issues"); // the dashboard count
+__("Unassigned"); // the person who is not there
+```
+
+If two uses of a word need two translations, they usually needed two different
+English strings as well — the ambiguity was there before the translator found it.
+
+## Strings that are not sentences
+
+Enum values and column names cannot be passed to `__()` — `in_progress` is not
+English. Map them to English first, then translate the result:
+
+```typescript
+const STATUS_LABEL: Record<string, string> = {
+  backlog: "Backlog",
+  in_progress: "In progress",
+  done: "Done",
+};
+
+__(STATUS_LABEL[issue.status] ?? issue.status);
+```
+
+The `?? issue.status` matters: a status added server-side renders as its raw
+name rather than vanishing from the page.
+
 ## Locale resolution
 
 `resolveLocale(request, config)` tries each configured resolver in order and only
@@ -160,7 +303,7 @@ returns a value listed in `supportedLocales` (otherwise `defaultLocale`):
 ## Overriding the locale
 
 The locale is resolved once, when `LocaleMiddleware` runs, and is then fixed for
-the rest of the request — so `ctx.locale` and `ctx.t()` always reflect what the
+the rest of the request — so `ctx.locale` and `ctx.__()` always reflect what the
 resolvers chose. There is no `setLocale()`. To change the language, do one of two
 things.
 
@@ -182,136 +325,86 @@ async setLocale(ctx: HttpContext) {
 ```
 
 **Override within the current request** — e.g. to honour a locale stored on the
-user — by running code inside `I18nContext.run()`. The `Lang` facade and `t()`
+user — by running code inside `I18nContext.run()`. The `Lang` facade and `__()`
 helper use the supplied locale for the duration of the callback:
 
 ```typescript
 // in a controller
-import { I18nContext, t } from "@zerotal/i18n";
+import { I18nContext, __ } from "@zerotal/i18n";
 
 async show(ctx: HttpContext) {
   const user = ctx.user as { name?: string; locale?: string } | undefined;
   const locale = user?.locale ?? ctx.locale;
 
   const greeting = I18nContext.run(locale, () =>
-    t("welcome.greeting", { name: user?.name }),
+    __("Hello, {name}!", { name: user?.name }),
   );
 
   return ctx.view(DashboardPage({ greeting }));
 }
 ```
 
-> **Note** — `I18nContext.run()` only affects the `Lang` facade and `t()` inside
-> its callback. `ctx.t()` and `ctx.locale` were bound by the middleware and stay on
-> the request's resolved locale. For a persistent change, set the cookie above.
+> **Note** — `I18nContext.run()` only affects the `Lang` facade and `__()` inside
+> its callback. `ctx.__()` and `ctx.locale` were bound by the middleware and stay
+> on the request's resolved locale. For a persistent change, set the cookie above.
 
-## Catalog structure
+## Rendering in someone else's language
 
-Catalogs can be flat or deeply nested — both styles resolve with the same dot-path:
-
-```json
-// resources/lang/en.json
-{
-  "auth": {
-    "login": {
-      "title": "Sign in",
-      "submit": "Sign in to your account",
-      "forgot": "Forgot your password?"
-    },
-    "logout": "Sign out"
-  },
-  "validation": {
-    "required": "The :field field is required.",
-    "email": "The :field must be a valid email address.",
-    "min": "The :field must be at least :min characters."
-  },
-  "posts": {
-    "count": "no posts | one post | :count posts",
-    "created": "Post created on :date"
-  }
-}
-```
+A queue job has no request, so there is no ambient locale to read — and the one
+belonging to whoever triggered the job was never the right answer anyway. Mail
+should arrive in the language of the person opening it, so pass the locale
+explicitly as the third argument:
 
 ```typescript
-ctx.t("auth.login.title"); // "Sign in"
-ctx.t("auth.logout"); // "Sign out"
-ctx.t("validation.required", { field: "name" }); // "The name field is required."
-ctx.t("posts.count", { count: 0 }); // "no posts"
-ctx.t("posts.count", { count: 1 }); // "one post"
-ctx.t("posts.count", { count: 42 }); // "42 posts"
+// app/notifications/IssueAssignedNotification.ts
+toMail(notifiable: Notifiable): MailMessage {
+  const recipient = notifiable as { name?: string; locale?: string | null };
+  const locale = recipient.locale ?? undefined;
+
+  return new MailMessage()
+    .subject(__("{actor} assigned you an issue", { actor: this.assignedBy }, locale))
+    .greeting(__("Hello {name},", { name: recipient.name ?? "" }, locale));
+}
 ```
 
 ## Translating validation messages
 
-A common pattern is to keep your localized form-error strings under a `validation`
-namespace in each catalog, then translate them with `t()` where you build the
+Write the message as you want to read it, and translate it where you build the
 error response:
 
 ```json
 // resources/lang/fr.json
 {
-  "validation": {
-    "required": "Le champ :field est obligatoire.",
-    "email": "Le champ :field doit être une adresse e-mail valide.",
-    "min": "Le champ :field doit contenir au moins :min caractères.",
-    "unique": "Cette valeur est déjà prise."
-  }
+  "The {field} field is required.": "Le champ {field} est obligatoire.",
+  "The {field} must be a valid email address.": "Le champ {field} doit être une adresse e-mail valide."
 }
 ```
 
 ```typescript
 // in a controller — translate a validation message yourself
-t("validation.required", { field: "email" }); // active locale
-```
-
-> **Note** — The `validation` namespace is just a convention for organizing keys;
-> the i18n package translates any key you pass to `t()`. See
-> [Validator](/docs/validator) for how the validator itself reports errors.
-
-## Multiple supported locales
-
-List every locale your app ships in `supportedLocales`. The resolver only returns a
-locale from this list — unsupported values fall back to `defaultLocale`:
-
-```typescript
-// config/i18n.ts
-export default I18nConfig({
-  defaultLocale: "en",
-  fallbackLocale: "en",
-  supportedLocales: ["en", "fr", "es", "zu", "af"],
-  resolvers: ["cookie", "accept-header"],
-});
+__("The {field} field is required.", { field: "email" });
 ```
 
-Add a catalog file for each:
-
-```
-resources/lang/
-  en.json
-  fr.json
-  es.json
-  zu.json   ← isiZulu
-  af.json   ← Afrikaans
-```
+See [Validator](/docs/validator) for how the validator itself reports errors.
 
-## Using t in JSX views
+## Using __ in JSX views
 
 ```tsx
 // app/views/PostCard.tsx
-import { t } from "@zerotal/i18n";
+import { __ } from "@zerotal/i18n";
 
 export function PostCard({ post }: { post: Post }) {
   return (
     <div>
       <h2>{post.title}</h2>
-      <p>{t("posts.count", { count: post.commentCount })}</p>
-      <a href={`/posts/${post.slug}`}>{t("posts.readMore")}</a>
+      <p>{__("{count} comment|{count} comments", { count: post.commentCount })}</p>
+      <a href={`/posts/${post.slug}`}>{__("Read more")}</a>
     </div>
   );
 }
 ```
 
-`t()` reads the active locale from `I18nContext` (async local storage) — no props
+`__()` reads the active locale from `I18nContext` (async local storage) — no props
 threading needed.
 
 ## Errors
@@ -322,46 +415,56 @@ thrown when a catalog file exists but contains malformed JSON. Both extend
 
 ## Testing
 
-Set your suite up once as described in [Testing](/docs/testing). Translation
-tests are cheap, and the two worth writing are the ones that catch a missing
-string before a user does.
+Set your suite up once as described in [Testing](/docs/testing). Two tests earn
+their place.
 
-**Assert the resolved string, not the key.** A test that checks `t("cart.empty")
-=== "cart.empty"` passes when the catalogue is missing entirely:
+**Assert the translated string.** Asserting the English proves nothing, since the
+English is what a completely missing catalog returns:
 
 ```typescript
 // tests/i18n/catalogues.test.ts
 import { test, expect } from "bun:test";
-import { t } from "@zerotal/i18n";
+import { __ } from "@zerotal/i18n";
 
 test("renders the French cart message", () => {
-  expect(t("cart.empty", {}, "fr")).toBe("Votre panier est vide");
+  expect(__("Your cart is empty", {}, "fr")).toBe("Votre panier est vide");
 });
 
 test("substitutes replacements", () => {
-  expect(t("cart.count", { n: 3 }, "fr")).toContain("3");
+  expect(__("{n} items", { n: 3 }, "fr")).toContain("3");
 });
 ```
 
-**Test that every locale has every key.** This is the test that earns its place —
-it fails the moment someone adds an English string and forgets the translation,
-which is otherwise found in production by a French speaker:
+**Report which strings a locale is missing.** There is no `en.json` to compare
+against, so the source is the source: scan it for the strings actually passed to
+`__()` and check each locale covers them. Unlike a key-parity test, this also
+catches catalog entries left behind by deleted screens:
 
 ```typescript
-// tests/i18n/parity.test.ts
+// tests/i18n/coverage.test.ts
 import { test, expect } from "bun:test";
 import { loadCatalogs } from "@zerotal/i18n";
 
-test("every locale defines the same keys as English", async () => {
-  const catalogs = await loadCatalogs("./resources/lang");
-  const english = Object.keys(catalogs.en).sort();
+test("reports the strings each locale still needs", async () => {
+  const used = new Set<string>();
+  const glob = new Bun.Glob("**/*.{ts,tsx}");
+  for (const file of glob.scanSync({ cwd: "./app", onlyFiles: true })) {
+    const source = await Bun.file(`./app/${file}`).text();
+    for (const [, text] of source.matchAll(/\b__\(\s*"([^"\\]+)"/g)) used.add(text!);
+  }
 
+  const catalogs = await loadCatalogs("./resources/lang");
   for (const [locale, messages] of Object.entries(catalogs)) {
-    expect(Object.keys(messages).sort(), `locale: ${locale}`).toEqual(english);
+    const missing = [...used].filter((text) => !(text in messages));
+    expect(missing, `locale: ${locale}`).toEqual([]);
   }
 });
 ```
 
+> **Note** — start this as a report rather than an assertion if you are adding a
+> language to an existing app: a failing list of 200 strings on day one gets the
+> test deleted, not the strings translated.
+
 **Locale resolution is a separate concern** from translation, and fails
 separately — a correct catalogue served under the wrong locale looks like a
 missing translation:
@@ -381,34 +484,34 @@ res.assertSee("Votre panier est vide");
 
 **Request context** — added by `LocaleMiddleware`:
 
-| Member       | Signature                                                              | Description                           |
-| ------------ | ---------------------------------------------------------------------- | ------------------------------------- |
-| `ctx.locale` | `string`                                                               | The locale resolved for this request. |
-| `ctx.t()`    | `t(key: string, replacements?: Replacements, locale?: string): string` | Translate using the request locale.   |
+| Member       | Signature                                                                | Description                           |
+| ------------ | ------------------------------------------------------------------------ | ------------------------------------- |
+| `ctx.locale` | `string`                                                                 | The locale resolved for this request. |
+| `ctx.__()`   | `__(text: string, replacements?: Replacements, locale?: string): string` | Translate using the request locale.   |
 
 **`Lang` facade** — the `i18n` binding (a `Translator`):
 
-| Method            | Signature                                                             | Description                                              |
-| ----------------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
-| `Lang.translate`  | `(key: string, replacements?: Replacements, locale?: string): string` | Translate a key; a missing key returns the key itself.   |
-| `Lang.has`        | `(key: string, locale?: string): boolean`                             | Whether the key exists in the active or fallback locale. |
-| `Lang.locales`    | `string[]`                                                            | Loaded locales.                                          |
-| `Lang.addCatalog` | `(locale: string, messages: Messages): void`                          | Merge messages into a locale (tooling / tests).          |
+| Method            | Signature                                                              | Description                                                 |
+| ----------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `Lang.translate`  | `(text: string, replacements?: Replacements, locale?: string): string` | Translate; an untranslated string returns itself.           |
+| `Lang.has`        | `(text: string, locale?: string): boolean`                             | Whether the string exists in the active or fallback locale. |
+| `Lang.locales`    | `string[]`                                                             | Loaded locales.                                             |
+| `Lang.addCatalog` | `(locale: string, messages: Messages): void`                           | Merge messages into a locale (tooling / tests).             |
 
 **Helpers & context** — importable from `@zerotal/i18n`:
 
-| Export                | Signature                                                             | Description                                      |
-| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------ |
-| `t`                   | `(key: string, replacements?: Replacements, locale?: string): string` | Global translate; reads the active locale.       |
-| `I18nContext.run`     | `<T>(locale: string, cb: () => T): T`                                 | Run `cb` with `locale` active.                   |
-| `I18nContext.current` | `(): string \| undefined`                                             | Active locale, or `undefined` outside a request. |
-| `resolveLocale`       | `(request: Request, config: I18nConfigShape): string`                 | Resolve a request's locale per config.           |
+| Export                | Signature                                                              | Description                                      |
+| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
+| `__`                  | `(text: string, replacements?: Replacements, locale?: string): string` | Global translate; reads the active locale.       |
+| `I18nContext.run`     | `<T>(locale: string, cb: () => T): T`                                  | Run `cb` with `locale` active.                   |
+| `I18nContext.current` | `(): string \| undefined`                                              | Active locale, or `undefined` outside a request. |
+| `resolveLocale`       | `(request: Request, config: I18nConfigShape): string`                  | Resolve a request's locale per config.           |
 
 See [Configuration](#configuration) for the `config/i18n.ts` fields.
 
 ## Next steps
 
-- [Validator](/docs/validator) — pair form validation with a translated `validation` namespace.
+- [Validator](/docs/validator) — pair form validation with translated messages.
 - [Middleware](/docs/middleware) — how `LocaleMiddleware` resolves the request locale.
 - [Cookies](/docs/cookies) — persist a visitor's locale choice.
-- [View](/docs/view) — use `t()` inside server-rendered JSX.
+- [View](/docs/view) — use `__()` inside server-rendered JSX.

package/docs/notifications.md

@@ -530,7 +530,7 @@ The broadcast channel works like this:
 
   ```ts
   // in your frontend
-  Echo.private(`notifications.${userId}`).listen("notification", (n) => {
+  Socket.private(`notifications.${userId}`).listen("notification", (n) => {
     console.log(n.type, n);
   });
   ```

package/docs/queue.md

@@ -326,11 +326,19 @@ The standard way to process jobs in production is a long-running worker process:
 
 ```bash
 # in your project root
-bun zt queue:work                  # process the 'default' queue
-bun zt queue:work --queue=emails   # process a specific queue
-bun zt queue:work --once           # process one job, then exit
+bun zt queue:work                        # process every queue in config.queues
+bun zt queue:work --queue=emails         # process one queue
+bun zt queue:work --queue=emails,reports # process several, in priority order
+bun zt queue:work --once                 # process one job, then exit
 ```
 
+With no `--queue`, the worker drains every queue listed in `queue.queues` — the
+same key the in-process pool reads — falling back to `["default"]`. That default
+matters more than it looks: a job may pin its own queue, and
+`SendNotificationJob` sets `"notifications"`. List the queues your jobs actually
+use, or the ones you leave out are queued by a documented call and drained by
+nobody.
+
 The worker polls continuously, retries failed jobs up to `maxAttempts`, and moves
 permanently-failed jobs to the `zerotal_failed_jobs` table.