@k8ordo/i18n 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Koki Sakano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @k8ordo/i18n
+
+The locale axis of an application, owned. One locale set declares which
+locales exist and which is the default, and derives the URL segment, the
+params schema of the `[locale]` route, negotiation from `navigator.languages`
+or `Accept-Language`, and the static build's path list. Each message is a
+function — `message({ ja: 'ホーム', en: 'Home' })` — that reads the locale
+where it is called: the request on the server, the URL in the browser. So the
+same line renders in a Server Component and in a Client Component, there is
+no provider and no hook, and a bundler keeps only the messages a client module
+names. No message grammar: interpolation is a template literal and plurals are
+`Intl.PluralRules`.
+
+Like every [k8ordo](https://ordo.k8o.me) package it assumes React 19 and Server
+Components, uses only what has reached Baseline newly available, and ships no
+polyfills or legacy fallbacks.
+
+- **Documentation**: https://ordo.k8o.me/i18n
+- **Design guide**: [docs/GUIDE.md](docs/GUIDE.md) — shipped inside this package
+
+## Installation
+
+```bash
+npm install @k8ordo/i18n
+# or
+pnpm add @k8ordo/i18n
+```
+
+## Peer Dependencies
+
+| Package      | Version | Needed for                    |
+| ------------ | ------- | ----------------------------- |
+| `typescript` | ≥7.0.2  | the shipped type declarations |
+
+No React import and no schema library: a message is a plain function, and a
+locale set is a list that checks membership itself. `locales.paramsSchema`
+speaks Standard Schema, which is what `@k8ordo/static` and `@k8ordo/server`
+run for a route's params. On a server the current locale rides on
+`AsyncLocalStorage` (Node ≥ 24).
+
+## Quick Start
+
+The locale set in its own module, registered once so every message is held
+to it:
+
+```ts
+// i18n.ts
+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>;
+  }
+}
+```
+
+Each message is one export, with its text in every locale:
+
+```ts
+// messages/nav.ts
+import { message } from '@k8ordo/i18n';
+
+export const home = message({ ja: 'ホーム', en: 'Home' });
+export const greeting = message({
+  ja: (name: string) => `こんにちは、${name}さん`,
+  en: (name) => `Hello, ${name}`, // the arguments are typed by ja
+});
+```
+
+The `[locale]` route's layout declares the schema; accepting a locale makes it
+the locale of that render:
+
+```tsx
+// routes/[locale]/layout.tsx
+import { locales } from '../../i18n';
+
+export const paramsSchema = locales.paramsSchema; // /fr/… is a 404
+```
+
+And a message is called the same way everywhere:
+
+```tsx
+// routes/[locale]/page.tsx — a Server Component
+import * as nav from '../../messages/nav';
+
+export default function Page() {
+  return <h1>{nav.home()}</h1>;
+}
+```
+
+```tsx
+// components/toolbar.tsx — a Client Component, the same line
+'use client';
+import * as nav from '../messages/nav';
+
+export function Toolbar() {
+  return <button>{nav.greeting('k8o')}</button>;
+}
+```
+
+Where a Server Component hands text to a Client Component as a prop, it calls
+the message and passes the string: a function does not cross that boundary.
+
+`/` negotiates and redirects; `<html lang>` and a language switcher read
+`locales.getLocale()`; a static build expands `[locale]` from `locales.all`.
+
+## AI Agent Documentation
+
+This package ships its documentation so an AI coding assistant reads the exact
+installed version:
+
+- `node_modules/@k8ordo/i18n/docs/GUIDE.md` — the design guide
+- `node_modules/@k8ordo/i18n/docs/llms.txt` — the index
+
+## License
+
+MIT

package/dist/accept-language.d.mts

@@ -0,0 +1,11 @@
+//#region src/accept-language.d.ts
+/**
+ * The tags of an `Accept-Language` header, most preferred first: `q` weights
+ * decide the order (a tag without one weighs 1), ties keep the header's
+ * order, `q=0` and the `*` wildcard are dropped — the wildcard says "anything",
+ * which is what the default locale already means. Feed the result to
+ * `locales.negotiate`; a missing header (`null`) is an empty list.
+ */
+declare const parseAcceptLanguage: (header: string | null) => string[];
+//#endregion
+export { parseAcceptLanguage };

package/dist/accept-language.mjs

@@ -0,0 +1,31 @@
+//#region src/accept-language.ts
+/**
+* The tags of an `Accept-Language` header, most preferred first: `q` weights
+* decide the order (a tag without one weighs 1), ties keep the header's
+* order, `q=0` and the `*` wildcard are dropped — the wildcard says "anything",
+* which is what the default locale already means. Feed the result to
+* `locales.negotiate`; a missing header (`null`) is an empty list.
+*/
+const parseAcceptLanguage = (header) => {
+	if (header === null || header.trim() === "") return [];
+	return header.split(",").flatMap((part, index) => {
+		const [rawTag = "", ...params] = part.split(";");
+		const tag = rawTag.trim();
+		if (tag === "" || tag === "*") return [];
+		let quality = 1;
+		for (const param of params) {
+			const [name, value] = param.split("=");
+			if (name?.trim().toLowerCase() === "q" && value !== void 0) {
+				const parsed = Number(value.trim());
+				if (!Number.isNaN(parsed)) quality = parsed;
+			}
+		}
+		return quality > 0 ? [{
+			tag,
+			quality,
+			index
+		}] : [];
+	}).toSorted((a, b) => b.quality - a.quality || a.index - b.index).map((entry) => entry.tag);
+};
+//#endregion
+export { parseAcceptLanguage };

package/dist/current.d.mts

@@ -0,0 +1,47 @@
+//#region src/current.d.ts
+/**
+ * Where the current locale is kept, on each side of the network.
+ *
+ * On a server the request that `paramsSchema` accepted (or `locales.run`)
+ * names it, and it is carried by `AsyncLocalStorage` so concurrent renders
+ * stay apart. The RSC environment and the SSR environment (where client
+ * components run on the server) are separate module graphs in one process,
+ * so the storage — and the locale set that registered — live on
+ * `globalThis`, not in this module.
+ *
+ * In the browser the URL is the locale: its first segment, read when asked.
+ */
+type LocaleStorage = {
+  getStore: () => string | undefined;
+  enterWith: (locale: string) => void;
+  run: <T>(locale: string, fn: () => T) => T;
+};
+/** What `message()` needs from the locale set: the default, and membership. */
+type RegisteredSet = {
+  readonly default: string;
+  readonly is: (value: unknown) => boolean;
+};
+declare const inBrowser: boolean;
+/**
+ * Reached through `process.getBuiltinModule` rather than an import so the
+ * same build runs in the browser, where there is no request to scope to.
+ */
+declare const localeStorage: () => LocaleStorage | null;
+/**
+ * The set messages read is the last one defined; an application has one.
+ * Last rather than first so that a dev server re-evaluating the module that
+ * defines the set (a locale added under HMR) is what messages see next.
+ */
+declare const register: (set: RegisteredSet) => void;
+/** Whether a set has registered in this environment yet. */
+declare const setRegistered: () => boolean;
+/**
+ * The current locale as a string, or `null` when nothing names one: no
+ * segment in the URL, no request in progress. A registered set makes an
+ * unknown segment `null` too, so `/fr/…` does not read as a locale.
+ */
+declare const currentLocale: () => string | null;
+/** The registered default, when a set registered in this environment. */
+declare const registeredDefault: () => string | null;
+//#endregion
+export { LocaleStorage, RegisteredSet, currentLocale, inBrowser, localeStorage, register, registeredDefault, setRegistered };

package/dist/current.mjs

@@ -0,0 +1,47 @@
+//#region src/current.ts
+const STORAGE_KEY = Symbol.for("@k8ordo/i18n/storage");
+const SET_KEY = Symbol.for("@k8ordo/i18n/locales");
+const global = globalThis;
+const inBrowser = typeof document !== "undefined";
+/**
+* Reached through `process.getBuiltinModule` rather than an import so the
+* same build runs in the browser, where there is no request to scope to.
+*/
+const localeStorage = () => {
+	const existing = global[STORAGE_KEY];
+	if (existing !== void 0) return existing;
+	const getBuiltinModule = global.process?.getBuiltinModule;
+	if (typeof getBuiltinModule !== "function") return null;
+	const { AsyncLocalStorage } = getBuiltinModule("node:async_hooks");
+	const created = new AsyncLocalStorage();
+	global[STORAGE_KEY] = created;
+	return created;
+};
+/**
+* The set messages read is the last one defined; an application has one.
+* Last rather than first so that a dev server re-evaluating the module that
+* defines the set (a locale added under HMR) is what messages see next.
+*/
+const register = (set) => {
+	global[SET_KEY] = set;
+};
+/** The first segment of the browser's URL, whatever it spells. */
+const browserSegment = () => global.location?.pathname.split("/")[1] ?? "";
+/** Whether a set has registered in this environment yet. */
+const setRegistered = () => global[SET_KEY] !== void 0;
+/**
+* The current locale as a string, or `null` when nothing names one: no
+* segment in the URL, no request in progress. A registered set makes an
+* unknown segment `null` too, so `/fr/…` does not read as a locale.
+*/
+const currentLocale = () => {
+	const set = global[SET_KEY];
+	const named = inBrowser ? browserSegment() : localeStorage()?.getStore();
+	if (named === void 0 || named === "") return null;
+	if (set !== void 0 && !set.is(named)) return null;
+	return named;
+};
+/** The registered default, when a set registered in this environment. */
+const registeredDefault = () => global[SET_KEY]?.default ?? null;
+//#endregion
+export { currentLocale, inBrowser, localeStorage, register, registeredDefault, setRegistered };

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { parseAcceptLanguage } from "./accept-language.mjs";
+import { Delocalized, LocaleOf, LocaleParamsSchema, Locales, LocalesOptions, defineLocales } from "./locales.mjs";
+import { Register, RegisteredLocale } from "./register.mjs";
+import { Message, Variants, message } from "./message.mjs";
+export { type Delocalized, type LocaleOf, type LocaleParamsSchema, type Locales, type LocalesOptions, type Message, type Register, type RegisteredLocale, type Variants, defineLocales, message, parseAcceptLanguage };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { parseAcceptLanguage } from "./accept-language.mjs";
+import { defineLocales } from "./locales.mjs";
+import { message } from "./message.mjs";
+export { defineLocales, message, parseAcceptLanguage };

package/dist/locales.d.mts

@@ -0,0 +1,103 @@
+//#region src/locales.d.ts
+/**
+ * The one shape every validation library agrees on (Standard Schema), as far
+ * as `@k8ordo/static` / `@k8ordo/server` read it for a route's `paramsSchema`.
+ * Declared here rather than depended on so the package carries no schema
+ * library: a locale set is a list, and a list can check membership itself.
+ */
+type LocaleParamsSchema<L extends string> = {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: '@k8ordo/i18n';
+    readonly validate: (value: unknown) => {
+      readonly value: {
+        readonly locale: L;
+      };
+      readonly issues?: undefined;
+    } | {
+      readonly issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path: readonly ['locale'];
+      }>;
+    };
+    readonly types?: {
+      readonly input: {
+        readonly locale: string;
+      };
+      readonly output: {
+        readonly locale: L;
+      };
+    } | undefined;
+  };
+};
+type Delocalized<L extends string> = {
+  /** The locale the first segment spelled, or `null` when it spelled none. */
+  readonly locale: L | null;
+  /** The pathname with that segment removed — never empty, `/` at least. */
+  readonly pathname: string;
+};
+/**
+ * An application's locale set. `L` is the union of its tags, `D` the default
+ * among them.
+ */
+type Locales<L extends string = string, D extends L = L> = {
+  /** Every locale, in the order given; the first is the default unless told otherwise. */
+  readonly all: readonly L[];
+  /** The locale used when negotiation finds nothing better, and when nothing names one. */
+  readonly default: D;
+  /** Membership, as a type guard — the check `params.locale` and a pathname segment go through. */
+  readonly is: (value: unknown) => value is L;
+  /**
+   * The best supported locale for a preference list — `navigator.languages`
+   * in the browser, `parseAcceptLanguage(header)` on a server. Each requested
+   * tag is tried in order — the exact tag, then the first supported locale
+   * that speaks its language — and nothing matching is the default. A tag
+   * that is not BCP 47 is skipped, not thrown on: the list is user input.
+   */
+  readonly negotiate: (requested: Iterable<string>) => L;
+  /** `'/ui'` → `'/en/ui'`, `'/'` → `'/en'`. The pathname must not already carry a locale segment. */
+  readonly localize: (pathname: string, locale: L) => string;
+  /** The inverse: `'/en/ui'` → `{ locale: 'en', pathname: '/ui' }`, `'/x'` → `{ locale: null, pathname: '/x' }`. */
+  readonly delocalize: (pathname: string) => Delocalized<L>;
+  /**
+   * A params schema for a `[locale]` route segment, in the shape
+   * `@k8ordo/static` / `@k8ordo/server` run: `export const paramsSchema =
+   * locales.paramsSchema` makes `/fr/…` a pathname the pattern does not
+   * answer. Accepting a locale also makes it the current one for the rest of
+   * that request's render, which is how `getLocale()` knows it on the server.
+   */
+  readonly paramsSchema: LocaleParamsSchema<L>;
+  /**
+   * The locale of the render in progress. In the browser it is the first
+   * segment of `location.pathname`; on the server it is what `paramsSchema`
+   * accepted for this request, or what `run` set. Neither names one → the
+   * default. Not a hook: call it anywhere, including inside a message.
+   */
+  readonly getLocale: () => L;
+  /**
+   * Runs `fn` with `locale` as the current one for everything it starts —
+   * a test, a Server Action, code outside a `[locale]` route. Server only:
+   * in the browser the URL is the locale.
+   */
+  readonly run: <T>(locale: L, fn: () => T) => T;
+};
+type LocalesOptions<D extends string> = {
+  /** The default locale. Must be one of the list; the first entry when omitted. */
+  readonly default?: D;
+};
+/** The locale union of a `Locales` — `LocaleOf<typeof locales>`. */
+type LocaleOf<Ls> = Ls extends Locales<infer L, infer _D> ? L : never;
+/**
+ * Declares the locale set once. Everything that needs to know which locales
+ * exist — the params schema of the `[locale]` segment, the static build's
+ * path expansion, the language switcher, negotiation for a `/` redirect,
+ * every message — reads this value, so the list is spelled in one place.
+ *
+ * ```ts
+ * export const locales = defineLocales(['ja', 'en']);
+ * export const locales = defineLocales(['en-US', 'en-GB', 'ja'], { default: 'ja' });
+ * ```
+ */
+declare const defineLocales: <const All extends readonly [string, ...string[]], D extends All[number] = All[0]>(all: All, options?: LocalesOptions<D>) => Locales<All[number], D>;
+//#endregion
+export { Delocalized, LocaleOf, LocaleParamsSchema, Locales, LocalesOptions, defineLocales };

