@k8ordo/i18n 0.1.0 → 1.1.0

package/docs/llms.txt

@@ -1,15 +1,19 @@
 # @k8ordo/i18n
 
-> The locale axis of an application, owned. `defineLocales(['ja', 'en'])`
-> declares the set once and derives membership, negotiation, the URL segment
+> The locale axis of an application, owned. `defineLocales({ ja: { timeZone,
+> dir }, en: … })` declares the set once — each locale with the time zone its
+> dates are shown in and its text direction — and derives membership,
+> negotiation, the URL segment
 > (`localize` / `delocalize`), the `[locale]` params schema in the shape
-> `@k8ordo/static` / `@k8ordo/server` run, and the current locale
+> `@k8ordo/framework` runs, and the current locale
 > (`getLocale()`). Each message is a function — `message({ ja, en })` — that
 > reads the locale where it is called: on the server the request the schema
 > accepted, in the browser the URL. The same call renders in a Server
 > Component and in a Client Component; there is no provider and no hook; a
 > bundler keeps only the messages a client module names. `Register` carries
-> the app's locale union so a message missing a locale does not compile.
+> the app's locale union so a message missing a locale does not compile;
+> `@k8ordo/framework` generates it from the `locales` export of
+> `src/i18n.ts`, and any other app writes it by hand.
 >
 > Like every k8ordo package it assumes React 19 and Server Components, uses
 > only what has reached Baseline newly available, and ships no polyfills or
@@ -21,24 +25,43 @@ When installed via npm, these docs live under `node_modules/@k8ordo/i18n/docs/`.
 
 - [Design Guide](GUIDE.md): what the package owns and does not (the locale
   segment, not the pathname; no message grammar; no loader), the locale set
-  and negotiation, messages as functions and `Register`, the Server
+  and negotiation, messages as functions and `Register` (generated under
+  `@k8ordo/framework`, hand-written elsewhere), formatting (`Intl`
+  drawn for the current locale, dates in its time zone), the Server
   Component boundary (a message is called before it is passed to a
   `'use client'` component), what reaches the browser, where the locale comes
-  from on each side, `/` and `<html lang>`, static path expansion, and
-  pairing with `@k8ordo/router` / `@k8ordo/ui` / `@k8ordo/form`.
+  from on each side, `/` (a `307` from a `guard.ts` in server mode,
+  an effect in static mode) and `<html lang>` / `dir`, static path
+  expansion, and pairing with `@k8ordo/router` / `@k8ordo/ui` /
+  `@k8ordo/form`.
 
 ## Entry point
 
-- `@k8ordo/i18n` — `defineLocales(all, { default? })` returns `{ all,
-  default, is, negotiate, localize, delocalize, paramsSchema, getLocale,
-  run }`; the first entry is the default unless told otherwise, every tag
+- `@k8ordo/i18n` — `defineLocales(definitions, { default? })` takes each
+  locale's `{ timeZone, dir }` by tag (both required; an unknown time zone
+  throws) and returns `{ all, definitions, default, is, negotiate, localize,
+  delocalize, paths, paramsSchema, getLocale, run, negotiateRequest, dateTimeFormat,
+  numberFormat, relativeTimeFormat, pluralRules, listFormat }`; the last five
+  return the `Intl` object for the current locale, cached per locale and
+  options, and `dateTimeFormat` always in that locale's `timeZone` (its
+  options type refuses one); `paths(patterns)` is the static build's `paths` option
+  with `/:locale` expanded to every locale; typed links come from
+  the router's `bindParams(() => ({ locale: locales.getLocale() }))`,
+  written by the application (imported from `@k8ordo/framework` in a
+  framework application); the first entry is the default unless told otherwise (and `default` is then typed as the whole union), every tag
   must be BCP 47, `negotiate(list)` tries each requested tag in order (exact,
   then language) before falling back to the default, `getLocale()` is the
   locale of the render in progress (not a hook), and `run(locale, fn)`
-  (server only) runs `fn` under a locale. `parseAcceptLanguage(header)` turns
-  an `Accept-Language` header into a preference list. `message(variants)`
+  (server only) runs `fn` under a locale. `negotiateRequest(request, {
+  cookie? })` chooses for a `Request` — the named cookie (the visitor's
+  earlier choice) first, then `Accept-Language` — through the same rule as
+  `negotiate`. `parseAcceptLanguage(header)` turns an `Accept-Language`
+  header into a preference list. `currentLocale()` returns the current locale as the
+  defined set resolves it — the one named, else the set's default — or `null`
+  where no set is defined in that environment; it is for a library rendering
+  inside an application it does not know (`@k8ordo/ui`'s built-in text). `message(variants)`
   declares one message — text in every locale, or a function of the same
   parameters in every locale — and returns `Message<Args>`, a function that
-  renders the current locale's text. Types: `Locales`, `LocaleOf`, `Message`,
+  renders the current locale's text. Types: `Locales`, `LocaleOf`, `LocaleDefinition`, `IntlFormats`, `LocaleDateTimeFormatOptions`, `Message`,
   `Variants`, `Register`, `RegisteredLocale`, `Delocalized`,
-  `LocaleParamsSchema`, `LocalesOptions`.
+  `LocaleParamsSchema`, `LocalesOptions`, `NegotiateRequestOptions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/i18n",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "The locale axis of an application, owned. One locale set derives the URL segment, negotiation, the params schema, the static paths, and the current locale on either side of the network; each message is a function that reads it, so a bundler keeps only what a page names.",
   "keywords": [
     "i18n",
@@ -40,15 +40,15 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@vitest/browser-playwright": "5.0.0",
-    "publint": "0.3.24",
+    "@vitest/browser-playwright": "5.0.5",
+    "publint": "0.3.25",
     "typescript": "7.0.2",
-    "vite": "8.2.2",
-    "vite-plus": "0.3.0",
-    "vitest": "5.0.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0",
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "typescript": ">=7.0.2"
+    "typescript": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "typescript": {