@tatara/i18n 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,35 @@
 # @tatara/i18n
 
-Part of [tatara](https://github.com/mohammed-bageri/tatara-cli).
+Part of [tatara](https://github.com/mohammed-bageri/tatara-cli). Dictionaries, `t()`, plurals,
+language detection for Hono and localised zod messages. No i18n library underneath.
+
+```ts
+import { createI18n, loadDictionaries, zodErrorMap } from "@tatara/i18n";
+import { z } from "zod";
+
+const i18n = createI18n({
+	// { en: { common: {…}, errors: {…} }, ar: {…} } from locales/<lang>/<ns>.json
+	dictionaries: await loadDictionaries({ dir: `${process.cwd()}/locales` }),
+	defaultLanguage: "en",
+	detection: { cookie: "language", persist: { maxAge: 31_536_000, httpOnly: true, sameSite: "Lax" } },
+});
+
+app.use(i18n.detectLanguage); // ?lang, cookie, Accept-Language → c.var.language
+app.use(i18n.preferLanguage((c) => c.get("user")?.language)); // unless ?lang is set
+z.config({ customError: zodErrorMap(i18n, { prefix: "errors:validation." }) });
+
+const t = i18n.translator(c.get("language"));
+t("common:items", { count: 3 }); // items_one / items_other / items_zero
+t("errors:notFound", { defaultValue: "Not found" });
+```
+
+- Keys are `a.b.c` or `namespace:a.b.c`; a namespace is a top-level key of the dictionary.
+- Variables are `{name}` or `{{name}}`; unknown ones are left as written.
+- Missing keys fall back to the default language, then `defaultValue` (or `t`'s `fallback`), then the key.
+- `currentLanguage()` is the request's language anywhere below `detectLanguage` (the zod map uses it);
+  `withLanguage(lang, fn)` sets it for jobs and scripts.
+- `zodErrorMap` keys: `required`, `invalid_type`, `too_small`, `too_big`, `invalid_format`,
+  `invalid_value`, `custom` under `prefix` (default `validation.`), or full keys via `keys`. A kind
+  with no translation keeps zod's message.
+- `pick(lang, { en, ar })` chooses a per-language value; `withEnumLabels(row, { status: "jobs:status" }, t)`
+  adds `status_label`.

package/dist/index.d.mts

@@ -1,16 +1,98 @@
-import { Env, MiddlewareHandler } from "hono";
+import { Context, Env, MiddlewareHandler } from "hono";
+import { CookieOptions } from "hono/utils/cookie";
+//#region src/enum-labels.d.ts
+type Translate = (key: string) => string;
+/**
+ * A copy of `data` with a `<field>_label` for each field in `enumMap` that has a value:
+ * `enumMap` maps a field to its key prefix, so `{ status: "jobs:status" }` reads `jobs:status.DRAFT`.
+ */
+export declare function withEnumLabels<T extends Record<string, unknown>>(data: T, enumMap: Record<string, string>, t: Translate): T & Record<string, unknown>;
+/** `withEnumLabels` for every item. */
+export declare function withEnumLabelsAll<T extends Record<string, unknown>>(items: T[], enumMap: Record<string, string>, t: Translate): Array<T & Record<string, unknown>>;
+//#endregion
+//#region src/load.d.ts
+interface LoadDictionariesOptions {
+  /** holds `<language>/<namespace>.json`, e.g. `${process.cwd()}/locales` */
+  dir: string;
+  /** default: every sub-directory of `dir` */
+  languages?: readonly string[];
+  /** default: every `*.json` file found in any language */
+  namespaces?: readonly string[];
+  /** a namespace file one language lacks; that namespace is `{}` there */
+  onMissing?: (language: string, namespace: string) => void;
+}
+/**
+ * Reads `<dir>/<language>/<namespace>.json` into `{ [language]: { [namespace]: … } }`, so
+ * `t(language, "namespace:key")` finds them. Namespaces are discovered from the files.
+ */
+export declare function loadDictionaries(options: LoadDictionariesOptions): Promise<Record<string, Dictionary>>;
+//#endregion
+//#region src/zod.d.ts
+/** The fields of a zod issue the messages use; zod's own issue type is assignable to it. */
+interface ZodIssueLike {
+  code?: string;
+  input?: unknown;
+  expected?: unknown;
+  minimum?: unknown;
+  maximum?: unknown;
+  values?: readonly unknown[];
+}
+type ZodMessageKind = "required" | "invalid_type" | "too_small" | "too_big" | "invalid_format" | "invalid_value" | "custom";
+interface ZodErrorMapOptions {
+  /** key prefix; a message's key is `${prefix}${kind}` (default "validation.") */
+  prefix?: string;
+  /** full keys for some kinds, overriding the prefix */
+  keys?: Partial<Record<ZodMessageKind, string>>;
+}
+/**
+ * A zod error map giving messages in `i18n.currentLanguage()` (the request's language under
+ * `detectLanguage`). Register it once: `z.config({ customError: zodErrorMap(i18n) })`.
+ * Kinds without a translation keep zod's own message.
+ */
+export declare function zodErrorMap(i18n: I18n, options?: ZodErrorMapOptions): (issue: ZodIssueLike) => {
+  message: string;
+} | undefined;
+//#endregion
 //#region src/index.d.ts
 export type Dictionary = {
   [key: string]: string | Dictionary;
 };
+/** Variables for a message; `count` (a number) also picks the plural form (`key_one`, `key_other`, `key_zero`). */
+export type TranslateVars = Record<string, unknown>;
+/** A translator bound to one language, i18next-style: `t("errors:notFound", { name, count, defaultValue })`. */
+export type Translator = (key: string, vars?: TranslateVars & {
+  defaultValue?: string;
+}) => string;
+export interface LanguageDetectionOptions {
+  /** query parameter, or `false` to ignore the query (default "lang") */
+  query?: string | false;
+  /** cookie name, or `false` to ignore cookies (default "lang") */
+  cookie?: string | false;
+  /** read Accept-Language (default true) */
+  header?: boolean;
+  /** write the detected language to the cookie when it differs, e.g. `{ maxAge: 31536000, httpOnly: true }` */
+  persist?: CookieOptions;
+}
 export interface I18nOptions {
-  /** language code → strings, e.g. { en, ar } from src/locales */
+  /** language code → strings, e.g. { en, ar } from src/locales, or `loadDictionaries()` */
   dictionaries: Record<string, Dictionary>;
   defaultLanguage: string;
+  detection?: LanguageDetectionOptions;
 }
-export declare function createI18n({ dictionaries, defaultLanguage }: I18nOptions): {
+export declare function createI18n({ dictionaries, defaultLanguage, detection }: I18nOptions): {
   languages: string[];
-  t: (language: string, key: string, fallback?: string, vars?: Record<string, string>) => string;
+  defaultLanguage: string;
+  t: (language: string, key: string, fallback?: string, vars?: TranslateVars) => string;
+  translator: (language: string | null | undefined) => Translator;
+  exists: (key: string, language?: string) => boolean;
+  resource: (language: string, key: string) => string | Dictionary | undefined;
+  resolveLanguage: (language: string | null | undefined) => string;
+  currentLanguage: () => string;
+  withLanguage: <T>(language: string, fn: () => T) => T;
+  pick: (language: string, values: Partial<Record<string, string | null | undefined>>) => string;
   detectLanguage: MiddlewareHandler<Env>;
+  preferLanguage: (preferred: (c: Context) => string | null | undefined | Promise<string | null | undefined>) => MiddlewareHandler<Env>;
 };
-//#endregion
+export type I18n = ReturnType<typeof createI18n>;
+//#endregion
+export type { LoadDictionariesOptions, ZodErrorMapOptions, ZodIssueLike, ZodMessageKind };

package/dist/index.mjs

@@ -1,33 +1,234 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getCookie, setCookie } from "hono/cookie";
 import { createMiddleware } from "hono/factory";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+//#region src/enum-labels.ts
+/**
+* A copy of `data` with a `<field>_label` for each field in `enumMap` that has a value:
+* `enumMap` maps a field to its key prefix, so `{ status: "jobs:status" }` reads `jobs:status.DRAFT`.
+*/
+function withEnumLabels(data, enumMap, t) {
+	const result = { ...data };
+	for (const [field, prefix] of Object.entries(enumMap)) {
+		const value = data[field];
+		if (value !== void 0 && value !== null) result[`${field}_label`] = t(`${prefix}.${value}`);
+	}
+	return result;
+}
+/** `withEnumLabels` for every item. */
+function withEnumLabelsAll(items, enumMap, t) {
+	return items.map((item) => withEnumLabels(item, enumMap, t));
+}
+//#endregion
+//#region src/load.ts
+async function list(dir, pick) {
+	return (await readdir(dir, { withFileTypes: true })).flatMap((e) => pick(e.name, e.isDirectory()) ?? []).sort();
+}
+/**
+* Reads `<dir>/<language>/<namespace>.json` into `{ [language]: { [namespace]: … } }`, so
+* `t(language, "namespace:key")` finds them. Namespaces are discovered from the files.
+*/
+async function loadDictionaries(options) {
+	const languages = options.languages ?? await list(options.dir, (name, isDir) => isDir ? name : void 0);
+	const files = /* @__PURE__ */ new Map();
+	for (const language of languages) {
+		const names = await list(join(options.dir, language), (name, isDir) => !isDir && name.endsWith(".json") ? name.slice(0, -5) : void 0).catch(() => []);
+		files.set(language, names);
+	}
+	const namespaces = options.namespaces ?? [...new Set([...files.values()].flat())].sort();
+	const result = {};
+	for (const language of languages) {
+		const dictionary = {};
+		for (const namespace of namespaces) {
+			if (!files.get(language)?.includes(namespace)) {
+				options.onMissing?.(language, namespace);
+				dictionary[namespace] = {};
+				continue;
+			}
+			const text = await readFile(join(options.dir, language, `${namespace}.json`), "utf8");
+			dictionary[namespace] = JSON.parse(text);
+		}
+		result[language] = dictionary;
+	}
+	return result;
+}
+//#endregion
+//#region src/zod.ts
+function describe(issue) {
+	switch (issue.code) {
+		case "invalid_type": return issue.input === void 0 ? ["required", {}] : ["invalid_type", {
+			expected: issue.expected,
+			received: typeof issue.input
+		}];
+		case "too_small": return ["too_small", { minimum: String(issue.minimum) }];
+		case "too_big": return ["too_big", { maximum: String(issue.maximum) }];
+		case "invalid_format": return ["invalid_format", {}];
+		case "invalid_value": return ["invalid_value", { options: (issue.values ?? []).map(String).join(", ") }];
+		case "custom": return ["custom", {}];
+		default: return;
+	}
+}
+/**
+* A zod error map giving messages in `i18n.currentLanguage()` (the request's language under
+* `detectLanguage`). Register it once: `z.config({ customError: zodErrorMap(i18n) })`.
+* Kinds without a translation keep zod's own message.
+*/
+function zodErrorMap(i18n, options = {}) {
+	const prefix = options.prefix ?? "validation.";
+	return (issue) => {
+		const described = describe(issue);
+		if (!described) return void 0;
+		const [kind, vars] = described;
+		const key = options.keys?.[kind] ?? `${prefix}${kind}`;
+		const language = i18n.currentLanguage();
+		if (!i18n.exists(key, language)) return void 0;
+		return { message: i18n.t(language, key, key, vars) };
+	};
+}
+//#endregion
 //#region src/index.ts
+/** @tatara/i18n: dictionaries, `t()`, language detection for Hono and localised zod messages. */
+function path(key) {
+	const ns = key.indexOf(":");
+	const parts = (ns === -1 ? key : key.slice(ns + 1)).split(".");
+	return ns === -1 ? parts : [key.slice(0, ns), ...parts];
+}
 function lookup(dict, key) {
 	let node = dict;
-	for (const part of key.split(".")) {
+	for (const part of path(key)) {
 		if (!node || typeof node === "string") return void 0;
 		node = node[part];
 	}
-	return typeof node === "string" ? node : void 0;
+	return node;
 }
-function createI18n({ dictionaries, defaultLanguage }) {
+const VARIABLE = /\{\{\s*(\w+)\s*\}\}|\{(\w+)\}/g;
+function interpolate(text, vars) {
+	return text.replace(VARIABLE, (match, double, single) => {
+		const value = vars[double ?? single];
+		return value === void 0 || value === null ? match : String(value);
+	});
+}
+function createI18n({ dictionaries, defaultLanguage, detection = {} }) {
 	const languages = Object.keys(dictionaries);
-	/** Translates `key` ("errors.NOT_FOUND"), falling back to the default language, then `fallback`. */
+	const supported = new Set(languages);
+	const storage = new AsyncLocalStorage();
+	const pluralRules = /* @__PURE__ */ new Map();
+	const queryKey = detection.query ?? "lang";
+	const cookieName = detection.cookie ?? "lang";
+	function plural(language, count) {
+		let rules = pluralRules.get(language);
+		if (!rules) {
+			rules = new Intl.PluralRules(language);
+			pluralRules.set(language, rules);
+		}
+		return rules.select(count);
+	}
+	/** `language` when it is supported, otherwise the default language. */
+	function resolveLanguage(language) {
+		return language && supported.has(language) ? language : defaultLanguage;
+	}
+	function find(language, key, count) {
+		for (const lang of language === defaultLanguage ? [language] : [language, defaultLanguage]) {
+			const dict = dictionaries[lang];
+			if (typeof count === "number") {
+				const forms = count === 0 ? ["zero", plural(lang, count)] : [plural(lang, count)];
+				for (const form of forms) {
+					const text = lookup(dict, `${key}_${form}`);
+					if (typeof text === "string") return text;
+				}
+			}
+			const text = lookup(dict, key);
+			if (typeof text === "string") return text;
+		}
+	}
+	/** Translates `key` ("errors.NOT_FOUND" or "errors:NOT_FOUND"), falling back to the default language, then `fallback`. */
 	function t(language, key, fallback = key, vars = {}) {
-		return (lookup(dictionaries[language], key) ?? lookup(dictionaries[defaultLanguage], key) ?? fallback).replace(/\{(\w+)\}/g, (_, name) => vars[name] ?? `{${name}}`);
+		return interpolate(find(language, key, vars.count) ?? fallback, vars);
+	}
+	/** A translator for one language (unsupported → default); missing keys give `defaultValue`, else the key. */
+	function translator(language) {
+		const lang = resolveLanguage(language);
+		return (key, vars = {}) => t(lang, key, vars.defaultValue ?? key, vars);
+	}
+	/** True when `key` has a string in `language` (or the default language). */
+	function exists(key, language = defaultLanguage) {
+		return find(resolveLanguage(language), key, void 0) !== void 0;
+	}
+	/** The raw entry at `key` in one language's dictionary, no fallback: a string, a subtree or undefined. */
+	function resource(language, key) {
+		return lookup(dictionaries[language], key);
+	}
+	/** The request's language inside `detectLanguage`/`withLanguage`, else the default language. */
+	function currentLanguage() {
+		return storage.getStore() ?? defaultLanguage;
+	}
+	/** Runs `fn` with `currentLanguage()` set to `language` (for jobs, CLI, tests). */
+	function withLanguage(language, fn) {
+		return storage.run(resolveLanguage(language), fn);
+	}
+	/** The value for `language` from per-language values (e.g. `{ en: row.nameEn, ar: row.nameAr }`); empty falls back to the default language. */
+	function pick(language, values) {
+		return values[language] || values[defaultLanguage] || "";
+	}
+	function accepted(header) {
+		const ranked = header.split(",").map((part, index) => {
+			const [tag = "", ...params] = part.trim().toLowerCase().split(";");
+			const q = params.map((p) => /^\s*q=([\d.]+)/.exec(p)?.[1]).find(Boolean);
+			return {
+				tag: tag.trim(),
+				q: q === void 0 ? 1 : Number(q),
+				index
+			};
+		}).filter((entry) => entry.tag && entry.q > 0).sort((a, b) => b.q - a.q || a.index - b.index);
+		for (const { tag } of ranked) {
+			const match = languages.find((l) => l.toLowerCase() === tag) ?? tag.split("-")[0];
+			if (match && supported.has(match)) return match;
+		}
+	}
+	function apply(c, language, next) {
+		c.set("language", language);
+		c.header("content-language", language);
+		return storage.run(language, next);
+	}
+	function explicitQuery(c) {
+		const value = queryKey ? c.req.query(queryKey) : void 0;
+		return value && supported.has(value) ? value : void 0;
+	}
+	/** ?lang, then the `lang` cookie, then Accept-Language; sets `c.var.language` and `currentLanguage()`. */
+	const detectLanguage = createMiddleware(async (c, next) => {
+		const fromCookie = cookieName ? getCookie(c, cookieName) : void 0;
+		const language = explicitQuery(c) ?? (fromCookie && supported.has(fromCookie) ? fromCookie : void 0) ?? (detection.header === false ? void 0 : accepted(c.req.header("accept-language") ?? "")) ?? defaultLanguage;
+		if (detection.persist && cookieName && fromCookie !== language) setCookie(c, cookieName, language, detection.persist);
+		await apply(c, language, next);
+	});
+	/**
+	* Replaces the detected language with `preferred(c)` (e.g. the signed-in user's stored
+	* preference) when it is supported, unless the request asked for one with the query
+	* parameter. Mount after `detectLanguage` and after whatever sets the user.
+	*/
+	function preferLanguage(preferred) {
+		return async (c, next) => {
+			if (explicitQuery(c)) return next();
+			const language = await preferred(c);
+			if (!language || !supported.has(language)) return next();
+			await apply(c, language, next);
+		};
 	}
 	return {
 		languages,
+		defaultLanguage,
 		t,
-		detectLanguage: createMiddleware(async (c, next) => {
-			const language = [
-				c.req.query("lang"),
-				/(?:^|;\s*)lang=([^;]+)/.exec(c.req.header("cookie") ?? "")?.[1],
-				...(c.req.header("accept-language") ?? "").split(",").map((part) => part.split(";")[0]?.trim().toLowerCase().split("-")[0])
-			].find((l) => l && languages.includes(l)) ?? defaultLanguage;
-			c.set("language", language);
-			c.header("content-language", language);
-			await next();
-		})
+		translator,
+		exists,
+		resource,
+		resolveLanguage,
+		currentLanguage,
+		withLanguage,
+		pick,
+		detectLanguage,
+		preferLanguage
 	};
 }
 //#endregion
-export { createI18n };
+export { createI18n, loadDictionaries, withEnumLabels, withEnumLabelsAll, zodErrorMap };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tatara/i18n",
-  "version": "0.1.0",
-  "description": "tatara i18n: dictionaries, t() and language detection for Hono",
+  "version": "0.2.0",
+  "description": "tatara i18n: dictionaries, t(), plurals, language detection for Hono and localised zod messages",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -23,7 +23,8 @@
     "hono": "^4.13.13"
   },
   "devDependencies": {
-    "hono": "^4.13.13"
+    "hono": "^4.13.13",
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "access": "public"

package/src/enum-labels.ts

@@ -0,0 +1,27 @@
+type Translate = (key: string) => string;
+
+/**
+ * A copy of `data` with a `<field>_label` for each field in `enumMap` that has a value:
+ * `enumMap` maps a field to its key prefix, so `{ status: "jobs:status" }` reads `jobs:status.DRAFT`.
+ */
+export function withEnumLabels<T extends Record<string, unknown>>(
+	data: T,
+	enumMap: Record<string, string>,
+	t: Translate,
+): T & Record<string, unknown> {
+	const result: Record<string, unknown> = { ...data };
+	for (const [field, prefix] of Object.entries(enumMap)) {
+		const value = data[field];
+		if (value !== undefined && value !== null) result[`${field}_label`] = t(`${prefix}.${value}`);
+	}
+	return result as T & Record<string, unknown>;
+}
+
+/** `withEnumLabels` for every item. */
+export function withEnumLabelsAll<T extends Record<string, unknown>>(
+	items: T[],
+	enumMap: Record<string, string>,
+	t: Translate,
+): Array<T & Record<string, unknown>> {
+	return items.map((item) => withEnumLabels(item, enumMap, t));
+}

package/src/index.ts

@@ -1,54 +1,221 @@
-/** @tatara/i18n: dictionaries, `t()` and language detection for Hono. */
-import type { Env, MiddlewareHandler } from "hono";
+/** @tatara/i18n: dictionaries, `t()`, language detection for Hono and localised zod messages. */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Context, Env, MiddlewareHandler } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
 import { createMiddleware } from "hono/factory";
+import type { CookieOptions } from "hono/utils/cookie";
+
+export { withEnumLabels, withEnumLabelsAll } from "./enum-labels.ts";
+export { type LoadDictionariesOptions, loadDictionaries } from "./load.ts";
+export {
+	type ZodErrorMapOptions,
+	type ZodIssueLike,
+	type ZodMessageKind,
+	zodErrorMap,
+} from "./zod.ts";
 
 export type Dictionary = { [key: string]: string | Dictionary };
 
+/** Variables for a message; `count` (a number) also picks the plural form (`key_one`, `key_other`, `key_zero`). */
+export type TranslateVars = Record<string, unknown>;
+
+/** A translator bound to one language, i18next-style: `t("errors:notFound", { name, count, defaultValue })`. */
+export type Translator = (key: string, vars?: TranslateVars & { defaultValue?: string }) => string;
+
+export interface LanguageDetectionOptions {
+	/** query parameter, or `false` to ignore the query (default "lang") */
+	query?: string | false;
+	/** cookie name, or `false` to ignore cookies (default "lang") */
+	cookie?: string | false;
+	/** read Accept-Language (default true) */
+	header?: boolean;
+	/** write the detected language to the cookie when it differs, e.g. `{ maxAge: 31536000, httpOnly: true }` */
+	persist?: CookieOptions;
+}
+
 export interface I18nOptions {
-	/** language code → strings, e.g. { en, ar } from src/locales */
+	/** language code → strings, e.g. { en, ar } from src/locales, or `loadDictionaries()` */
 	dictionaries: Record<string, Dictionary>;
 	defaultLanguage: string;
+	detection?: LanguageDetectionOptions;
 }
 
-function lookup(dict: Dictionary | undefined, key: string): string | undefined {
-	let node: string | Dictionary | undefined = dict;
-	for (const part of key.split(".")) {
+type Node = string | Dictionary | undefined;
+
+// "ns:a.b" reads dictionary.ns.a.b, so a namespace is just the top-level key.
+function path(key: string): string[] {
+	const ns = key.indexOf(":");
+	const parts = (ns === -1 ? key : key.slice(ns + 1)).split(".");
+	return ns === -1 ? parts : [key.slice(0, ns), ...parts];
+}
+
+function lookup(dict: Dictionary | undefined, key: string): Node {
+	let node: Node = dict;
+	for (const part of path(key)) {
 		if (!node || typeof node === "string") return undefined;
 		node = node[part];
 	}
-	return typeof node === "string" ? node : undefined;
+	return node;
+}
+
+const VARIABLE = /\{\{\s*(\w+)\s*\}\}|\{(\w+)\}/g;
+
+function interpolate(text: string, vars: TranslateVars): string {
+	return text.replace(VARIABLE, (match, double?: string, single?: string) => {
+		const value = vars[(double ?? single) as string];
+		return value === undefined || value === null ? match : String(value);
+	});
 }
 
-export function createI18n({ dictionaries, defaultLanguage }: I18nOptions) {
+export function createI18n({ dictionaries, defaultLanguage, detection = {} }: I18nOptions) {
 	const languages = Object.keys(dictionaries);
+	const supported = new Set(languages);
+	const storage = new AsyncLocalStorage<string>();
+	const pluralRules = new Map<string, Intl.PluralRules>();
+	const queryKey = detection.query ?? "lang";
+	const cookieName = detection.cookie ?? "lang";
+
+	function plural(language: string, count: number): string {
+		let rules = pluralRules.get(language);
+		if (!rules) {
+			rules = new Intl.PluralRules(language);
+			pluralRules.set(language, rules);
+		}
+		return rules.select(count);
+	}
+
+	/** `language` when it is supported, otherwise the default language. */
+	function resolveLanguage(language: string | null | undefined): string {
+		return language && supported.has(language) ? language : defaultLanguage;
+	}
+
+	function find(language: string, key: string, count: unknown): string | undefined {
+		for (const lang of language === defaultLanguage ? [language] : [language, defaultLanguage]) {
+			const dict = dictionaries[lang];
+			if (typeof count === "number") {
+				const forms = count === 0 ? ["zero", plural(lang, count)] : [plural(lang, count)];
+				for (const form of forms) {
+					const text = lookup(dict, `${key}_${form}`);
+					if (typeof text === "string") return text;
+				}
+			}
+			const text = lookup(dict, key);
+			if (typeof text === "string") return text;
+		}
+		return undefined;
+	}
+
+	/** Translates `key` ("errors.NOT_FOUND" or "errors:NOT_FOUND"), falling back to the default language, then `fallback`. */
+	function t(language: string, key: string, fallback = key, vars: TranslateVars = {}): string {
+		return interpolate(find(language, key, vars.count) ?? fallback, vars);
+	}
+
+	/** A translator for one language (unsupported → default); missing keys give `defaultValue`, else the key. */
+	function translator(language: string | null | undefined): Translator {
+		const lang = resolveLanguage(language);
+		return (key, vars = {}) => t(lang, key, vars.defaultValue ?? key, vars);
+	}
+
+	/** True when `key` has a string in `language` (or the default language). */
+	function exists(key: string, language: string = defaultLanguage): boolean {
+		return find(resolveLanguage(language), key, undefined) !== undefined;
+	}
+
+	/** The raw entry at `key` in one language's dictionary, no fallback: a string, a subtree or undefined. */
+	function resource(language: string, key: string): string | Dictionary | undefined {
+		return lookup(dictionaries[language], key);
+	}
 
-	/** Translates `key` ("errors.NOT_FOUND"), falling back to the default language, then `fallback`. */
-	function t(
+	/** The request's language inside `detectLanguage`/`withLanguage`, else the default language. */
+	function currentLanguage(): string {
+		return storage.getStore() ?? defaultLanguage;
+	}
+
+	/** Runs `fn` with `currentLanguage()` set to `language` (for jobs, CLI, tests). */
+	function withLanguage<T>(language: string, fn: () => T): T {
+		return storage.run(resolveLanguage(language), fn);
+	}
+
+	/** The value for `language` from per-language values (e.g. `{ en: row.nameEn, ar: row.nameAr }`); empty falls back to the default language. */
+	function pick(
 		language: string,
-		key: string,
-		fallback = key,
-		vars: Record<string, string> = {},
+		values: Partial<Record<string, string | null | undefined>>,
 	): string {
-		const text =
-			lookup(dictionaries[language], key) ?? lookup(dictionaries[defaultLanguage], key) ?? fallback;
-		return text.replace(/\{(\w+)\}/g, (_, name: string) => vars[name] ?? `{${name}}`);
+		return values[language] || values[defaultLanguage] || "";
 	}
 
-	/** ?lang, then the `lang` cookie, then Accept-Language; sets `c.var.language`. */
-	const detectLanguage = createMiddleware<{ Variables: { language: string } }>(async (c, next) => {
-		const candidates = [
-			c.req.query("lang"),
-			/(?:^|;\s*)lang=([^;]+)/.exec(c.req.header("cookie") ?? "")?.[1],
-			...(c.req.header("accept-language") ?? "")
-				.split(",")
-				.map((part) => part.split(";")[0]?.trim().toLowerCase().split("-")[0]),
-		];
-		const language = candidates.find((l) => l && languages.includes(l)) ?? defaultLanguage;
+	function accepted(header: string): string | undefined {
+		const ranked = header
+			.split(",")
+			.map((part, index) => {
+				const [tag = "", ...params] = part.trim().toLowerCase().split(";");
+				const q = params.map((p) => /^\s*q=([\d.]+)/.exec(p)?.[1]).find(Boolean);
+				return { tag: tag.trim(), q: q === undefined ? 1 : Number(q), index };
+			})
+			.filter((entry) => entry.tag && entry.q > 0)
+			.sort((a, b) => b.q - a.q || a.index - b.index);
+		for (const { tag } of ranked) {
+			const match = languages.find((l) => l.toLowerCase() === tag) ?? tag.split("-")[0];
+			if (match && supported.has(match)) return match;
+		}
+		return undefined;
+	}
+
+	function apply(c: Context, language: string, next: () => Promise<void>) {
 		c.set("language", language);
 		c.header("content-language", language);
-		await next();
+		return storage.run(language, next);
+	}
+
+	function explicitQuery(c: Context): string | undefined {
+		const value = queryKey ? c.req.query(queryKey) : undefined;
+		return value && supported.has(value) ? value : undefined;
+	}
+
+	/** ?lang, then the `lang` cookie, then Accept-Language; sets `c.var.language` and `currentLanguage()`. */
+	const detectLanguage = createMiddleware<{ Variables: { language: string } }>(async (c, next) => {
+		const fromCookie = cookieName ? getCookie(c, cookieName) : undefined;
+		const language =
+			explicitQuery(c) ??
+			(fromCookie && supported.has(fromCookie) ? fromCookie : undefined) ??
+			(detection.header === false ? undefined : accepted(c.req.header("accept-language") ?? "")) ??
+			defaultLanguage;
+		if (detection.persist && cookieName && fromCookie !== language)
+			setCookie(c, cookieName, language, detection.persist);
+		await apply(c, language, next);
 	}) as unknown as MiddlewareHandler<Env>;
 	// typed as adding nothing to the env, so it mounts on any app whose env has `language`
 
-	return { languages, t, detectLanguage };
+	/**
+	 * Replaces the detected language with `preferred(c)` (e.g. the signed-in user's stored
+	 * preference) when it is supported, unless the request asked for one with the query
+	 * parameter. Mount after `detectLanguage` and after whatever sets the user.
+	 */
+	function preferLanguage(
+		preferred: (c: Context) => string | null | undefined | Promise<string | null | undefined>,
+	): MiddlewareHandler<Env> {
+		return async (c, next) => {
+			if (explicitQuery(c)) return next();
+			const language = await preferred(c);
+			if (!language || !supported.has(language)) return next();
+			await apply(c, language, next);
+		};
+	}
+
+	return {
+		languages,
+		defaultLanguage,
+		t,
+		translator,
+		exists,
+		resource,
+		resolveLanguage,
+		currentLanguage,
+		withLanguage,
+		pick,
+		detectLanguage,
+		preferLanguage,
+	};
 }
+
+export type I18n = ReturnType<typeof createI18n>;

package/src/load.ts

@@ -0,0 +1,53 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Dictionary } from "./index.ts";
+
+export interface LoadDictionariesOptions {
+	/** holds `<language>/<namespace>.json`, e.g. `${process.cwd()}/locales` */
+	dir: string;
+	/** default: every sub-directory of `dir` */
+	languages?: readonly string[];
+	/** default: every `*.json` file found in any language */
+	namespaces?: readonly string[];
+	/** a namespace file one language lacks; that namespace is `{}` there */
+	onMissing?: (language: string, namespace: string) => void;
+}
+
+async function list(dir: string, pick: (name: string, isDir: boolean) => string | undefined) {
+	const entries = await readdir(dir, { withFileTypes: true });
+	return entries.flatMap((e) => pick(e.name, e.isDirectory()) ?? []).sort();
+}
+
+/**
+ * Reads `<dir>/<language>/<namespace>.json` into `{ [language]: { [namespace]: … } }`, so
+ * `t(language, "namespace:key")` finds them. Namespaces are discovered from the files.
+ */
+export async function loadDictionaries(
+	options: LoadDictionariesOptions,
+): Promise<Record<string, Dictionary>> {
+	const languages =
+		options.languages ?? (await list(options.dir, (name, isDir) => (isDir ? name : undefined)));
+	const files = new Map<string, string[]>();
+	for (const language of languages) {
+		const names = await list(join(options.dir, language), (name, isDir) =>
+			!isDir && name.endsWith(".json") ? name.slice(0, -".json".length) : undefined,
+		).catch(() => []);
+		files.set(language, names);
+	}
+	const namespaces = options.namespaces ?? [...new Set([...files.values()].flat())].sort();
+	const result: Record<string, Dictionary> = {};
+	for (const language of languages) {
+		const dictionary: Dictionary = {};
+		for (const namespace of namespaces) {
+			if (!files.get(language)?.includes(namespace)) {
+				options.onMissing?.(language, namespace);
+				dictionary[namespace] = {};
+				continue;
+			}
+			const text = await readFile(join(options.dir, language, `${namespace}.json`), "utf8");
+			dictionary[namespace] = JSON.parse(text) as Dictionary;
+		}
+		result[language] = dictionary;
+	}
+	return result;
+}

package/src/zod.ts

@@ -0,0 +1,66 @@
+import type { I18n } from "./index.ts";
+
+/** The fields of a zod issue the messages use; zod's own issue type is assignable to it. */
+export interface ZodIssueLike {
+	code?: string;
+	input?: unknown;
+	expected?: unknown;
+	minimum?: unknown;
+	maximum?: unknown;
+	values?: readonly unknown[];
+}
+
+export type ZodMessageKind =
+	| "required"
+	| "invalid_type"
+	| "too_small"
+	| "too_big"
+	| "invalid_format"
+	| "invalid_value"
+	| "custom";
+
+export interface ZodErrorMapOptions {
+	/** key prefix; a message's key is `${prefix}${kind}` (default "validation.") */
+	prefix?: string;
+	/** full keys for some kinds, overriding the prefix */
+	keys?: Partial<Record<ZodMessageKind, string>>;
+}
+
+function describe(issue: ZodIssueLike): [ZodMessageKind, Record<string, unknown>] | undefined {
+	switch (issue.code) {
+		case "invalid_type":
+			return issue.input === undefined
+				? ["required", {}]
+				: ["invalid_type", { expected: issue.expected, received: typeof issue.input }];
+		case "too_small":
+			return ["too_small", { minimum: String(issue.minimum) }];
+		case "too_big":
+			return ["too_big", { maximum: String(issue.maximum) }];
+		case "invalid_format":
+			return ["invalid_format", {}];
+		case "invalid_value":
+			return ["invalid_value", { options: (issue.values ?? []).map(String).join(", ") }];
+		case "custom":
+			return ["custom", {}];
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * A zod error map giving messages in `i18n.currentLanguage()` (the request's language under
+ * `detectLanguage`). Register it once: `z.config({ customError: zodErrorMap(i18n) })`.
+ * Kinds without a translation keep zod's own message.
+ */
+export function zodErrorMap(i18n: I18n, options: ZodErrorMapOptions = {}) {
+	const prefix = options.prefix ?? "validation.";
+	return (issue: ZodIssueLike): { message: string } | undefined => {
+		const described = describe(issue);
+		if (!described) return undefined;
+		const [kind, vars] = described;
+		const key = options.keys?.[kind] ?? `${prefix}${kind}`;
+		const language = i18n.currentLanguage();
+		if (!i18n.exists(key, language)) return undefined;
+		return { message: i18n.t(language, key, key, vars) };
+	};
+}