@facilis.dev/i18n-db 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 facilis-dev
+
+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

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @facilis.dev/i18n-db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+database i18n: translated content fields plus an optional catalogue overlay
+
+Part of [Facilis](https://github.com/facilis-dev/facilis), a browser-first low-code framework: the Studio
+runs a generated project in a WebContainer where vite dev is the only dev server
+and Nitro v3 runs as a Vite plugin. Framework contracts live in
+[docs/SPEC.md](https://github.com/facilis-dev/facilis/blob/main/docs/SPEC.md) and architectural decisions in
+[docs/DECISIONS.md](https://github.com/facilis-dev/facilis/blob/main/docs/DECISIONS.md).
+
+```sh
+npm install @facilis.dev/i18n-db
+```
+
+The package publishes its TypeScript sources and its compiled dist/; the exports map
+of the published manifest points at dist/, so Node and bundlers load JavaScript and
+the bundled .d.ts files.
+
+Licensed under the MIT License.

package/dist/catalog.d.ts

@@ -0,0 +1,31 @@
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+import { z } from "zod";
+/** A flat key/value catalogue for one locale (O-001: flat keys). */
+export type I18nCatalog = Record<string, string>;
+/** Every catalogue for the requested locales, each keyed by message key. */
+export type I18nCatalogs = Record<string, I18nCatalog>;
+/**
+ * Query schema the project route passes to `defineAuthorizedHandler`: `?locales=en,it`,
+ * default "en". It is exported (not wrapped in a handler) so the route's config literal is
+ * visible to the Nitro AST metadata pass (security invariant 2).
+ */
+export declare const catalogQuery: z.ZodObject<{
+    locales: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/** `"en, it ,en"` -> `["en","it"]`; a blank list falls back to the contract default. */
+export declare function parseCatalogLocales(raw: string): string[];
+/**
+ * Reads one locale through the caller's policy-scoped database. RLS restricts the rows to
+ * `app.tenant_id`, so no tenant id is ever part of the query.
+ */
+export declare function loadCatalog(db: PolicyScopedDatabase, locale: string): Promise<I18nCatalog>;
+/**
+ * Reads several locales in one round trip. Requested locales with no rows still appear as
+ * empty catalogues so the route response has a stable shape.
+ */
+export declare function loadCatalogs(db: PolicyScopedDatabase, locales: readonly string[]): Promise<I18nCatalogs>;
+/**
+ * Upserts every key of one locale (seeding/admin). The tenant comes from the insert default,
+ * i.e. the policy-scope GUC, and `excluded.value` makes a re-save overwrite the old text.
+ */
+export declare function saveCatalog(db: PolicyScopedDatabase, locale: string, messages: I18nCatalog): Promise<void>;

package/dist/catalog.js

@@ -0,0 +1,73 @@
+import { inArray, sql } from "drizzle-orm";
+import { z } from "zod";
+import { i18nMessages } from "./messages.js";
+/**
+ * Query schema the project route passes to `defineAuthorizedHandler`: `?locales=en,it`,
+ * default "en". It is exported (not wrapped in a handler) so the route's config literal is
+ * visible to the Nitro AST metadata pass (security invariant 2).
+ */
+export const catalogQuery = z.object({
+    locales: z.string().default("en"),
+});
+/** `"en, it ,en"` -> `["en","it"]`; a blank list falls back to the contract default. */
+export function parseCatalogLocales(raw) {
+    const locales = raw
+        .split(",")
+        .map((locale) => locale.trim())
+        .filter((locale) => locale.length > 0);
+    return locales.length === 0 ? ["en"] : [...new Set(locales)];
+}
+/**
+ * Reads one locale through the caller's policy-scoped database. RLS restricts the rows to
+ * `app.tenant_id`, so no tenant id is ever part of the query.
+ */
+export async function loadCatalog(db, locale) {
+    const rows = await db
+        .select({ key: i18nMessages.key, value: i18nMessages.value })
+        .from(i18nMessages)
+        .where(sql `${i18nMessages.locale} = ${locale}`)
+        .orderBy(i18nMessages.key);
+    return Object.fromEntries(rows.map((row) => [row.key, row.value]));
+}
+/**
+ * Reads several locales in one round trip. Requested locales with no rows still appear as
+ * empty catalogues so the route response has a stable shape.
+ */
+export async function loadCatalogs(db, locales) {
+    const catalogs = Object.fromEntries(locales.map((locale) => [locale, {}]));
+    if (locales.length === 0)
+        return catalogs;
+    const rows = await db
+        .select({
+        locale: i18nMessages.locale,
+        key: i18nMessages.key,
+        value: i18nMessages.value,
+    })
+        .from(i18nMessages)
+        .where(inArray(i18nMessages.locale, [...locales]))
+        .orderBy(i18nMessages.locale, i18nMessages.key);
+    for (const row of rows) {
+        const catalog = catalogs[row.locale];
+        // inArray() guarantees this, but the record is indexed so keep the narrowing explicit.
+        if (catalog === undefined)
+            continue;
+        catalog[row.key] = row.value;
+    }
+    return catalogs;
+}
+/**
+ * Upserts every key of one locale (seeding/admin). The tenant comes from the insert default,
+ * i.e. the policy-scope GUC, and `excluded.value` makes a re-save overwrite the old text.
+ */
+export async function saveCatalog(db, locale, messages) {
+    const rows = Object.entries(messages).map(([key, value]) => ({ locale, key, value }));
+    if (rows.length === 0)
+        return;
+    await db
+        .insert(i18nMessages)
+        .values(rows)
+        .onConflictDoUpdate({
+        target: [i18nMessages.tenantId, i18nMessages.locale, i18nMessages.key],
+        set: { value: sql `excluded.value`, updatedAt: sql `now()` },
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+export { matchLocale, normalizeLocale, parseAcceptLanguage, resolveTranslation, resolveUserLocale, translationsSchema, type ResolveUserLocaleOptions, type Translations, } from "./translations.js";
+export interface HydrateCatalogsOptions {
+    /** Locales to load; every one is registered, even when the database has no rows for it. */
+    readonly locales: readonly string[];
+    /** Bundled JSON catalogues; DB rows win per key and missing rows fall back here. */
+    readonly base?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** Applied with `setDefaultLocale` after registration when given. */
+    readonly defaultLocale?: string;
+    /** Catalogue endpoint; defaults to "/api/i18n". */
+    readonly endpoint?: string;
+}
+/**
+ * Fetches the DB catalogue overlay, merges it over the bundled JSON per key and registers
+ * every locale (D-057). Throws on a failed request, a network error or a malformed payload
+ * so the caller can decide (the docs show the try/catch); it never logs.
+ */
+export declare function hydrateCatalogs(options: HydrateCatalogsOptions): Promise<void>;

package/dist/client.js

@@ -0,0 +1,61 @@
+import { registerCatalog, setDefaultLocale } from "@facilis.dev/core/i18n";
+// The browser half also exposes the pure locale/translation helpers so a generated app can
+// resolve content without a second import; the column helper and Drizzle stay server-only.
+export { matchLocale, normalizeLocale, parseAcceptLanguage, resolveTranslation, resolveUserLocale, translationsSchema, } from "./translations.js";
+const DEFAULT_ENDPOINT = "/api/i18n";
+/**
+ * Fetches the DB catalogue overlay, merges it over the bundled JSON per key and registers
+ * every locale (D-057). Throws on a failed request, a network error or a malformed payload
+ * so the caller can decide (the docs show the try/catch); it never logs.
+ */
+export async function hydrateCatalogs(options) {
+    const { locales, base, defaultLocale, endpoint = DEFAULT_ENDPOINT } = options;
+    const remote = await fetchCatalogs(endpoint, locales);
+    for (const locale of locales) {
+        // Spreading a missing catalogue is a no-op, which is exactly the per-key fallback.
+        registerCatalog(locale, { ...base?.[locale], ...remote[locale] });
+    }
+    if (defaultLocale !== undefined)
+        setDefaultLocale(defaultLocale);
+}
+async function fetchCatalogs(endpoint, locales) {
+    // The endpoint may already carry a query string; append rather than replace it.
+    const separator = endpoint.includes("?") ? "&" : "?";
+    const url = `${endpoint}${separator}locales=${encodeURIComponent(locales.join(","))}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`i18n: catalogue request failed with HTTP ${response.status}`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (cause) {
+        throw new Error("i18n: catalogue response is not valid JSON", { cause });
+    }
+    return validateCatalogs(payload);
+}
+/** Validates `{ "<locale>": { "<key>": "<value>" } }` by hand: the client has no zod. */
+function validateCatalogs(payload) {
+    if (!isRecord(payload)) {
+        throw new Error("i18n: catalogue response must be a JSON object");
+    }
+    const catalogs = {};
+    for (const [locale, rawCatalog] of Object.entries(payload)) {
+        if (!isRecord(rawCatalog)) {
+            throw new Error(`i18n: catalogue for "${locale}" must be a JSON object`);
+        }
+        const catalog = {};
+        for (const [key, value] of Object.entries(rawCatalog)) {
+            if (typeof value !== "string") {
+                throw new Error(`i18n: message "${key}" for "${locale}" must be a string`);
+            }
+            catalog[key] = value;
+        }
+        catalogs[locale] = catalog;
+    }
+    return catalogs;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/columns.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A translatable content field: one NOT NULL `jsonb` column holding `{ locale: text }`.
+ * A project schema re-exports this helper (`title: translatedText("title")`) and lets
+ * drizzle-kit generate the migration; the package ships none.
+ */
+export declare function translatedText(name: string): import("drizzle-orm").NotNull<import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<string>, Readonly<Record<string, string>>>>;

package/dist/columns.js

@@ -0,0 +1,9 @@
+import { jsonb } from "drizzle-orm/pg-core";
+/**
+ * A translatable content field: one NOT NULL `jsonb` column holding `{ locale: text }`.
+ * A project schema re-exports this helper (`title: translatedText("title")`) and lets
+ * drizzle-kit generate the migration; the package ships none.
+ */
+export function translatedText(name) {
+    return jsonb(name).$type().notNull();
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@facilis.dev/i18n-db` — database i18n for generated projects: translated content fields
+ * (a typed `jsonb` column + locale resolution) and the optional database catalogue overlay.
+ *
+ * The root entry point is server-only (Drizzle + policy-scoped DB). The browser half lives
+ * behind the `@facilis.dev/i18n-db/client` subpath so a client bundle never pulls drizzle.
+ */
+export { translatedText } from "./columns.js";
+export { matchLocale, normalizeLocale, parseAcceptLanguage, resolveTranslation, resolveUserLocale, translationsSchema, type ResolveUserLocaleOptions, type Translations, } from "./translations.js";
+export { i18nMessages, type I18nMessageRow } from "./messages.js";
+export { catalogQuery, loadCatalog, loadCatalogs, parseCatalogLocales, saveCatalog, type I18nCatalog, type I18nCatalogs, } from "./catalog.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@facilis.dev/i18n-db` — database i18n for generated projects: translated content fields
+ * (a typed `jsonb` column + locale resolution) and the optional database catalogue overlay.
+ *
+ * The root entry point is server-only (Drizzle + policy-scoped DB). The browser half lives
+ * behind the `@facilis.dev/i18n-db/client` subpath so a client bundle never pulls drizzle.
+ */
+export { translatedText } from "./columns.js";
+export { matchLocale, normalizeLocale, parseAcceptLanguage, resolveTranslation, resolveUserLocale, translationsSchema, } from "./translations.js";
+export { i18nMessages } from "./messages.js";
+export { catalogQuery, loadCatalog, loadCatalogs, parseCatalogLocales, saveCatalog, } from "./catalog.js";

package/dist/messages.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Tenant-scoped catalogue overlay (D-057): one row per locale/key, unique per tenant.
+ *
+ * The JSON catalogues of `@facilis.dev/core/i18n` stay the base; these rows win key by key.
+ * A project re-exports this table from its `db/schema.ts` and lets drizzle-kit generate
+ * the migration — the package intentionally ships no migration.
+ */
+export declare const i18nMessages: Omit<import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "i18n_messages";
+    schema: undefined;
+    columns: {
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "i18n_messages";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        locale: import("drizzle-orm/pg-core").PgColumn<{
+            name: "locale";
+            tableName: "i18n_messages";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        key: import("drizzle-orm/pg-core").PgColumn<{
+            name: "key";
+            tableName: "i18n_messages";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        value: import("drizzle-orm/pg-core").PgColumn<{
+            name: "value";
+            tableName: "i18n_messages";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "i18n_messages";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>, "enableRLS">;
+export type I18nMessageRow = typeof i18nMessages.$inferSelect;

package/dist/messages.js

@@ -0,0 +1,30 @@
+import { sql } from "drizzle-orm";
+import { pgPolicy, pgTable, primaryKey, text, timestamp } from "drizzle-orm/pg-core";
+import { tenantColumn, tenantIsolationPolicy } from "@facilis.dev/db";
+/**
+ * Tenant-scoped catalogue overlay (D-057): one row per locale/key, unique per tenant.
+ *
+ * The JSON catalogues of `@facilis.dev/core/i18n` stay the base; these rows win key by key.
+ * A project re-exports this table from its `db/schema.ts` and lets drizzle-kit generate
+ * the migration — the package intentionally ships no migration.
+ */
+export const i18nMessages = pgTable("i18n_messages", {
+    // The insert never names the tenant; the column takes it from the policy-scope GUC,
+    // so raw SQL and app code are both held to the deployment tenant (D-040).
+    tenantId: tenantColumn(),
+    locale: text("locale").notNull(),
+    key: text("key").notNull(),
+    value: text("value").notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow(),
+}, (table) => [
+    primaryKey({ columns: [table.tenantId, table.locale, table.key] }),
+    tenantIsolationPolicy(),
+    // A RESTRICTIVE policy only narrows the rows a permissive policy already allows; with
+    // no permissive policy Postgres denies every row (D-008). This clause admits the scoped
+    // tenant and the restrictive tenant_isolation AND's it down to that tenant's rows.
+    pgPolicy("i18n_messages_tenant_access", {
+        for: "all",
+        using: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+        withCheck: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+]).enableRLS();

package/dist/test-support.d.ts

@@ -0,0 +1,8 @@
+import { type FacilisDb } from "@facilis.dev/db";
+/**
+ * Hand-written DDL matching ./messages.ts exactly (no drizzle-kit in tests): column names,
+ * types, nullability, the GUC tenant default and the composite primary key.
+ */
+export declare const I18N_MESSAGES_TABLE_STATEMENTS: readonly string[];
+/** Boots an in-memory PGlite database with the catalogue table, its RLS policies and the app role. */
+export declare function createI18nTestDb(): Promise<FacilisDb>;

package/dist/test-support.js

@@ -0,0 +1,28 @@
+import { getTableConfig } from "drizzle-orm/pg-core";
+import { applyStatements, createDb, ensureAppRole, policyCreateSql, } from "@facilis.dev/db";
+import { i18nMessages } from "./messages.js";
+/**
+ * Hand-written DDL matching ./messages.ts exactly (no drizzle-kit in tests): column names,
+ * types, nullability, the GUC tenant default and the composite primary key.
+ */
+export const I18N_MESSAGES_TABLE_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS i18n_messages (
+    tenant_id uuid NOT NULL DEFAULT nullif(current_setting('app.tenant_id', true), '')::uuid,
+    locale text NOT NULL,
+    key text NOT NULL,
+    value text NOT NULL,
+    updated_at timestamp with time zone DEFAULT now(),
+    PRIMARY KEY (tenant_id, locale, key)
+  )`,
+];
+function policyStatements() {
+    const policies = getTableConfig(i18nMessages).policies.map((policy) => policyCreateSql("i18n_messages", policy));
+    return ["ALTER TABLE i18n_messages ENABLE ROW LEVEL SECURITY", ...policies];
+}
+/** Boots an in-memory PGlite database with the catalogue table, its RLS policies and the app role. */
+export async function createI18nTestDb() {
+    const db = await createDb();
+    await applyStatements(db, [...I18N_MESSAGES_TABLE_STATEMENTS, ...policyStatements()]);
+    await ensureAppRole(db);
+    return db;
+}

package/dist/translations.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * A text stored as a map of locale tag -> translated string, e.g.
+ * `{ en: "Todo", it: "Da fare" }`. The raw value is what the database stores and what
+ * admin/edit APIs accept; serving maps a row through `resolveTranslation`.
+ */
+export type Translations = Readonly<Record<string, string>>;
+/**
+ * Validates admin/edit payloads: every key must be a structurally valid locale tag and
+ * every value a non-empty string. Keys stay verbatim; matching normalizes them later, so
+ * `{ "IT": "Ciao" }` is stored as written but still served for `it`.
+ */
+export declare const translationsSchema: z.ZodType<Translations>;
+/** Intl-canonical form of a locale tag (`it-ch` -> `it-CH`), or null when it is invalid. */
+export declare function normalizeLocale(tag: string): string | null;
+/**
+ * Picks the supported tag matching `locale`: exact canonical match, then its base language
+ * (`it-CH` -> `it`), then any supported variant of that language. `fallback` is returned
+ * when the tag is invalid or unsupported, so callers always get a usable locale.
+ */
+export declare function matchLocale(locale: string | undefined, supported: readonly string[], fallback: string): string;
+/** Parses Accept-Language: q-ordered (stable ties), canonicalized, no wildcard, no q=0. */
+export declare function parseAcceptLanguage(header: string | null | undefined): string[];
+export interface ResolveUserLocaleOptions {
+    /** Saved preference (e.g. a profile column); wins over the request header. */
+    readonly userLocale?: string | null;
+    /** Raw Accept-Language header; second in precedence. */
+    readonly acceptLanguage?: string | null;
+    /** Application locales to filter candidates through; omitted/empty means no filter. */
+    readonly supported?: readonly string[];
+    /** Last resort; defaults to "en". */
+    readonly defaultLocale?: string;
+}
+/**
+ * Resolves the language a request should be served in: saved preference, then
+ * Accept-Language tags in q-order, then the default — each filtered by `supported`.
+ * Storing the preference is the app's job; this only resolves it.
+ */
+export declare function resolveUserLocale(options: ResolveUserLocaleOptions): string;
+/**
+ * Serves only one language: exact locale, then its base language (`it-CH` -> `it`), then
+ * `fallbackLocale`, then the first non-empty value, else "". Tolerates null/malformed row
+ * data (it can predate the schema) and never throws.
+ */
+export declare function resolveTranslation(value: Translations | null | undefined, locale: string, fallbackLocale?: string): string;

package/dist/translations.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+/**
+ * Validates admin/edit payloads: every key must be a structurally valid locale tag and
+ * every value a non-empty string. Keys stay verbatim; matching normalizes them later, so
+ * `{ "IT": "Ciao" }` is stored as written but still served for `it`.
+ */
+export const translationsSchema = z
+    .record(z.string(), z.string().min(1))
+    .superRefine((value, ctx) => {
+    for (const tag of Object.keys(value)) {
+        if (normalizeLocale(tag) === null) {
+            ctx.addIssue({
+                code: "custom",
+                message: `"${tag}" is not a valid locale tag`,
+                path: [tag],
+            });
+        }
+    }
+});
+/** Intl-canonical form of a locale tag (`it-ch` -> `it-CH`), or null when it is invalid. */
+export function normalizeLocale(tag) {
+    try {
+        const [canonical] = Intl.getCanonicalLocales(tag.trim());
+        return canonical ?? null;
+    }
+    catch {
+        // Intl throws RangeError for malformed tags; invalid input is a value, not a crash.
+        return null;
+    }
+}
+/**
+ * Picks the supported tag matching `locale`: exact canonical match, then its base language
+ * (`it-CH` -> `it`), then any supported variant of that language. `fallback` is returned
+ * when the tag is invalid or unsupported, so callers always get a usable locale.
+ */
+export function matchLocale(locale, supported, fallback) {
+    return findSupportedLocale(locale, supported) ?? fallback;
+}
+/** Parses Accept-Language: q-ordered (stable ties), canonicalized, no wildcard, no q=0. */
+export function parseAcceptLanguage(header) {
+    if (header === null || header === undefined || header.trim() === "")
+        return [];
+    const ranked = [];
+    header.split(",").forEach((part, index) => {
+        const [rawTag, ...parameters] = part.split(";");
+        const tag = rawTag?.trim() ?? "";
+        // "*" means "anything else": it cannot resolve to a concrete language.
+        if (tag === "" || tag === "*")
+            return;
+        let q = 1;
+        for (const parameter of parameters) {
+            const [name, rawValue] = parameter.split("=");
+            if (name?.trim().toLowerCase() !== "q")
+                continue;
+            const parsed = Number.parseFloat(rawValue ?? "");
+            q = Number.isNaN(parsed) ? 1 : Math.min(Math.max(parsed, 0), 1);
+        }
+        if (q <= 0)
+            return;
+        const normalized = normalizeLocale(tag);
+        if (normalized === null)
+            return;
+        ranked.push({ tag: normalized, q, index });
+    });
+    const ordered = ranked
+        .toSorted((left, right) => right.q - left.q || left.index - right.index)
+        .map((entry) => entry.tag);
+    return ordered.filter((tag, index) => ordered.indexOf(tag) === index);
+}
+/**
+ * Resolves the language a request should be served in: saved preference, then
+ * Accept-Language tags in q-order, then the default — each filtered by `supported`.
+ * Storing the preference is the app's job; this only resolves it.
+ */
+export function resolveUserLocale(options) {
+    const { userLocale, acceptLanguage, supported, defaultLocale = "en" } = options;
+    const candidates = supported !== undefined && supported.length > 0 ? supported : null;
+    for (const tag of [userLocale ?? undefined, ...parseAcceptLanguage(acceptLanguage)]) {
+        if (tag === undefined)
+            continue;
+        const resolved = candidates === null
+            ? (normalizeLocale(tag) ?? undefined)
+            : findSupportedLocale(tag, candidates);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return candidates === null
+        ? (normalizeLocale(defaultLocale) ?? defaultLocale)
+        : (findSupportedLocale(defaultLocale, candidates) ?? defaultLocale);
+}
+/**
+ * Serves only one language: exact locale, then its base language (`it-CH` -> `it`), then
+ * `fallbackLocale`, then the first non-empty value, else "". Tolerates null/malformed row
+ * data (it can predate the schema) and never throws.
+ */
+export function resolveTranslation(value, locale, fallbackLocale = "en") {
+    const source = value;
+    if (typeof source !== "object" || source === null || Array.isArray(source))
+        return "";
+    const entries = [];
+    for (const [key, rawValue] of Object.entries(source)) {
+        if (typeof rawValue === "string")
+            entries.push([key, rawValue]);
+    }
+    const exact = lookupLocale(entries, locale);
+    if (exact !== undefined)
+        return exact;
+    const normalized = normalizeLocale(locale);
+    const base = normalized === null ? undefined : lookupLocale(entries, baseLanguage(normalized));
+    if (base !== undefined)
+        return base;
+    const fallback = lookupLocale(entries, fallbackLocale);
+    if (fallback !== undefined)
+        return fallback;
+    return entries.find(([, text]) => text.length > 0)?.[1] ?? "";
+}
+function findSupportedLocale(locale, supported) {
+    if (locale === null || locale === undefined)
+        return undefined;
+    const normalized = normalizeLocale(locale);
+    if (normalized === null)
+        return undefined;
+    const base = baseLanguage(normalized);
+    const variants = supported.map((tag) => ({ tag, normalized: normalizeLocale(tag) }));
+    const exact = variants.find((entry) => entry.normalized === normalized);
+    if (exact !== undefined)
+        return exact.tag;
+    const baseExact = variants.find((entry) => entry.normalized === base);
+    if (baseExact !== undefined)
+        return baseExact.tag;
+    return variants.find((entry) => entry.normalized?.startsWith(`${base}-`))?.tag;
+}
+function lookupLocale(entries, tag) {
+    const normalized = normalizeLocale(tag);
+    if (normalized === null)
+        return undefined;
+    for (const [key, text] of entries) {
+        // Empty values are treated as absent so the fallback chain can still serve something.
+        if (text.length > 0 && normalizeLocale(key) === normalized)
+            return text;
+    }
+    return undefined;
+}
+function baseLanguage(normalized) {
+    return normalized.split("-")[0] ?? normalized;
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@facilis.dev/i18n-db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "database i18n: translated content fields plus an optional catalogue overlay",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./dist/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "dependencies": {
+    "@facilis.dev/core": "0.1.0",
+    "@facilis.dev/db": "0.1.0",
+    "drizzle-orm": "0.45.4",
+    "zod": "4.6.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facilis-dev/facilis.git",
+    "directory": "packages/i18n-db"
+  },
+  "homepage": "https://github.com/facilis-dev/facilis/tree/main/packages/i18n-db#readme",
+  "bugs": {
+    "url": "https://github.com/facilis-dev/facilis/issues"
+  },
+  "keywords": [
+    "facilis",
+    "framework",
+    "vite",
+    "nitro",
+    "low-code"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/catalog.ts

@@ -0,0 +1,93 @@
+import { inArray, sql } from "drizzle-orm";
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+import { z } from "zod";
+
+import { i18nMessages } from "./messages.ts";
+
+/** A flat key/value catalogue for one locale (O-001: flat keys). */
+export type I18nCatalog = Record<string, string>;
+
+/** Every catalogue for the requested locales, each keyed by message key. */
+export type I18nCatalogs = Record<string, I18nCatalog>;
+
+/**
+ * Query schema the project route passes to `defineAuthorizedHandler`: `?locales=en,it`,
+ * default "en". It is exported (not wrapped in a handler) so the route's config literal is
+ * visible to the Nitro AST metadata pass (security invariant 2).
+ */
+export const catalogQuery = z.object({
+  locales: z.string().default("en"),
+});
+
+/** `"en, it ,en"` -> `["en","it"]`; a blank list falls back to the contract default. */
+export function parseCatalogLocales(raw: string): string[] {
+  const locales = raw
+    .split(",")
+    .map((locale) => locale.trim())
+    .filter((locale) => locale.length > 0);
+  return locales.length === 0 ? ["en"] : [...new Set(locales)];
+}
+
+/**
+ * Reads one locale through the caller's policy-scoped database. RLS restricts the rows to
+ * `app.tenant_id`, so no tenant id is ever part of the query.
+ */
+export async function loadCatalog(db: PolicyScopedDatabase, locale: string): Promise<I18nCatalog> {
+  const rows = await db
+    .select({ key: i18nMessages.key, value: i18nMessages.value })
+    .from(i18nMessages)
+    .where(sql`${i18nMessages.locale} = ${locale}`)
+    .orderBy(i18nMessages.key);
+  return Object.fromEntries(rows.map((row) => [row.key, row.value]));
+}
+
+/**
+ * Reads several locales in one round trip. Requested locales with no rows still appear as
+ * empty catalogues so the route response has a stable shape.
+ */
+export async function loadCatalogs(
+  db: PolicyScopedDatabase,
+  locales: readonly string[],
+): Promise<I18nCatalogs> {
+  const catalogs: I18nCatalogs = Object.fromEntries(locales.map((locale) => [locale, {}]));
+  if (locales.length === 0) return catalogs;
+
+  const rows = await db
+    .select({
+      locale: i18nMessages.locale,
+      key: i18nMessages.key,
+      value: i18nMessages.value,
+    })
+    .from(i18nMessages)
+    .where(inArray(i18nMessages.locale, [...locales]))
+    .orderBy(i18nMessages.locale, i18nMessages.key);
+
+  for (const row of rows) {
+    const catalog = catalogs[row.locale];
+    // inArray() guarantees this, but the record is indexed so keep the narrowing explicit.
+    if (catalog === undefined) continue;
+    catalog[row.key] = row.value;
+  }
+  return catalogs;
+}
+
+/**
+ * Upserts every key of one locale (seeding/admin). The tenant comes from the insert default,
+ * i.e. the policy-scope GUC, and `excluded.value` makes a re-save overwrite the old text.
+ */
+export async function saveCatalog(
+  db: PolicyScopedDatabase,
+  locale: string,
+  messages: I18nCatalog,
+): Promise<void> {
+  const rows = Object.entries(messages).map(([key, value]) => ({ locale, key, value }));
+  if (rows.length === 0) return;
+
+  await db
+    .insert(i18nMessages)
+    .values(rows)
+    .onConflictDoUpdate({
+      target: [i18nMessages.tenantId, i18nMessages.locale, i18nMessages.key],
+      set: { value: sql`excluded.value`, updatedAt: sql`now()` },
+    });
+}

package/src/client.ts

@@ -0,0 +1,91 @@
+import { registerCatalog, setDefaultLocale } from "@facilis.dev/core/i18n";
+
+// The browser half also exposes the pure locale/translation helpers so a generated app can
+// resolve content without a second import; the column helper and Drizzle stay server-only.
+export {
+  matchLocale,
+  normalizeLocale,
+  parseAcceptLanguage,
+  resolveTranslation,
+  resolveUserLocale,
+  translationsSchema,
+  type ResolveUserLocaleOptions,
+  type Translations,
+} from "./translations.ts";
+
+export interface HydrateCatalogsOptions {
+  /** Locales to load; every one is registered, even when the database has no rows for it. */
+  readonly locales: readonly string[];
+  /** Bundled JSON catalogues; DB rows win per key and missing rows fall back here. */
+  readonly base?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  /** Applied with `setDefaultLocale` after registration when given. */
+  readonly defaultLocale?: string;
+  /** Catalogue endpoint; defaults to "/api/i18n". */
+  readonly endpoint?: string;
+}
+
+const DEFAULT_ENDPOINT = "/api/i18n";
+
+/**
+ * Fetches the DB catalogue overlay, merges it over the bundled JSON per key and registers
+ * every locale (D-057). Throws on a failed request, a network error or a malformed payload
+ * so the caller can decide (the docs show the try/catch); it never logs.
+ */
+export async function hydrateCatalogs(options: HydrateCatalogsOptions): Promise<void> {
+  const { locales, base, defaultLocale, endpoint = DEFAULT_ENDPOINT } = options;
+  const remote = await fetchCatalogs(endpoint, locales);
+
+  for (const locale of locales) {
+    // Spreading a missing catalogue is a no-op, which is exactly the per-key fallback.
+    registerCatalog(locale, { ...base?.[locale], ...remote[locale] });
+  }
+  if (defaultLocale !== undefined) setDefaultLocale(defaultLocale);
+}
+
+async function fetchCatalogs(
+  endpoint: string,
+  locales: readonly string[],
+): Promise<Record<string, Record<string, string>>> {
+  // The endpoint may already carry a query string; append rather than replace it.
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${endpoint}${separator}locales=${encodeURIComponent(locales.join(","))}`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`i18n: catalogue request failed with HTTP ${response.status}`);
+  }
+
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch (cause) {
+    throw new Error("i18n: catalogue response is not valid JSON", { cause });
+  }
+  return validateCatalogs(payload);
+}
+
+/** Validates `{ "<locale>": { "<key>": "<value>" } }` by hand: the client has no zod. */
+function validateCatalogs(payload: unknown): Record<string, Record<string, string>> {
+  if (!isRecord(payload)) {
+    throw new Error("i18n: catalogue response must be a JSON object");
+  }
+
+  const catalogs: Record<string, Record<string, string>> = {};
+  for (const [locale, rawCatalog] of Object.entries(payload)) {
+    if (!isRecord(rawCatalog)) {
+      throw new Error(`i18n: catalogue for "${locale}" must be a JSON object`);
+    }
+    const catalog: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawCatalog)) {
+      if (typeof value !== "string") {
+        throw new Error(`i18n: message "${key}" for "${locale}" must be a string`);
+      }
+      catalog[key] = value;
+    }
+    catalogs[locale] = catalog;
+  }
+  return catalogs;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/columns.ts

@@ -0,0 +1,12 @@
+import { jsonb } from "drizzle-orm/pg-core";
+
+import type { Translations } from "./translations.ts";
+
+/**
+ * A translatable content field: one NOT NULL `jsonb` column holding `{ locale: text }`.
+ * A project schema re-exports this helper (`title: translatedText("title")`) and lets
+ * drizzle-kit generate the migration; the package ships none.
+ */
+export function translatedText(name: string) {
+  return jsonb(name).$type<Translations>().notNull();
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * `@facilis.dev/i18n-db` — database i18n for generated projects: translated content fields
+ * (a typed `jsonb` column + locale resolution) and the optional database catalogue overlay.
+ *
+ * The root entry point is server-only (Drizzle + policy-scoped DB). The browser half lives
+ * behind the `@facilis.dev/i18n-db/client` subpath so a client bundle never pulls drizzle.
+ */
+
+export { translatedText } from "./columns.ts";
+export {
+  matchLocale,
+  normalizeLocale,
+  parseAcceptLanguage,
+  resolveTranslation,
+  resolveUserLocale,
+  translationsSchema,
+  type ResolveUserLocaleOptions,
+  type Translations,
+} from "./translations.ts";
+export { i18nMessages, type I18nMessageRow } from "./messages.ts";
+export {
+  catalogQuery,
+  loadCatalog,
+  loadCatalogs,
+  parseCatalogLocales,
+  saveCatalog,
+  type I18nCatalog,
+  type I18nCatalogs,
+} from "./catalog.ts";

package/src/messages.ts

@@ -0,0 +1,38 @@
+import { sql } from "drizzle-orm";
+import { pgPolicy, pgTable, primaryKey, text, timestamp } from "drizzle-orm/pg-core";
+
+import { tenantColumn, tenantIsolationPolicy } from "@facilis.dev/db";
+
+/**
+ * Tenant-scoped catalogue overlay (D-057): one row per locale/key, unique per tenant.
+ *
+ * The JSON catalogues of `@facilis.dev/core/i18n` stay the base; these rows win key by key.
+ * A project re-exports this table from its `db/schema.ts` and lets drizzle-kit generate
+ * the migration — the package intentionally ships no migration.
+ */
+export const i18nMessages = pgTable(
+  "i18n_messages",
+  {
+    // The insert never names the tenant; the column takes it from the policy-scope GUC,
+    // so raw SQL and app code are both held to the deployment tenant (D-040).
+    tenantId: tenantColumn(),
+    locale: text("locale").notNull(),
+    key: text("key").notNull(),
+    value: text("value").notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.tenantId, table.locale, table.key] }),
+    tenantIsolationPolicy(),
+    // A RESTRICTIVE policy only narrows the rows a permissive policy already allows; with
+    // no permissive policy Postgres denies every row (D-008). This clause admits the scoped
+    // tenant and the restrictive tenant_isolation AND's it down to that tenant's rows.
+    pgPolicy("i18n_messages_tenant_access", {
+      for: "all",
+      using: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+      withCheck: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+  ],
+).enableRLS();
+
+export type I18nMessageRow = typeof i18nMessages.$inferSelect;

package/src/test-support.ts

@@ -0,0 +1,41 @@
+import { getTableConfig } from "drizzle-orm/pg-core";
+
+import {
+  applyStatements,
+  createDb,
+  ensureAppRole,
+  policyCreateSql,
+  type FacilisDb,
+} from "@facilis.dev/db";
+
+import { i18nMessages } from "./messages.ts";
+
+/**
+ * Hand-written DDL matching ./messages.ts exactly (no drizzle-kit in tests): column names,
+ * types, nullability, the GUC tenant default and the composite primary key.
+ */
+export const I18N_MESSAGES_TABLE_STATEMENTS: readonly string[] = [
+  `CREATE TABLE IF NOT EXISTS i18n_messages (
+    tenant_id uuid NOT NULL DEFAULT nullif(current_setting('app.tenant_id', true), '')::uuid,
+    locale text NOT NULL,
+    key text NOT NULL,
+    value text NOT NULL,
+    updated_at timestamp with time zone DEFAULT now(),
+    PRIMARY KEY (tenant_id, locale, key)
+  )`,
+];
+
+function policyStatements(): readonly string[] {
+  const policies = getTableConfig(i18nMessages).policies.map((policy) =>
+    policyCreateSql("i18n_messages", policy),
+  );
+  return ["ALTER TABLE i18n_messages ENABLE ROW LEVEL SECURITY", ...policies];
+}
+
+/** Boots an in-memory PGlite database with the catalogue table, its RLS policies and the app role. */
+export async function createI18nTestDb(): Promise<FacilisDb> {
+  const db = await createDb();
+  await applyStatements(db, [...I18N_MESSAGES_TABLE_STATEMENTS, ...policyStatements()]);
+  await ensureAppRole(db);
+  return db;
+}

package/src/translations.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+
+/**
+ * A text stored as a map of locale tag -> translated string, e.g.
+ * `{ en: "Todo", it: "Da fare" }`. The raw value is what the database stores and what
+ * admin/edit APIs accept; serving maps a row through `resolveTranslation`.
+ */
+export type Translations = Readonly<Record<string, string>>;
+
+/**
+ * Validates admin/edit payloads: every key must be a structurally valid locale tag and
+ * every value a non-empty string. Keys stay verbatim; matching normalizes them later, so
+ * `{ "IT": "Ciao" }` is stored as written but still served for `it`.
+ */
+export const translationsSchema: z.ZodType<Translations> = z
+  .record(z.string(), z.string().min(1))
+  .superRefine((value, ctx) => {
+    for (const tag of Object.keys(value)) {
+      if (normalizeLocale(tag) === null) {
+        ctx.addIssue({
+          code: "custom",
+          message: `"${tag}" is not a valid locale tag`,
+          path: [tag],
+        });
+      }
+    }
+  });
+
+/** Intl-canonical form of a locale tag (`it-ch` -> `it-CH`), or null when it is invalid. */
+export function normalizeLocale(tag: string): string | null {
+  try {
+    const [canonical] = Intl.getCanonicalLocales(tag.trim());
+    return canonical ?? null;
+  } catch {
+    // Intl throws RangeError for malformed tags; invalid input is a value, not a crash.
+    return null;
+  }
+}
+
+/**
+ * Picks the supported tag matching `locale`: exact canonical match, then its base language
+ * (`it-CH` -> `it`), then any supported variant of that language. `fallback` is returned
+ * when the tag is invalid or unsupported, so callers always get a usable locale.
+ */
+export function matchLocale(
+  locale: string | undefined,
+  supported: readonly string[],
+  fallback: string,
+): string {
+  return findSupportedLocale(locale, supported) ?? fallback;
+}
+
+/** Parses Accept-Language: q-ordered (stable ties), canonicalized, no wildcard, no q=0. */
+export function parseAcceptLanguage(header: string | null | undefined): string[] {
+  if (header === null || header === undefined || header.trim() === "") return [];
+
+  const ranked: { tag: string; q: number; index: number }[] = [];
+  header.split(",").forEach((part, index) => {
+    const [rawTag, ...parameters] = part.split(";");
+    const tag = rawTag?.trim() ?? "";
+    // "*" means "anything else": it cannot resolve to a concrete language.
+    if (tag === "" || tag === "*") return;
+
+    let q = 1;
+    for (const parameter of parameters) {
+      const [name, rawValue] = parameter.split("=");
+      if (name?.trim().toLowerCase() !== "q") continue;
+      const parsed = Number.parseFloat(rawValue ?? "");
+      q = Number.isNaN(parsed) ? 1 : Math.min(Math.max(parsed, 0), 1);
+    }
+    if (q <= 0) return;
+
+    const normalized = normalizeLocale(tag);
+    if (normalized === null) return;
+    ranked.push({ tag: normalized, q, index });
+  });
+
+  const ordered = ranked
+    .toSorted((left, right) => right.q - left.q || left.index - right.index)
+    .map((entry) => entry.tag);
+  return ordered.filter((tag, index) => ordered.indexOf(tag) === index);
+}
+
+export interface ResolveUserLocaleOptions {
+  /** Saved preference (e.g. a profile column); wins over the request header. */
+  readonly userLocale?: string | null;
+  /** Raw Accept-Language header; second in precedence. */
+  readonly acceptLanguage?: string | null;
+  /** Application locales to filter candidates through; omitted/empty means no filter. */
+  readonly supported?: readonly string[];
+  /** Last resort; defaults to "en". */
+  readonly defaultLocale?: string;
+}
+
+/**
+ * Resolves the language a request should be served in: saved preference, then
+ * Accept-Language tags in q-order, then the default — each filtered by `supported`.
+ * Storing the preference is the app's job; this only resolves it.
+ */
+export function resolveUserLocale(options: ResolveUserLocaleOptions): string {
+  const { userLocale, acceptLanguage, supported, defaultLocale = "en" } = options;
+  const candidates = supported !== undefined && supported.length > 0 ? supported : null;
+
+  for (const tag of [userLocale ?? undefined, ...parseAcceptLanguage(acceptLanguage)]) {
+    if (tag === undefined) continue;
+    const resolved =
+      candidates === null
+        ? (normalizeLocale(tag) ?? undefined)
+        : findSupportedLocale(tag, candidates);
+    if (resolved !== undefined) return resolved;
+  }
+
+  return candidates === null
+    ? (normalizeLocale(defaultLocale) ?? defaultLocale)
+    : (findSupportedLocale(defaultLocale, candidates) ?? defaultLocale);
+}
+
+/**
+ * Serves only one language: exact locale, then its base language (`it-CH` -> `it`), then
+ * `fallbackLocale`, then the first non-empty value, else "". Tolerates null/malformed row
+ * data (it can predate the schema) and never throws.
+ */
+export function resolveTranslation(
+  value: Translations | null | undefined,
+  locale: string,
+  fallbackLocale = "en",
+): string {
+  const source: unknown = value;
+  if (typeof source !== "object" || source === null || Array.isArray(source)) return "";
+
+  const entries: [string, string][] = [];
+  for (const [key, rawValue] of Object.entries(source)) {
+    if (typeof rawValue === "string") entries.push([key, rawValue]);
+  }
+
+  const exact = lookupLocale(entries, locale);
+  if (exact !== undefined) return exact;
+
+  const normalized = normalizeLocale(locale);
+  const base = normalized === null ? undefined : lookupLocale(entries, baseLanguage(normalized));
+  if (base !== undefined) return base;
+
+  const fallback = lookupLocale(entries, fallbackLocale);
+  if (fallback !== undefined) return fallback;
+
+  return entries.find(([, text]) => text.length > 0)?.[1] ?? "";
+}
+
+function findSupportedLocale(
+  locale: string | null | undefined,
+  supported: readonly string[],
+): string | undefined {
+  if (locale === null || locale === undefined) return undefined;
+  const normalized = normalizeLocale(locale);
+  if (normalized === null) return undefined;
+  const base = baseLanguage(normalized);
+
+  const variants = supported.map((tag) => ({ tag, normalized: normalizeLocale(tag) }));
+  const exact = variants.find((entry) => entry.normalized === normalized);
+  if (exact !== undefined) return exact.tag;
+  const baseExact = variants.find((entry) => entry.normalized === base);
+  if (baseExact !== undefined) return baseExact.tag;
+  return variants.find((entry) => entry.normalized?.startsWith(`${base}-`))?.tag;
+}
+
+function lookupLocale(entries: readonly [string, string][], tag: string): string | undefined {
+  const normalized = normalizeLocale(tag);
+  if (normalized === null) return undefined;
+  for (const [key, text] of entries) {
+    // Empty values are treated as absent so the fallback chain can still serve something.
+    if (text.length > 0 && normalizeLocale(key) === normalized) return text;
+  }
+  return undefined;
+}
+
+function baseLanguage(normalized: string): string {
+  return normalized.split("-")[0] ?? normalized;
+}