package/dist/locales.mjs

@@ -0,0 +1,108 @@
+import { inBrowser, localeStorage, register } from "./current.mjs";
+//#region src/locales.ts
+/** `Intl.Locale` throws a RangeError on a tag that is not BCP 47; that is the only check a tag needs. */
+const parseTag = (tag) => {
+	try {
+		return new Intl.Locale(tag);
+	} catch {
+		return null;
+	}
+};
+/** `'/ui'` → `'/en/ui'`; `'/'` and `''` → `'/en'`. Pure over strings, so it lives outside the set. */
+const localize = (pathname, locale) => {
+	const rest = pathname === "/" || pathname === "" ? "" : pathname;
+	if (rest !== "" && !rest.startsWith("/")) throw new TypeError(`localize: ${JSON.stringify(pathname)} is not a pathname — it does not start with "/"`);
+	return `/${locale}${rest}`;
+};
+/** Server only: the browser has no request, and its URL already is the locale. */
+const run = (locale, fn) => {
+	if (inBrowser) throw new Error("locales.run: in the browser the URL is the locale — navigate instead");
+	const storage = localeStorage();
+	if (storage === null) throw new Error("locales.run: this runtime has no AsyncLocalStorage to scope a locale to");
+	return storage.run(locale, fn);
+};
+/**
+* Declares the locale set once. Everything that needs to know which locales
+* exist — the params schema of the `[locale]` segment, the static build's
+* path expansion, the language switcher, negotiation for a `/` redirect,
+* every message — reads this value, so the list is spelled in one place.
+*
+* ```ts
+* export const locales = defineLocales(['ja', 'en']);
+* export const locales = defineLocales(['en-US', 'en-GB', 'ja'], { default: 'ja' });
+* ```
+*/
+const defineLocales = (all, options) => {
+	const list = all;
+	if (new Set(list).size !== list.length) throw new TypeError(`defineLocales: a locale is listed twice in ${JSON.stringify(list)}`);
+	const fallback = options?.default ?? list[0];
+	if (!list.includes(fallback)) throw new TypeError(`defineLocales: the default ${JSON.stringify(fallback)} is not in ${JSON.stringify(list)}`);
+	const supported = list.map((tag) => {
+		const parsed = parseTag(tag);
+		if (parsed === null) throw new TypeError(`defineLocales: ${JSON.stringify(tag)} is not a BCP 47 language tag`);
+		return {
+			tag,
+			language: parsed.language
+		};
+	});
+	const byExactTag = new Map(supported.map((s) => [s.tag.toLowerCase(), s.tag]));
+	const is = (value) => typeof value === "string" && list.includes(value);
+	const negotiate = (requested) => {
+		for (const tag of requested) {
+			const exact = byExactTag.get(tag.toLowerCase());
+			if (exact !== void 0) return exact;
+			const parsed = parseTag(tag);
+			if (parsed === null) continue;
+			const spoken = supported.find((s) => s.language === parsed.language);
+			if (spoken !== void 0) return spoken.tag;
+		}
+		return fallback;
+	};
+	const delocalize = (pathname) => {
+		const first = pathname.split("/")[1] ?? "";
+		if (!is(first)) return {
+			locale: null,
+			pathname
+		};
+		const rest = pathname.slice(first.length + 1);
+		return {
+			locale: first,
+			pathname: rest === "" ? "/" : rest
+		};
+	};
+	const getLocale = () => {
+		if (inBrowser) return delocalize(location.pathname).locale ?? fallback;
+		const current = localeStorage()?.getStore();
+		return is(current) ? current : fallback;
+	};
+	const paramsSchema = { "~standard": {
+		version: 1,
+		vendor: "@k8ordo/i18n",
+		validate: (value) => {
+			const locale = typeof value === "object" && value !== null && "locale" in value ? value.locale : void 0;
+			if (!is(locale)) return { issues: [{
+				message: `expected one of ${JSON.stringify(list)}, received ${JSON.stringify(locale)}`,
+				path: ["locale"]
+			}] };
+			localeStorage()?.enterWith(locale);
+			return { value: { locale } };
+		}
+	} };
+	register({
+		default: fallback,
+		is
+	});
+	return {
+		all: list,
+		default: fallback,
+		is,
+		negotiate,
+		localize,
+		delocalize,
+		paramsSchema,
+		getLocale,
+		run
+	};
+};
+//#endregion
+export { defineLocales };

