@k8ordo/i18n 0.1.0 → 1.0.0

package/docs/GUIDE.md

@@ -22,7 +22,8 @@ legacy fallbacks.
   locale segment in front of them and nothing after it.
 - **A message grammar.** No placeholder syntax, no ICU. A message with
   values is a function of those values: interpolation is a template
-  literal, plurals are `Intl.PluralRules`, dates and numbers are `Intl`.
+  literal, and plurals, dates and numbers are `Intl` — the set only draws
+  the `Intl` object for the current locale ([Formatting](#formatting)).
   TypeScript checks the arguments because they are arguments.
 - **Loading.** Messages are ordinary exports. Which ones reach the browser is
   decided by the bundler from what each client module imports, not by a
@@ -31,21 +32,17 @@ legacy fallbacks.
 ## The shape of it
 
 ```ts
-// i18n.ts — the one place the list is spelled
+// src/i18n.ts — the one place the list is spelled
 import { defineLocales } from '@k8ordo/i18n';
-import type { LocaleOf } from '@k8ordo/i18n';
-
-export const locales = defineLocales(['ja', 'en']);
 
-declare module '@k8ordo/i18n' {
-  interface Register {
-    locale: LocaleOf<typeof locales>;
-  }
-}
+export const locales = defineLocales({
+  ja: { timeZone: 'Asia/Tokyo', dir: 'ltr' },
+  en: { timeZone: 'UTC', dir: 'ltr' },
+});
 ```
 
 ```ts
-// messages/nav.ts — each message is one export
+// src/messages/nav.ts — each message is one export
 import { message } from '@k8ordo/i18n';
 
 export const home = message({ ja: 'ホーム', en: 'Home' });
@@ -56,51 +53,98 @@ export const greeting = message({
 ```
 
 ```tsx
-// routes/[locale]/layout.tsx — a Server Component
+// src/routes/[locale]/layout.tsx — a Server Component
 import { locales } from '../../i18n';
 
-export const paramsSchema = locales.paramsSchema;
+export const { paramsSchema } = locales;
 ```
 
-Spell it as that assignment: the framework finds a route's schema by
-reading the file for `export const paramsSchema`, so a destructuring export
-(`export const { paramsSchema } = locales`) would go unnoticed and `/fr/…`
-would render in the default locale. A linter's `prefer-destructuring`
-autofix rewrites it into exactly that, so disable the rule on the line.
-
 ```tsx
-// anywhere — a Server Component or a Client Component, the same line
-import * as nav from '../messages/nav';
+// src/components/header.tsx — a Server or a Client Component, the same lines
+import { greeting, home } from '../messages/nav';
 
-<h1>{nav.home()}</h1>
-<p>{nav.greeting(name)}</p>
+<h1>{home()}</h1>
+<p>{greeting(name)}</p>
+```
+
+That is all a working setup needs under `@k8ordo/framework`:
+`defineLocales`, `message`, and `paramsSchema` on the `[locale]` segment.
+
+`Register` is what holds every message to the set. Under the framework it is
+generated: when the application's `package.json` lists `@k8ordo/i18n` and
+`src/i18n.ts` exports the set as `locales`, the framework writes the
+augmentation into `.k8ordo/register.gen.ts` beside the route table,
+rewrites it as that file changes under `vite dev`, and the application
+writes none. It reads the export from the file's syntax, so the set has to
+be exported by that name from that file — `export const locales` or
+`export { locales } from './locales'`, not a type-only export and not
+`export *`. A `src/i18n.ts` without it gets a warning from the build and no
+`Register`.
+
+Anywhere else — Next.js, a framework of your own — write it once, beside the
+set:
+
+```ts
+// src/i18n.ts, outside @k8ordo/framework
+import type { LocaleOf } from '@k8ordo/i18n';
+
+declare module '@k8ordo/i18n' {
+  interface Register {
+    locale: LocaleOf<typeof locales>;
+  }
+}
 ```
 
-That is the whole surface: `defineLocales`, `Register`, `message`, and
-`paramsSchema` on the `[locale]` segment.
+A hand-written one left in a framework application still compiles, since
+both declare the same type, and can be deleted.
 
 ## The locale set
 
-`defineLocales(all, { default? })` returns the set. The first entry is the
-default unless told otherwise; every tag must be BCP 47 (checked with
-`Intl.Locale`); a repeated tag or a default outside the list throws at the
-definition, not later.
-
-| Member            | What it is                                                                        |
-| ----------------- | --------------------------------------------------------------------------------- |
-| `all`             | The tags, in order.                                                               |
-| `default`         | The tag used when nothing names one.                                              |
-| `is(value)`       | Membership as a type guard.                                                       |
-| `negotiate(…)`    | The best supported tag for a preference list.                                     |
-| `localize`        | `'/ui'` → `'/en/ui'`; `'/'` → `'/en'`.                                            |
-| `delocalize`      | `'/en/ui'` → `{ locale: 'en', pathname: '/ui' }`; `'/x'` → `{ locale: null, … }`. |
-| `paramsSchema`    | The `[locale]` segment's schema (Standard Schema; no schema library).             |
-| `getLocale()`     | The locale of the render in progress. Not a hook.                                 |
-| `run(locale, fn)` | Server only: runs `fn` with `locale` current.                                     |
-
-`LocaleOf<typeof locales>` is the tag union. `delocalize` says `null` for a
-first segment that is not a locale rather than guessing the default, so the
-root layout and the 404 page choose the fallback visibly.
+`defineLocales(definitions, { default? })` returns the set. `definitions` is
+keyed by locale tag, and each locale states its `timeZone` and its `dir`. The
+first entry is the default unless told otherwise (without `default`,
+`locales.default` is typed as the whole union); every tag must be BCP 47
+(checked with `Intl.Locale`); an empty set, a default outside the list, a time
+zone the runtime does not know, and a `dir` other than `ltr` / `rtl` throw at
+the definition, not later.
+
+| Member                | What it is                                                                        |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `all`                 | The tags, in order.                                                               |
+| `definitions`         | Each locale's `{ timeZone, dir }`, as given.                                      |
+| `default`             | The tag used when nothing names one.                                              |
+| `is(value)`           | Membership as a type guard.                                                       |
+| `negotiate(…)`        | The best supported tag for a preference list.                                     |
+| `negotiateRequest(…)` | The best supported tag for a `Request`: a cookie, then `Accept-Language`.         |
+| `localize`            | `'/ui'` → `'/en/ui'`; `'/'` → `'/en'`.                                            |
+| `delocalize`          | `'/en/ui'` → `{ locale: 'en', pathname: '/ui' }`; `'/x'` → `{ locale: null, … }`. |
+| `paths`               | The static build's `paths` option: `/:locale` expanded to every locale.           |
+| `paramsSchema`        | The `[locale]` segment's schema (Standard Schema; no schema library).             |
+| `getLocale()`         | The locale of the render in progress. Not a hook.                                 |
+| `run(locale, fn)`     | Server only: runs `fn` with `locale` current.                                     |
+| `dateTimeFormat`…     | `Intl` for the current locale ([Formatting](#formatting)).                        |
+
+`LocaleOf<typeof locales>` is the tag union and `LocaleDefinition` one
+locale's `{ timeZone, dir }`. `delocalize` says `null` for a first segment
+that is not a locale rather than guessing the default, so the root layout and
+the 404 page choose the fallback visibly.
+
+### `timeZone` and `dir`
+
+Neither can be derived from the runtime, so each locale declares both.
+
+`timeZone` is the IANA time zone the locale's dates are shown in. The
+runtime's own zone is the server's on the server and the visitor's in the
+browser, so a date left to it renders one way in the HTML and another while
+hydrating — a different day, near midnight. One zone per locale gives both
+sides the same value. Which zone is a product decision: a site about events in
+Tokyo may show its English pages in `Asia/Tokyo` too; a display that should
+follow each visitor's own zone belongs in a part that renders in the browser
+only.
+
+`dir` is the direction the locale's text runs in, for `<html dir>`.
+`Intl.Locale`'s `getTextInfo()` has not reached every browser, so it is
+declared rather than derived.
 
 ### Negotiation
 
@@ -112,12 +156,39 @@ skipped, because the list is user input.
 
 ```ts
 locales.negotiate(navigator.languages); // in the browser
-locales.negotiate(parseAcceptLanguage(request.headers.get('accept-language')));
+locales.negotiateRequest(request, { cookie: 'locale' }); // on a server
+```
+
+`negotiateRequest(request, { cookie? })` is the server's form. The cookie
+named by `cookie` comes first when the request carries it — the locale the
+visitor chose before, written where they switched language — then the
+`Accept-Language` header in its order of preference. Both go through
+`negotiate`, so a cookie still holding a locale the set no longer lists falls
+through to the header. The name is the application's: a language switcher
+that writes it and the server that reads it agree on one. Without `cookie`,
+only the header is read.
+
+```ts
+// the language switcher, in the browser
+await cookieStore.set({
+  name: 'locale',
+  value: next,
+  sameSite: 'lax',
+  expires: Date.now() + 400 * 24 * 60 * 60 * 1000,
+});
 ```
 
-`parseAcceptLanguage(header)` turns an `Accept-Language` header into that
-list: `q` weights decide the order, ties keep the header's order, `q=0` and
-`*` are dropped, and a missing header is an empty list.
+Left to the Cookie Store API's defaults, the switcher would write a session
+cookie under `SameSite=Strict`: the choice is gone once the browser closes,
+and the first request arriving from a link on another site goes without it,
+so that page is chosen by the header instead. `sameSite: 'lax'` and a far
+`expires` — 400 days is the longest a browser keeps a cookie — are what make
+the choice stick.
+
+`parseAcceptLanguage(header)` is the header half on its own: it turns an
+`Accept-Language` header into a preference list for `negotiate`: `q` weights decide the order (a `q` that is not a number is ignored),
+ties keep the header's order, a weight of 0 or less (an empty `q=` included)
+and `*` are dropped, and a missing header is an empty list.
 
 ## Messages
 
@@ -128,14 +199,16 @@ key does not compile" guarantee, per message, with no key list to maintain.
 
 A message is either text in every locale or a function in every locale;
 the two are not mixed within one message. For a function message the
-arguments are typed by the variant you annotate, and every other variant
-is held to the same parameters:
+argument types come from the variant you annotate, and every other variant
+is held to them. Declare every parameter in every variant, an unused one as
+`_count`: whether a variant that declares fewer compiles depends on which
+locale holds it, and with no annotation at all the arguments are `unknown`.
 
 ```ts
 export const items = message({
   ja: (count: number) => `${String(count)} 件`,
   en: (count) =>
-    `${String(count)} ${new Intl.PluralRules('en').select(count) === 'one' ? 'item' : 'items'}`,
+    `${String(count)} ${locales.pluralRules().select(count) === 'one' ? 'item' : 'items'}`,
 });
 ```
 
@@ -144,8 +217,13 @@ string` for a function. That type is what a component that takes a message
 as a prop should accept —
 
 ```tsx
+// src/components/nav-list.tsx
+import type { Message } from '@k8ordo/i18n';
+
+import { home } from '../messages/nav';
+
 type NavItem = { path: string; label: Message };
-const items: NavItem[] = [{ path: '/ui', label: nav.ui }];
+const items: NavItem[] = [{ path: '/', label: home }];
 …
 <a href={item.path}>{item.label()}</a>
 ```
@@ -155,34 +233,41 @@ component translating on another's behalf.
 
 ### Where messages live
 
-Anywhere. A file per area (`messages/nav.ts`, `messages/form.ts`) with a
-barrel that re-exports each as a namespace reads well at the call site:
-
-```ts
-// messages/index.ts
-export * as nav from './nav';
-export * as form from './form';
-```
+Anywhere. A file per area in `src/messages/` (`nav.ts`, `cart.ts`) reads
+well: a module imports the messages it uses by name, and renames one on import
+where two files export the same name:
 
 ```tsx
-import * as m from '../messages';
-<h1>{m.nav.home()}</h1>;
+// src/components/cart-summary.tsx
+import { title as cartTitle } from '../messages/cart';
+import { home } from '../messages/nav';
+
+<a href="/">{home()}</a>
+<h2>{cartTitle()}</h2>
 ```
 
-A message that belongs to one component can sit next to that component.
-Grouping related messages in an object (`export const button = { label:
-message(…), hint: message(…) }`) is fine too; the bundler then keeps the
-group together.
+A message that belongs to one component can be declared in that
+component's own module. Grouping related messages in an object (`export const
+button = { label: message(…), hint: message(…) }`) is fine too; the bundler
+then keeps the group together.
 
 ### Across the Server Component boundary
 
 A message is a function, and a function does not cross from a Server
 Component to a Client Component as a prop. Where a Server Component hands
 text to a `'use client'` component, it calls the message and passes the
-string — `<Dialog title={m.dialog.title()} />` — which is the rule the rest
-of k8ordo already follows: only input crosses the boundary. Nothing further
-down needs the string threaded through it, because any component, on either
-side, can import a message and call it itself.
+string:
+
+```tsx
+// src/components/settings.tsx — a Server Component
+import { title } from '../messages/dialog';
+
+<Dialog title={title()} />;
+```
+
+That is the rule the rest of k8ordo already follows: only input crosses the
+boundary. Nothing further down needs the string threaded through it, because
+any component, on either side, can import a message and call it itself.
 
 A component without a directive is shared: rendered by a Server Component it
 runs on the server, rendered by a Client Component it runs in the browser,
@@ -203,99 +288,295 @@ Keep the rule of thumb in mind: text that a Server Component renders costs
 the client nothing, whichever module declares it. A client component that
 needs text names it and pays for that message alone.
 
+## Formatting
+
+Plurals, dates, numbers and lists are `Intl` itself; there is no format
+syntax here. The set draws the `Intl` object for the current locale:
+
+| Member                         | Returns                                                         |
+| ------------------------------ | --------------------------------------------------------------- |
+| `dateTimeFormat(options?)`     | `Intl.DateTimeFormat` in the current locale and its `timeZone`. |
+| `numberFormat(options?)`       | `Intl.NumberFormat` in the current locale.                      |
+| `relativeTimeFormat(options?)` | `Intl.RelativeTimeFormat` in the current locale.                |
+| `pluralRules(options?)`        | `Intl.PluralRules` in the current locale.                       |
+| `listFormat(options?)`         | `Intl.ListFormat` in the current locale.                        |
+
+```tsx
+<time dateTime={date.toISOString()}>
+  {locales.dateTimeFormat({ dateStyle: 'medium' }).format(date)}
+</time>
+```
+
+What comes back is the `Intl` object, so `format`, `formatToParts`,
+`formatRange`, `select` and the options are `Intl`'s own. One is made per
+locale and options and returned again after that, so calling it where a
+component or a message renders costs a lookup. Options are keyed by their
+JSON: the same options in another order make a second object, never a
+different answer. None of them is a hook, and each reads the current locale
+the way a message does, so the same call works in a Server Component, a
+Client Component, and inside a message's function.
+
+`dateTimeFormat` writes a date only in the locale's `timeZone`. Its options
+type refuses a `timeZone`, and one forced through with `as` is overridden. The
+runtime's own zone is the server's on one side and the visitor's on the other,
+so a date left to it reads differently in the HTML and while hydrating; the
+locale's zone is the same on both. A display that should follow the visitor's
+own zone — a local clock, a time relative to now — differs between the two by
+nature: use `Intl` directly for it, in a part that renders in the browser
+only. An `Intl` API not listed here (`Intl.Collator`, `Intl.DisplayNames`)
+takes the tag from `locales.getLocale()`.
+
 ## Where the locale comes from
 
 **On the server**, `paramsSchema` accepting a locale makes it the current
-one for the rest of that request's render — the Server Components, the
+one for the render of the page that accepted it — the Server Components, the
 HTML they become, and the client components that run on the server for
-that HTML. Concurrent renders stay apart (`AsyncLocalStorage`). Outside a
-`[locale]` route — a test, code that runs before the route matched — use
+that HTML — and for nothing else. Concurrent renders stay apart
+(`AsyncLocalStorage`). An acceptance belongs to the pattern that answered,
+not to the request: when a schema further down the same stack refuses
+(`/en/blog/nope`, where the page's slug schema says no), the pattern does
+not answer and the locale goes with it. The 404 that answers instead runs
+the schemas above its `not-found.tsx` on its own, so it is in the locale its
+URL names — `/en/blog/nope` as `/en/nothing` is — and in the default under a
+segment the set refuses (`/fr/nothing`). Outside a `[locale]` route — a
+test, code that runs before the route matched — use
 `locales.run(locale, fn)`; and when nothing names a locale, messages render
 in the default.
 
+The server keeps the locale in `AsyncLocalStorage`, reached through
+`process.getBuiltinModule`. A runtime without them throws from
+`paramsSchema` and from `run`, rather than accepting a locale and rendering
+the page in the default.
+
 **In the browser**, the URL is the locale: the first segment of
 `location.pathname`, read when a message is called. Changing locale is a
 navigation to the same pathname under the other segment
 (`locales.localize(locales.delocalize(pathname).pathname, 'en')`), which
 re-renders the page; there is no state to keep in sync.
 
+Under Vite's `base` (`base: '/docs/'`), the segment read is the first one
+below it — `/docs/en/ui` is in `en` — as the route table's `[locale]` sits
+below it too. `localize` and `delocalize` work on pathnames in the table's
+terms, which is what `usePathname` returns; the one you navigate to gets the
+base back from the router's `withBase` (imported from `@k8ordo/framework` in
+a framework application).
+
 A first segment that is not one of the set's locales is no locale, and the
 default applies; before the set has been defined in that environment, a
 segment no message has text for is read the same way, so a 404 page never
 throws on `/fr/…`.
 
 `locales.getLocale()` reads the same source for code that needs the tag
-itself: `<html lang>`, a language switcher, `Intl` formatters.
+itself: `<html lang>`, a language switcher, an `Intl` API the set does not
+draw.
 
 ### The `/` page
 
-`/` is the one URL without a locale. Render nothing there and redirect from
-an effect:
+`/` is the one URL without a locale; all it does is send the visitor to one.
+
+In server mode a `guard.ts` answers it before anything renders. It
+chooses from the request — the cookie holding the locale the visitor chose
+before, then `Accept-Language` — and ends the request with a `307`:
+
+```ts
+// src/routes/(home)/guard.ts
+import { withBase } from '@k8ordo/framework';
+import type { Guard } from '@k8ordo/framework/server';
+
+import { locales } from '../../i18n';
+
+const guard: Guard<'/'> = ({ request }) => {
+  const locale = locales.negotiateRequest(request, { cookie: 'locale' });
+  return new Response(null, {
+    status: 307,
+    headers: { location: withBase(locales.localize('/', locale)) },
+  });
+};
+
+export default guard;
+```
+
+```
+src/routes/
+  layout.tsx
+  (home)/
+    page.tsx      declares /; never renders, since the guard always answers
+    guard.ts
+  [locale]/
+```
+
+The route group is what keeps the guard to `/`: a `guard.ts` runs before
+every URL below its directory, so one directly in `src/routes/` would send
+`/en/…` away as well. The page still has to exist — a guard runs before a
+URL a page declares, and without one `/` is a 404 — and it can return
+`null`. The status is `307`, not `308`, because the answer depends on who
+asks; `withBase` puts back the Vite `base` that `localize` leaves out. A
+visitor without JavaScript is redirected all the same, and so is a client
+navigation to `/`, whose payload request the guard answers too.
+
+Static mode refuses a `guard.ts` — a file has no request to guard — so
+there the page renders nothing and redirects from an effect: through the
+bound `navigateTo` where the router is `@k8ordo/router`'s (below), or
+`locales.localize` otherwise:
 
 ```tsx
 'use client';
 useEffect(() => {
-  navigation.navigate(
-    locales.localize('/', locales.negotiate(navigator.languages)),
+  navigateTo(
+    '/:locale',
+    { locale: locales.negotiate(navigator.languages) },
     { history: 'replace' },
   );
 }, []);
 ```
 
-Under `@k8ordo/server` the same decision can be made on the server with
-`parseAcceptLanguage` and a redirect.
-
-### `<html lang>`
+### `<html lang>` and `dir`
 
-The root layout sits above `[locale]` and receives `pathname`; the schema
-has already run for that request, so `locales.getLocale()` is right, and
+The root layout sits above `[locale]` and receives `pathname`. On a page the
+schema has already run for that page, so `locales.getLocale()` is right, and
 `locales.delocalize(pathname).locale ?? locales.default` says the same thing
-in terms of the URL alone.
+in terms of the URL alone. On a 404 they agree too: the schema runs over the
+catch-all's params, so `getLocale()` is the URL's locale where it names one
+and the default where it does not, as `delocalize` reads it.
+
+```tsx
+const locale = locales.delocalize(pathname).locale ?? locales.default;
+
+<html dir={locales.definitions[locale].dir} lang={locale}>
+```
 
 ## Static builds
 
-`@k8ordo/static` asks for the pathnames of every pattern with a parameter.
-Expand `[locale]` from the set — the list is spelled once:
+Static mode asks for the pathnames of every pattern with a parameter.
+The set answers for its own segment:
 
 ```ts
-framework({
-  paths: (patterns) =>
-    patterns.flatMap((pattern) =>
-      locales.all.map((locale) => pattern.replace(':locale', locale)),
-    ),
-});
+framework({ mode: 'static', paths: locales.paths });
+```
+
+`/:locale` in every pattern becomes one pathname per locale. A pattern with
+another parameter comes back still holding it (`/ja/blog/:slug`). Only a
+page with a `fallback.tsx` beside it takes such a pathname, as the location
+of its shell: one per locale, answering in the browser the slugs the build
+did not write. For any other route the build stops:
+
+```
+the "paths" option supplied pathnames that still hold a parameter, and only a page with a fallback.tsx beside it takes one: /ja/blog/:slug ([locale]/blog/[slug]/page.tsx has none)
 ```
 
+A site with a second parameter expands the rest in the same function:
+`paths: (patterns) => locales.paths(patterns).flatMap(expandSlug)`, where
+`expandSlug` keeps `/ja/blog/:slug` beside the slugs for a page that has a
+`fallback.tsx`.
+
+A shell runs the schemas of the layouts above it, never its page's: there
+is no value for the page's to parse. With the schema on
+`[locale]/layout.tsx`, as in [The shape of it](#the-shape-of-it), the
+locale is set for every page below it, shells included, and a shell's
+messages come out in the locale its location fills.
+
 Each path is rendered as its own request, so the schema names the locale
-for each and the messages come out in that locale. The `404.html` a static
-host serves for everything else is rendered once, under the build's
-sentinel locale; a client component on it reads the visitor's URL and
-re-renders in theirs after hydration.
+for each and the messages come out in that locale; the build renders several
+at once, and none lends its locale to another. The `404.html` a static host
+serves for everything else is rendered once, by the catch-all under the
+build's sentinel segment, which the schema refuses — so it is in the default
+locale whatever the build rendered before it, and cannot follow the
+visitor's. The browser does not hydrate it: it was rendered for another URL,
+and a message read while hydrating would disagree with the text written
+there. It renders the file afresh where the visitor is instead, so its client
+components come out in their locale once the script runs, and a visitor
+without JavaScript keeps the default.
 
 ## Alongside the rest of k8ordo
 
-- **`@k8ordo/router`**: `locales.localize` / `delocalize` are the only
-  things here that touch a pathname. A link component that prefixes the
-  current locale is `href(locales.localize(path, locales.getLocale()))`.
-- **`@k8ordo/ui`**: its own built-in strings take a dictionary prop on
-  `UIProvider`; pass `en` on `/en/…` from `locales.getLocale()`.
-- **`@k8ordo/form`**: constraint messages are messages — `message({ ja:
-(max: number) => …, en: … })` — called where the constraint is declared.
+- **`@k8ordo/router`**: the locale is a param of every pattern
+  (`/:locale/products/:id`), and the router's `bindParams` supplies it from
+  this package once, so links stay typed against the table and never spell
+  the locale:
+
+  ```ts
+  // src/lib/links.ts
+  import { bindParams } from '@k8ordo/framework'; // '@k8ordo/router' without the framework
+
+  export const { href, navigateTo } = bindParams(() => ({
+    locale: locales.getLocale(),
+  }));
+  ```
+
+  `href('/:locale/products/:id', { id })` then reads the current locale;
+  `navigateTo('/:locale', { locale: 'en' }, { history: 'replace' })`
+  overrides it. Neither package imports the other: the line above is the
+  application's. `localize` / `delocalize` remain for a pathname in hand —
+  the language switcher, which takes the page it is on to another locale.
+
+- **`@k8ordo/ui`**: its built-in strings read `currentLocale()` from this
+  package — the locale messages render in, or `null` (English there) when no
+  set is defined in that environment — so they follow the app's locale with
+  nothing passed. `ja` and `en` ship with it; another locale is registered
+  next to the set with `registerMessages` from `@k8ordo/ui/i18n`. The module
+  that defines the set has to be loaded in the browser too, or the components
+  there speak English.
+- **`@k8ordo/form`**: constraint messages are messages, and a message called
+  where the constraint is declared keeps the text of whatever locale was
+  current then. Hand zod the message instead, so it is called when zod
+  reports the issue — and a `defineForm` rule the same way, which calls it
+  when the rule is reported:
+
+  ```ts
+  // src/lib/talk-form.ts
+  import {
+    reasonRequired,
+    titleRequired,
+    titleTooLong,
+  } from '../messages/talk';
+
+  export const talkForm = defineForm(
+    z.object({
+      title: z
+        .string()
+        .min(1, { error: titleRequired })
+        .max(120, { error: () => titleTooLong(120) }),
+      status: z.enum(['draft', 'rejected']),
+      reason: z.string(),
+    }),
+    [requiredWhen('reason', 'status', 'rejected', reasonRequired)],
+  );
+  ```
+
+  The definition stays at module scope; what has to happen per request is
+  calling it. Call `formFields` during the page's render, not at module
+  scope. A Server Action posted from a `[locale]` page runs in that page's
+  locale in server mode — the framework runs the page's params
+  schemas for the action's request too — so `parseForm` in it needs nothing
+  more. Anywhere else — an action run outside the framework, a job — call it
+  inside `locales.run`.
 
 ## What it guarantees
 
 - A locale outside the list never reaches a page: the schema refuses it.
-- A message missing a locale does not compile once `Register` is merged.
+- A message missing a locale does not compile once `Register` is merged —
+  by `@k8ordo/framework`'s generated files, or by hand.
   From JavaScript, or through `as`, it throws where it is read, naming the
   locale and the variants present — never `undefined`.
 - Arguments to a function message are typed by the function.
-- No render is ever in a locale the URL does not spell (browser) or the
-  request did not accept (server).
+- A page under `[locale]` never renders in a locale its URL does not spell:
+  on the server its schema accepted that locale, and in the browser the URL
+  is what is read. A locale accepted for one page reaches no other page, no
+  404, and nothing rendered after it; a 404 is in the locale its own URL
+  names, or the default.
+- On a server runtime without `AsyncLocalStorage`, accepting a locale throws
+  rather than rendering in the default.
+- A date written through `dateTimeFormat` is in its locale's time zone on the
+  server and in every browser; the type refuses any other.
 
 ## Testing
 
-Under Node, `locales.run('en', () => nav.home())` renders in `en`; without
-it, the default. The `paramsSchema` sets the locale for the rest of its
-scope too, so wrap a test that validates in `run` to keep tests apart. In a
-browser environment, `history.replaceState(null, '', '/en/…')` is the
-locale.
+Under Node, `locales.run('en', () => home())` renders in `en`; without
+it, the default. Called directly, `paramsSchema` sets the locale for the
+rest of the caller's async context — the framework gives each pattern's
+schemas a context of their own, a test does not — so wrap a test that
+validates in `run` to keep tests apart. A test that calls `defineLocales`
+itself replaces the set messages read: the last one defined wins. In a
+browser environment, `history.replaceState(null, '', '/en/…')` is the locale
+and `run` throws; an environment that defines `document`, such as jsdom or
+happy-dom, counts as one.