hanzio 3.0.0 → 3.1.0

package/src/format/index.ts

@@ -100,6 +100,26 @@ export function formatCurrency(
 	})
 }
 
+/**
+ * A price: whole amounts without minor units (`'2.500 kr.'`), fractional ones
+ * with the currency's usual digits (`'199,95 kr.'`) instead of rounding them
+ * into a price nobody charges.
+ */
+export function formatPrice(
+	amount: number,
+	currency: string,
+	locale: string
+): string {
+	return formatCurrency(
+		amount,
+		currency,
+		locale,
+		Number.isInteger(amount)
+			? { minimumFractionDigits: 0, maximumFractionDigits: 0 }
+			: undefined
+	)
+}
+
 /** Short compact notation: `1234` -> `"1.2K"` (en-US), `"1,2 t"` (da-DK). */
 export function formatCompactNumber(value: number, locale: string): string {
 	return formatNumber(value, locale, { notation: 'compact' })
@@ -355,6 +375,102 @@ export function formatDateRange(
 		: `${format.format(from)} – ${format.format(to)}`
 }
 
+// `hourCycle: 'h23'` on the `HH` presets: the name promises a 24-hour clock,
+// but `hour: '2-digit'` alone still renders "07:00 AM" under en-US.
+const DATE_PRESETS = {
+	'DD/MM/YYYY': { day: '2-digit', month: '2-digit', year: 'numeric' },
+	'DD/MM/YYYY HH:mm': {
+		day: '2-digit',
+		month: '2-digit',
+		year: 'numeric',
+		hour: '2-digit',
+		minute: '2-digit',
+		hourCycle: 'h23'
+	},
+	'HH:mm': { hour: '2-digit', minute: '2-digit', hourCycle: 'h23' },
+	ddd: { weekday: 'short' },
+	'D MMM': { day: 'numeric', month: 'short' },
+	'D MMM YYYY': { day: 'numeric', month: 'short', year: 'numeric' },
+	'dddd, MMMM D': { weekday: 'long', day: 'numeric', month: 'long' },
+	'MMMM YYYY': { month: 'long', year: 'numeric' }
+} as const satisfies Record<string, Intl.DateTimeFormatOptions>
+
+/**
+ * A named date layout. The names read like dayjs tokens, but the output
+ * follows the locale: `'D MMM'` is "5 Mar" in en-GB and "Mar 5" in en-US.
+ */
+export type DatePreset = keyof typeof DATE_PRESETS
+
+/** A date in one of the `DatePreset` layouts, in local time. */
+export function formatDate(
+	date: DateInput,
+	preset: DatePreset,
+	locale: string
+): string {
+	return getDateTimeFormat(locale, DATE_PRESETS[preset]).format(toTime(date))
+}
+
+/** Medium date and short time: "5 Mar 2026, 14:30" (en-GB). */
+export function formatDateTime(date: DateInput, locale: string): string {
+	return getDateTimeFormat(locale, {
+		dateStyle: 'medium',
+		timeStyle: 'short'
+	}).format(toTime(date))
+}
+
+/**
+ * Calendar days from today in local time: 0 today, -1 yesterday. Rounded,
+ * because a DST change makes one local day 23 or 25 hours long.
+ */
+function dayOffset(date: Date, now: Date): number {
+	const start = (d: Date) =>
+		new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+	return Math.round((start(date) - start(now)) / DAY_MS)
+}
+
+/** "today" / "yesterday" in the locale's own words. */
+const relativeDay = (offset: 0 | -1, locale: string) =>
+	getRelativeTimeFormat(locale, { numeric: 'auto' }).format(offset, 'day')
+
+/**
+ * Compact activity timestamp for a list row: the time today, "yesterday",
+ * else the date (with the year when it is not this year). Unparseable input
+ * returns `''`.
+ */
+export function formatCompactTime(
+	date: DateInput,
+	locale: string,
+	options: { now?: DateInput } = {}
+): string {
+	const value = new Date(toTime(date))
+	if (Number.isNaN(value.getTime())) return ''
+	const now = new Date(toTime(options.now ?? Date.now()))
+	const offset = dayOffset(value, now)
+	if (offset === 0) return formatDate(value, 'HH:mm', locale)
+	if (offset === -1) return relativeDay(-1, locale)
+	const sameYear = value.getFullYear() === now.getFullYear()
+	return formatDate(value, sameYear ? 'D MMM' : 'D MMM YYYY', locale)
+}
+
+/**
+ * Day-divider label for a chat timeline: "today", "yesterday", else weekday
+ * and date (with the year when it is not this year). Unparseable input
+ * returns `''`.
+ */
+export function formatDayDivider(
+	date: DateInput,
+	locale: string,
+	options: { now?: DateInput } = {}
+): string {
+	const value = new Date(toTime(date))
+	if (Number.isNaN(value.getTime())) return ''
+	const now = new Date(toTime(options.now ?? Date.now()))
+	const offset = dayOffset(value, now)
+	if (offset === 0 || offset === -1) return relativeDay(offset, locale)
+	const sameYear = value.getFullYear() === now.getFullYear()
+	return formatDate(value, sameYear ? 'dddd, MMMM D' : 'D MMM YYYY', locale)
+}
+
 /** "a, b, and c". Falls back to a comma join where `Intl.ListFormat` is missing. */
 export function formatList(
 	items: readonly string[],
@@ -369,6 +485,12 @@ export function formatList(
 
 // ─── Counts ─────────────────────────────────────────────────────────────────
 
+/**
+ * Stands for "no value" in a cell or detail row that must keep its height, so
+ * absent values cannot drift between a hyphen and an em dash. Not translated.
+ */
+export const EM_DASH = '—'
+
 /** Badge count: `150` -> `"99+"`. Negative or NaN is `"0"`. */
 export function formatCappedCount(count: number, max = 99): string {
 	if (!(count > 0)) return '0'
@@ -387,3 +509,29 @@ export function pluralize(
 	const form = forms[getPluralRules(locale).select(count)] ?? forms.other
 	return form.replaceAll('{count}', formatNumber(count, locale))
 }
+
+// ─── Bound to a locale ──────────────────────────────────────────────────────
+
+/**
+ * The date formatters with the locale read on every call, for apps whose
+ * locale lives in their i18n runtime:
+ * `export const fmt = withLocale(() => uiLocales.tag(appI18n.locale()))`.
+ */
+export function withLocale(getLocale: () => string) {
+	return {
+		formatDate: (date: DateInput, preset: DatePreset) =>
+			formatDate(date, preset, getLocale()),
+		formatDateTime: (date: DateInput) => formatDateTime(date, getLocale()),
+		formatCompactTime: (date: DateInput) =>
+			formatCompactTime(date, getLocale()),
+		formatDayDivider: (date: DateInput) => formatDayDivider(date, getLocale()),
+		formatRelativeTime: (
+			date: DateInput,
+			options?: FormatRelativeTimeOptions
+		) => formatRelativeTime(date, getLocale(), options),
+		formatNumber: (value: number, options?: Intl.NumberFormatOptions) =>
+			formatNumber(value, getLocale(), options),
+		formatPrice: (amount: number, currency: string) =>
+			formatPrice(amount, currency, getLocale())
+	}
+}

package/src/format/phone.ts

@@ -0,0 +1,43 @@
+// Phone numbers for people to read. Needs `libphonenumber-js` (its default
+// "min" metadata is about 84 KB, which is why this is not in `hanzio/format`).
+
+import {
+	isSupportedCountry,
+	parsePhoneNumberFromString
+} from 'libphonenumber-js'
+
+/**
+ * A stored phone number as a person reads it. `country` is the READER's ISO
+ * 3166-1 alpha-2 country (the organization's, say), not the number's: a local
+ * number prints the local way, any other with its country code.
+ *
+ * ```ts
+ * formatPhone('+4520304050', 'DK') // '20 30 40 50'
+ * formatPhone('+4520304050') // '+45 20 30 40 50'
+ * formatPhone('+4915112345678', 'DK') // '+49 1511 2345678'
+ * ```
+ *
+ * Nothing is lost: an unparseable value comes back trimmed but verbatim, and
+ * the national form is used only for a VALID number (`+4512345678` parses as
+ * DK but is not a real number, so it keeps its `+45`). A country
+ * libphonenumber cannot dial falls back to international. Empty input is
+ * `''`; the caller decides what stands in for "no number". Use the raw E.164
+ * value in `tel:` links.
+ */
+export function formatPhone(
+	value: string | null | undefined,
+	country?: string | null
+): string {
+	const raw = value?.trim() ?? ''
+	if (!raw) return ''
+	const region = country && isSupportedCountry(country) ? country : undefined
+	const parsed = parsePhoneNumberFromString(
+		raw,
+		region ? { defaultCountry: region } : undefined
+	)
+	if (!parsed) return raw
+	if (region && parsed.country === region && parsed.isValid()) {
+		return parsed.formatNational()
+	}
+	return parsed.formatInternational()
+}

package/src/http/README.md

@@ -0,0 +1,25 @@
+---
+description: SSE keep-alive comments and anti-buffering headers for streaming responses.
+---
+
+# hanzio/http
+
+Web-standard (`Response`, `TransformStream`), so it runs in Bun, Node and
+Workers.
+
+```ts
+import { withSseKeepAlive } from 'hanzio/http'
+
+return withSseKeepAlive(createUIMessageStreamResponse({ stream }))
+```
+
+`withSseKeepAlive(response, intervalMs = 15_000)` returns a copy of the
+response whose body writes an SSE comment (`:\n\n`) right away and again after
+every `intervalMs` without data, so proxy idle timers (Railway, nginx) don't
+close a stream that goes quiet. It also sets `Cache-Control: no-cache`,
+`X-Accel-Buffering: no` and `Connection: keep-alive`.
+
+`createSseKeepAliveTransform(intervalMs, timers?)` is the transform on its own,
+for a stream you pipe yourself; `timers` takes fake `setTimeout` /
+`clearTimeout` functions in tests. `SSE_KEEPALIVE_COMMENT` is the comment's
+bytes.

package/src/http/index.ts

@@ -0,0 +1,94 @@
+/**
+ * Byte-level SSE keep-alives. Empty `:` comments keep proxy and load-balancer
+ * idle timers (Railway, nginx) from resetting a stream that goes quiet, such
+ * as an LLM thinking or a slow tool call.
+ */
+const SSE_KEEPALIVE_INTERVAL_MS = 15_000
+export const SSE_KEEPALIVE_COMMENT = new TextEncoder().encode(':\n\n')
+
+function defaultClearTimeout(id: unknown) {
+	clearTimeout(id as ReturnType<typeof setTimeout>)
+}
+
+/** Passes bytes through, writing a comment first and after every `intervalMs` of silence. */
+export function createSseKeepAliveTransform(
+	intervalMs = SSE_KEEPALIVE_INTERVAL_MS,
+	timers: {
+		setTimeout: (fn: () => void, ms: number) => unknown
+		clearTimeout: (id: unknown) => void
+	} = { setTimeout, clearTimeout: defaultClearTimeout }
+) {
+	let timer: unknown
+	let closed = false
+	let enqueueKeepAlive: (() => void) | undefined
+
+	const clear = () => {
+		if (timer === undefined) return
+		timers.clearTimeout(timer)
+		timer = undefined
+	}
+
+	const arm = () => {
+		clear()
+		timer = timers.setTimeout(() => {
+			enqueueKeepAlive?.()
+		}, intervalMs)
+	}
+
+	return new TransformStream<Uint8Array, Uint8Array>(
+		{
+			start(controller) {
+				enqueueKeepAlive = () => {
+					if (closed) return
+					try {
+						controller.enqueue(SSE_KEEPALIVE_COMMENT)
+					} catch {
+						closed = true
+						clear()
+						return
+					}
+					arm()
+				}
+				// Immediate comment so the edge sees body bytes before the first
+				// event, which can take a long time to arrive.
+				enqueueKeepAlive()
+			},
+			transform(chunk, controller) {
+				if (closed) return
+				controller.enqueue(chunk)
+				arm()
+			},
+			flush() {
+				closed = true
+				clear()
+			}
+		},
+		{ highWaterMark: 16 },
+		{ highWaterMark: 16 }
+	)
+}
+
+/**
+ * Copies an SSE response with keep-alive comments in its body and headers that
+ * stop proxies from buffering it.
+ *
+ * @example
+ * return withSseKeepAlive(createUIMessageStreamResponse({ stream }))
+ */
+export function withSseKeepAlive(
+	response: Response,
+	intervalMs = SSE_KEEPALIVE_INTERVAL_MS
+) {
+	const headers = new Headers(response.headers)
+	headers.set('Cache-Control', 'no-cache')
+	headers.set('X-Accel-Buffering', 'no')
+	headers.set('Connection', 'keep-alive')
+	const body = response.body
+		? response.body.pipeThrough(createSseKeepAliveTransform(intervalMs))
+		: response.body
+	return new Response(body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	})
+}

package/src/i18n/README.md

@@ -1,11 +1,14 @@
 ---
-description: Typed `{name}` placeholders, interpolation and a small typed translator.
+description: Typed `{name}` placeholders, translators, locale registries, vue-i18n and i18next setup, and a catalog checker.
 ---
 
 # hanzio/i18n
 
-A typed helper for `{name}` message templates, not an i18n framework: no
-plurals, ICU, locale negotiation or escaping.
+Typed `{name}` message templates and the glue around an i18n framework: a
+locale registry, typed `t` for vue-i18n and i18next, their setup, and a
+`hanzio-i18n` bin that checks JSON catalogs and generates their key maps.
+`hanzio/i18n` itself has no dependencies; plurals and ICU syntax are the
+framework's job.
 
 ```ts
 import { createTranslator, extractPlaceholders, interpolate } from 'hanzio/i18n'
@@ -63,3 +66,203 @@ messages inline or `as const` so the templates stay literal; with plain
 and params are optional. A key that is missing at runtime returns the key.
 
 `flattenMessages(messages)` gives the flat map: `{ 'common.save': 'Save', greeting: 'Hi {name}' }`.
+
+## Typed `t` for a framework
+
+`hanzio-i18n generate` writes a key → placeholder-name map from your base
+catalog (see [Catalog checks](#catalog-checks)). `TypedTranslate<Params>`
+turns it into a strict `t`, and `typedTranslate` narrows a framework's `t`:
+
+```ts
+import { typedTranslate } from 'hanzio/i18n'
+import type { AppTranslationParams } from './locales/i18n.generated'
+
+// { 'common.save': never; 'greeting': 'name' }
+export const t = typedTranslate<AppTranslationParams>(i18n.t.bind(i18n))
+
+t('greeting', { name: 'Ada' })
+t('greeting') // type error: params required
+t('common.save', { name: 'Ada' }) // type error: no placeholders
+```
+
+`DynamicTranslate` is the explicit escape hatch for data-driven keys.
+
+## Locales
+
+`defineLocales` is the one list of shipped UI locales, shared by every runtime
+and the catalog check:
+
+```ts
+import { defineLocales, type LocaleOf } from 'hanzio/i18n'
+
+export const uiLocales = defineLocales({
+	locales: {
+		en: { tag: 'en-US', name: 'English' },
+		da: { tag: 'da-DK', name: 'Dansk' },
+		nb: { tag: 'nb-NO', name: 'Norsk bokmål' }
+	},
+	defaultLocale: 'en',
+	aliases: { no: 'nb' }
+})
+export type UiLocale = LocaleOf<typeof uiLocales> // 'en' | 'da' | 'nb'
+
+uiLocales.match('da_DK') // 'da' (id, tag, language subtag, then aliases)
+uiLocales.match('no-NO') // 'nb'
+uiLocales.resolve(saved, navigator.language) // first match, else 'en'
+uiLocales.tag('da') // 'da-DK', for Intl
+uiLocales.name('nb') // 'Norsk bokmål', for pickers
+```
+
+Ids name the catalog files (`da.json`). A server enum such as `da_DK` matches
+too, and `tag(locale).replace('-', '_')` goes the other way.
+
+`createLocaleSelector` switches the locale at once and rolls back when saving
+the choice fails:
+
+```ts
+const selectLocale = createLocaleSelector({
+	getLocale: () => locale.value,
+	setLocale,
+	persist: (locale) => api.user.updateLocale({ locale }),
+	onError: () => toast.error(t('settings.language.error'))
+})
+```
+
+## vue-i18n
+
+`hanzio/i18n/vue` needs `vue-i18n`. `createVueI18n` calls `createI18n` in
+composition mode, starting in the persisted locale, then the browser language,
+then the default (also the fallback). `messages` needs a catalog for every
+locale in the registry. `setLocale` switches, persists and sets `<html lang>`.
+Other options go to `createI18n` unchanged.
+
+```ts
+import { createVueI18n } from 'hanzio/i18n/vue'
+
+export const { i18n, setLocale, useI18n } = createVueI18n({
+	locales: uiLocales,
+	messages: { en, da, nb },
+	storageKey: 'app.ui-locale',
+	datetimeFormats: { en: dateFormats, da: dateFormats, nb: dateFormats }
+})
+
+// The app's only useI18n: locale is UiLocale, t is checked against the map.
+export const useAppI18n = () => useI18n<AppTranslationParams>()
+```
+
+The stored value is the raw locale id. After sign-in, call `setLocale` with the
+user's saved locale so pre-auth screens match on the next visit.
+
+`hanzio/i18n/vite` has `localeCatalogReloadPlugin()`, a dev-server plugin for
+`@intlify/unplugin-vue-i18n`: an edited `locales/*.json` reloads the page with
+fresh catalogs instead of serving the old ones until a restart. Pass
+`{ match }` if your catalogs are not in `locales` folders.
+
+## i18next
+
+`hanzio/i18n/i18next` takes your `i18next` instance (`.use(initReactI18next)`
+first for React). It starts in the persisted locale, then the first supported
+device locale, then the default, and interpolates `{name}` without escaping,
+the same syntax the rest of this module uses.
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { getLocales } from 'expo-localization'
+import i18n from 'i18next'
+import { initReactI18next } from 'react-i18next'
+import { initI18next } from 'hanzio/i18n/i18next'
+
+export const appI18n = initI18next(i18n.use(initReactI18next), {
+	locales: uiLocales,
+	resources: { en: { translation: en }, da: { translation: da } },
+	deviceLocales: () => getLocales().flatMap((l) => [l.languageTag, l.languageCode]),
+	storageKey: 'app.ui-locale',
+	storage: AsyncStorage
+})
+
+await appI18n.ready // before the first render
+appI18n.locale() // 'da'
+await appI18n.setLocale('en') // switches and persists
+await appI18n.syncLocale(me?.locale) // follow the user's saved locale; unknown tags do nothing
+```
+
+Other options go to `i18n.init`. Type `useTranslation()`'s `t` with
+`typedTranslate`.
+
+## Catalog checks
+
+The `hanzio-i18n` bin checks catalogs stored as one JSON file per locale
+(`<dir>/<locale>.json`), with the base locale as the source of truth:
+
+```bash
+hanzio-i18n check     # fails with one line per problem
+hanzio-i18n generate  # writes each catalog's generatedTypes
+```
+
+Both read `i18n.config.ts` (or `.mts`, `.js`, `.mjs`, or `--config <file>`)
+from the current directory; paths in it are relative to the config file.
+`defineI18nConfig` rejects a `baseLocale`, `disjointNamespaces` catalog or
+`identical.allowKeys` locale the config does not declare. A
+`.ts` config needs Bun, or a Node version that strips types. The bin is built
+on [`hanzio/cli`](../cli/README.md), so it needs `zod` installed; `--help`
+lists its options and it exits 1 on catalog problems, 2 on bad arguments.
+
+```ts
+import { defineI18nConfig } from 'hanzio/i18n/check'
+import { uiLocales } from './src/locales'
+
+export default defineI18nConfig({
+	baseLocale: 'en',
+	locales: uiLocales.locales,
+	catalogs: [
+		{
+			name: 'platform',
+			dir: 'apps/platform/src/locales',
+			runtime: 'vue-i18n',
+			generatedTypes: 'apps/platform/src/locales/i18n.generated.ts',
+			generatedTypeName: 'PlatformTranslationParams',
+			sourceRoots: ['apps/platform/src'],
+			dynamicKeyPrefixes: ['entities.']
+		},
+		{ name: 'expo', dir: 'apps/expo/src/locales', runtime: 'i18next' }
+	],
+	disjointNamespaces: [['platform', 'widget']],
+	rules: {
+		exemptKeyPrefixes: ['admin.'],
+		bannedWords: { translations: ['workflow', 'payload'] },
+		wrongLanguage: { markers: ['og', 'til', 'ikke', 'vi'], letters: 'æøåÆØÅ' },
+		identical: { brands: ['Acme'], allowKeys: { 'common.send': ['da', 'nb'] } }
+	}
+})
+```
+
+What `check` reports:
+
+- Locale files missing from `locales`, or not in it.
+- Leaves that are not strings, empty or dotted key segments, text that is not
+  NFC-normalized, likely mojibake (`æ`).
+- Keys missing from or stale in a translation, and placeholder sets that
+  differ from the base value.
+- Values that look like source code (`row.name`, `carTitle(car)`,
+  `LABELS[key]`, `x ?? y`), in every locale. `rules.allowCodeShapes` lists the
+  exceptions.
+- Translations of two or more words identical to the base value: an untranslated
+  label or sentence. Single words, brands, acronyms, paths and URLs, and
+  `rules.identical.allowKeys` are allowed.
+- With `rules.wrongLanguage`: base values written in that language (two marker
+  words, or one plus one of its `letters`).
+- With `rules.bannedWords`: `everywhere` words in any catalog, `translations`
+  words outside the base. Placeholders never count.
+- `runtime: 'vue-i18n'`: HTML and syntax that vue-i18n's `strictMessage`
+  compile rejects. Install `@intlify/message-compiler` for this.
+- `sourceRoots`: keys no source file references. Any dotted path in a file
+  counts, and `` `prefix.${x}` `` keeps a whole family; `dynamicKeyPrefixes`
+  keeps families built from data.
+- `generatedTypes` files that do not match the base catalog.
+- `disjointNamespaces`: catalogs merged into one runtime that share a
+  top-level key.
+
+`runtime` also decides plural keys in the generated map: vue-i18n's `a | b`
+messages and i18next's `key_one`/`key_other` (merged into `key`) take a
+`count`. The same checks are available as `validateCatalogs(config, { root })`
+and `writeCatalogTypes(config, { root })`.

package/src/i18n/catalog.ts

@@ -0,0 +1,139 @@
+import { isPlainObject } from '../guard'
+import { extractPlaceholders, flattenMessages, type Messages } from '.'
+
+/** How a catalog's runtime reads its messages: plural syntax and escaping. */
+export type CatalogRuntime = 'vue-i18n' | 'i18next' | 'plain'
+
+export type CatalogConfig = {
+	/** Shown in check output. */
+	name: string
+	/** Folder of `<locale>.json` files, relative to the config file. */
+	dir: string
+	runtime: CatalogRuntime
+	/** Where `hanzio-i18n generate` writes the key → placeholder map. */
+	generatedTypes?: string
+	/** Exported type name in `generatedTypes`. Default `TranslationParams`. */
+	generatedTypeName?: string
+	/**
+	 * Source folders scanned for key references. Set them and the check also
+	 * fails on keys nothing references. Leave unset when keys are built at
+	 * runtime from a prefix (`t(\`widget.${key}\`)` everywhere), since every key
+	 * would read as used.
+	 */
+	sourceRoots?: readonly string[]
+	/**
+	 * Key prefixes composed from data rather than written in source (labels
+	 * sent by the backend, for example), kept even when nothing references them.
+	 * A prefix a template literal spells out is found by the scan already.
+	 */
+	dynamicKeyPrefixes?: readonly string[]
+}
+
+export type CatalogIssue = {
+	catalog: string
+	locale?: string
+	message: string
+}
+
+const MOJIBAKE = /(?:Ã.|Â.|â€|�)/
+const I18NEXT_PLURAL_SUFFIX = /_(zero|one|two|few|many|other)$/
+
+/**
+ * Validates one parsed JSON catalog: every leaf a string, no empty or dotted
+ * key segments, NFC-normalized text and no mojibake.
+ */
+export function parseMessages(
+	value: unknown,
+	catalog: string,
+	locale: string
+): { messages?: Messages; issues: CatalogIssue[] } {
+	const issues: CatalogIssue[] = []
+	const issue = (message: string) => issues.push({ catalog, locale, message })
+
+	function visit(node: unknown, path: string): string | Messages | undefined {
+		if (typeof node === 'string') {
+			if (node.normalize('NFC') !== node) {
+				issue(`"${path}" is not Unicode NFC-normalized`)
+			}
+			if (MOJIBAKE.test(node)) issue(`"${path}" contains likely mojibake`)
+			return node
+		}
+		if (!isPlainObject(node)) {
+			issue(`"${path || '<root>'}" must be an object or string`)
+			return undefined
+		}
+		const result: Record<string, string | Messages> = {}
+		for (const [key, child] of Object.entries(node)) {
+			if (!key || key.includes('.')) {
+				issue(`"${path ? `${path}.` : ''}${key}" has an invalid key segment`)
+				continue
+			}
+			const parsed = visit(child, path ? `${path}.${key}` : key)
+			if (parsed !== undefined) result[key] = parsed
+		}
+		return result
+	}
+
+	const messages = visit(value, '')
+	return {
+		messages: typeof messages === 'object' ? messages : undefined,
+		issues
+	}
+}
+
+export function flattenCatalog(messages: Messages): Map<string, string> {
+	return new Map(Object.entries(flattenMessages(messages)))
+}
+
+const quote = (value: string) =>
+	`'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
+
+/**
+ * The TypeScript key → placeholder-name map for `TypedTranslate`, generated
+ * from the base catalog. Plural messages also take `count`: vue-i18n's
+ * `a | b | c` forms, and i18next's `key_one`/`key_other` (merged into `key`).
+ */
+export function generateCatalogTypes(
+	catalog: Pick<CatalogConfig, 'runtime' | 'generatedTypeName'>,
+	baseMessages: Messages,
+	command = 'hanzio-i18n generate'
+): string {
+	const entries = new Map<string, Set<string>>()
+
+	for (const [rawKey, template] of flattenCatalog(baseMessages)) {
+		const isI18nextPlural =
+			catalog.runtime === 'i18next' && I18NEXT_PLURAL_SUFFIX.test(rawKey)
+		const key = isI18nextPlural
+			? rawKey.replace(I18NEXT_PLURAL_SUFFIX, '')
+			: rawKey
+		const params = entries.get(key) ?? new Set<string>()
+		for (const name of extractPlaceholders(template)) params.add(name)
+		const isVuePlural =
+			catalog.runtime === 'vue-i18n' &&
+			template
+				.split('|')
+				.map((part) => part.trim())
+				.filter(Boolean).length > 1
+		if (isVuePlural || isI18nextPlural) params.add('count')
+		entries.set(key, params)
+	}
+
+	const lines = [...entries]
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([key, params]) => {
+			const value =
+				params.size === 0 ? 'never' : [...params].sort().map(quote).join(' | ')
+			return `\t${quote(key)}: ${value}`
+		})
+
+	return [
+		'/**',
+		` * Generated by \`${command}\` from the base catalog.`,
+		' * Do not edit by hand.',
+		' */',
+		`export type ${catalog.generatedTypeName ?? 'TranslationParams'} = {`,
+		...lines,
+		'}',
+		''
+	].join('\n')
+}