package/dist/message.d.mts

@@ -0,0 +1,31 @@
+import { RegisteredLocale } from "./register.mjs";
+//#region src/message.d.ts
+/**
+ * A message: a function of the values its text needs (none for a plain
+ * string), returning the text in the current locale. What a component that
+ * takes a message as a prop should accept.
+ */
+type Message<A extends readonly unknown[] = []> = (...args: A) => string;
+/** One value per locale — every locale, no locale twice. */
+type Variants<V> = Readonly<Record<RegisteredLocale, V>>;
+/**
+ * Declares one message with its text in every locale. The result reads the
+ * locale where it is called — the request on a server, the URL in the
+ * browser — so the same call renders on either side, and a bundler keeps
+ * only the messages a client module names.
+ *
+ * ```ts
+ * export const home = message({ ja: 'ホーム', en: 'Home' });
+ * export const greeting = message({
+ *   ja: (name: string) => `こんにちは、${name}`,
+ *   en: (name) => `Hello, ${name}`,
+ * });
+ * ```
+ *
+ * When nothing names a locale, the text is the default locale's — the one
+ * `defineLocales` registered, else the first variant written.
+ */
+declare function message(variants: Variants<string>): Message;
+declare function message<A extends readonly unknown[]>(variants: Variants<(...args: A) => string>): Message<A>;
+//#endregion
+export { Message, Variants, message };

package/dist/message.mjs

@@ -0,0 +1,13 @@
+import { currentLocale, registeredDefault, setRegistered } from "./current.mjs";
+//#region src/message.ts
+function message(variants) {
+	return (...args) => {
+		const named = currentLocale();
+		const locale = named !== null && (setRegistered() || Object.hasOwn(variants, named)) ? named : registeredDefault();
+		const variant = locale === null ? variants[Object.keys(variants)[0] ?? ""] : variants[locale];
+		if (variant === void 0) throw new TypeError(`message: no text for ${JSON.stringify(locale)} in ${JSON.stringify(Object.keys(variants))}`);
+		return typeof variant === "function" ? variant(...args) : variant;
+	};
+}
+//#endregion
+export { message };

package/dist/register.d.mts

@@ -0,0 +1,23 @@
+//#region src/register.d.ts
+/**
+ * Merged by the application once, so `message()` knows which locales every
+ * message must carry — without each message naming the set:
+ *
+ * ```ts
+ * declare module '@k8ordo/i18n' {
+ *   interface Register {
+ *     locale: LocaleOf<typeof locales>;
+ *   }
+ * }
+ * ```
+ *
+ * The one `interface` in this package, kept so because it exists to be
+ * merged (see the repository's conventions).
+ */
+interface Register {}
+/** The application's locale union once `Register` is merged; `string` before. */
+type RegisteredLocale = Register extends {
+  locale: infer L extends string;
+} ? L : string;
+//#endregion
+export { Register, RegisteredLocale };

package/dist/register.mjs

@@ -0,0 +1 @@
+export {};

package/docs/GUIDE.md

@@ -0,0 +1,301 @@
+# @k8ordo/i18n
+
+The locale axis of an application, owned.
+
+One locale set declares which locales exist and which is the default, and
+derives everything that depends on the list: the URL segment, the params
+schema of the `[locale]` route, negotiation from `navigator.languages` or
+`Accept-Language`, and the static build's path list. Each message is a
+function — `message({ ja: 'ホーム', en: 'Home' })` — that reads the locale
+where it is called. On the server that is the request the `[locale]` schema
+accepted; in the browser it is the URL. So the same call renders in a Server
+Component and in a Client Component, there is no provider and no hook, and a
+bundler keeps only the messages a client module names.
+
+Like every k8ordo package it assumes React 19 and Server Components, uses
+only what has reached Baseline newly available, and ships no polyfills or
+legacy fallbacks.
+
+## What it does not own
+
+- **The pathname.** `@k8ordo/router` owns routes; this package owns the
+  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`.
+  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
+  loader, a namespace list, or a provider prop.
+
+## The shape of it
+
+```ts
+// 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>;
+  }
+}
+```
+
+```ts
+// messages/nav.ts — each message is one export
+import { message } from '@k8ordo/i18n';
+
+export const home = message({ ja: 'ホーム', en: 'Home' });
+export const greeting = message({
+  ja: (name: string) => `こんにちは、${name}さん`,
+  en: (name) => `Hello, ${name}`,
+});
+```
+
+```tsx
+// routes/[locale]/layout.tsx — a Server Component
+import { locales } from '../../i18n';
+
+export const paramsSchema = locales.paramsSchema;
+```
+
+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';
+
+<h1>{nav.home()}</h1>
+<p>{nav.greeting(name)}</p>
+```
+
+That is the whole surface: `defineLocales`, `Register`, `message`, and
+`paramsSchema` on the `[locale]` segment.
+
+## 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.
+
+### Negotiation
+
+`negotiate` takes the list as the browser or the header gives it and tries
+each requested tag in order — the exact tag, then the first supported locale
+that speaks its language — before falling back to the default. Nothing
+matching across the whole list is the default; a tag that is not BCP 47 is
+skipped, because the list is user input.
+
+```ts
+locales.negotiate(navigator.languages); // in the browser
+locales.negotiate(parseAcceptLanguage(request.headers.get('accept-language')));
+```
+
+`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.
+
+## Messages
+
+`message(variants)` declares one message with its text in every locale.
+Once `Register` carries the app's locale union, a variant missing for any
+locale is a type error at the declaration — that is the whole "untranslated
+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:
+
+```ts
+export const items = message({
+  ja: (count: number) => `${String(count)} 件`,
+  en: (count) =>
+    `${String(count)} ${new Intl.PluralRules('en').select(count) === 'one' ? 'item' : 'items'}`,
+});
+```
+
+The result is a `Message<Args>`: `() => string` for text, `(…args) =>
+string` for a function. That type is what a component that takes a message
+as a prop should accept —
+
+```tsx
+type NavItem = { path: string; label: Message };
+const items: NavItem[] = [{ path: '/ui', label: nav.ui }];
+…
+<a href={item.path}>{item.label()}</a>
+```
+
+— so data can carry messages without carrying strings, and without any
+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';
+```
+
+```tsx
+import * as m from '../messages';
+<h1>{m.nav.home()}</h1>;
+```
+
+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.
+
+### 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.
+
+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,
+and in both cases a `Message` prop is fine because it never crosses. A
+component that only reads props and messages — a page title, a landing
+layout — is best left without `'use client'` for exactly this reason.
+
+### What reaches the browser
+
+`message()` has no side effect at the declaration — it returns a function
+and touches nothing — so a bundler treats an unreferenced message as dead
+code. What a client bundle carries is therefore exactly the messages that
+`'use client'` modules name, in every locale, and nothing a Server Component
+rendered. This is the reason messages are functions and exports rather than
+entries in a dictionary object: a dictionary is kept or dropped whole.
+
+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.
+
+## 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
+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
+`locales.run(locale, fn)`; and when nothing names a locale, messages render
+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.
+
+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.
+
+### The `/` page
+
+`/` is the one URL without a locale. Render nothing there and redirect from
+an effect:
+
+```tsx
+'use client';
+useEffect(() => {
+  navigation.navigate(
+    locales.localize('/', 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>`
+
+The root layout sits above `[locale]` and receives `pathname`; the schema
+has already run for that request, so `locales.getLocale()` is right, and
+`locales.delocalize(pathname).locale ?? locales.default` says the same thing
+in terms of the URL alone.
+
+## Static builds
+
+`@k8ordo/static` asks for the pathnames of every pattern with a parameter.
+Expand `[locale]` from the set — the list is spelled once:
+
+```ts
+framework({
+  paths: (patterns) =>
+    patterns.flatMap((pattern) =>
+      locales.all.map((locale) => pattern.replace(':locale', locale)),
+    ),
+});
+```
+
+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.
+
+## 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.
+
+## 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.
+  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).
+
+## 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.

package/docs/llms.txt

@@ -0,0 +1,44 @@
+# @k8ordo/i18n
+
+> The locale axis of an application, owned. `defineLocales(['ja', 'en'])`
+> declares the set once 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
+> (`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.
+>
+> Like every k8ordo package it assumes React 19 and Server Components, uses
+> only what has reached Baseline newly available, and ships no polyfills or
+> legacy fallbacks.
+
+When installed via npm, these docs live under `node_modules/@k8ordo/i18n/docs/`.
+
+## Guide
+
+- [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
+  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`.
+
+## 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
+  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)`
+  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`,
+  `Variants`, `Register`, `RegisteredLocale`, `Delocalized`,
+  `LocaleParamsSchema`, `LocalesOptions`.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@k8ordo/i18n",
+  "version": "0.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",
+    "intl",
+    "locale",
+    "react",
+    "server-components",
+    "translation",
+    "typescript"
+  ],
+  "homepage": "https://ordo.k8o.me",
+  "bugs": {
+    "url": "https://github.com/k35o/k8ordo/issues"
+  },
+  "license": "MIT",
+  "author": "k8o <kosakanoki@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k35o/k8ordo.git"
+  },
+  "files": [
+    "dist/**",
+    "docs/**"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@vitest/browser-playwright": "5.0.0",
+    "publint": "0.3.24",
+    "typescript": "7.0.2",
+    "vite": "8.2.2",
+    "vite-plus": "0.3.0",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "check": "vp check",
+    "check:write": "vp check --fix",
+    "check:package": "publint && attw --pack . --profile esm-only"
+  }
+}