@urbicon-ui/i18n 6.3.8 → 6.3.10

package/dist/audit/translations.js

@@ -0,0 +1,207 @@
+/**
+ * `auditTranslations` — data-level translation quality & parity audit.
+ *
+ * The richer successor to {@link validatePackageTranslations}: a pure function
+ * over a package's locale bundles (no source scan, no I/O, deterministic, zero
+ * false positives) that reports structured findings instead of opaque strings.
+ *
+ * Consumers run it in a vitest test to fail CI on drift —
+ * `expect(auditTranslations('app', bundles).ok).toBe(true)` — or via the
+ * `urbicon i18n parity` CLI, which formats the same findings. Key parity is the
+ * baseline (missing/extra keys); on top of it sit the checks a structural diff
+ * can't see: empty values, interpolation-param drift between locales, malformed
+ * or CLDR-incomplete `_plural` objects, placeholder leftovers, and (opt-in)
+ * not-yet-translated strings identical to the base locale.
+ */
+import { isLocaleSupported, SUPPORTED_LOCALES } from '../i18n/types.js';
+import { collectDeepKeys, getDeepValue } from '../utils/deep-keys.js';
+import { makeGlobMatcher } from './glob.js';
+/** Defaults: everything on except the FP-prone, opt-in `same-as-base`. */
+const DEFAULT_CHECKS = {
+    'missing-key': true,
+    'extra-key': true,
+    'empty-value': true,
+    'wrong-type': true,
+    'param-mismatch': true,
+    'plural-shape-invalid': true,
+    'plural-category-incomplete': true,
+    'value-equals-key': true,
+    'same-as-base': false,
+    'invalid-locale': true,
+    'no-translations': true
+};
+/** Same `{{param}}` syntax the runtime interpolates (`registry.interpolate`). */
+const PARAM_RE = /\{\{([^}]+)\}\}/g;
+/** The interpolation params a template references, e.g. `Hello {{name}}` → `{name}`. */
+function extractParamNames(template) {
+    const names = new Set();
+    for (const match of template.matchAll(PARAM_RE))
+        names.add(match[1].trim());
+    return names;
+}
+/** CLDR cardinal categories required for `locale`, e.g. `en` → [one, other]. */
+function requiredPluralCategories(locale) {
+    return new Intl.PluralRules(locale).resolvedOptions().pluralCategories;
+}
+/** A leaf value is "translatable" (worth a same-as-base check) if it has a letter. */
+function isTranslatable(value) {
+    return value.trim().length >= 2 && /\p{L}/u.test(value);
+}
+/** Readable type label for a wrong-type finding (`array`/`null` over the bare typeof). */
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+const LOCALE_ORDER = ['en', 'de', 'fr', 'es', 'it', 'nl'];
+function localeRank(locale) {
+    const i = LOCALE_ORDER.indexOf(locale);
+    return i === -1 ? LOCALE_ORDER.length : i;
+}
+/**
+ * Audit a package's locale bundles for parity and translation-quality issues.
+ *
+ * @param packageName Used only to prefix `detail` messages (e.g. `[blocks]`).
+ * @param translations Per-locale bundles, exactly as passed to `createPackageI18n`.
+ */
+export function auditTranslations(packageName, translations, options = {}) {
+    const checks = { ...DEFAULT_CHECKS, ...options.checks, 'missing-key': true };
+    const isIgnored = makeGlobMatcher(options.ignoreKeys);
+    const findings = [];
+    const add = (code, severity, locale, key, message) => {
+        if (!checks[code])
+            return;
+        findings.push({ code, severity, locale, key, detail: `[${packageName}] ${message}` });
+    };
+    const locales = Object.keys(translations);
+    const baseLocale = options.baseLocale ?? (locales.includes('en') ? 'en' : locales[0]) ?? 'en';
+    const baseBundle = translations[baseLocale];
+    if (!baseBundle || locales.length === 0) {
+        add('no-translations', 'error', baseLocale, '', locales.length === 0
+            ? 'no translations provided'
+            : `base locale ${baseLocale} has no translations`);
+        return finalize(findings);
+    }
+    const baseKeys = collectDeepKeys(baseBundle);
+    const baseKeySet = new Set(baseKeys);
+    const baseValueOf = (key) => {
+        const value = getDeepValue(baseBundle, key);
+        return typeof value === 'string' ? value : undefined;
+    };
+    // Value-level checks run on EVERY locale (the base included — an empty or
+    // malformed base entry is a defect regardless). Parity checks compare each
+    // non-base locale against the base.
+    for (const locale of locales) {
+        const bundle = translations[locale];
+        if (!bundle)
+            continue;
+        // Guard before any per-value work: an unsupported tag (a typo like `de_DE`)
+        // would otherwise crash `Intl.PluralRules(locale)` and take the whole audit
+        // down. Report it as a finding and skip the locale — fail-loud, not fatal.
+        if (!isLocaleSupported(locale)) {
+            add('invalid-locale', 'error', locale, '', `unknown locale "${locale}" — not one of ${SUPPORTED_LOCALES.join(', ')}`);
+            continue;
+        }
+        const keys = collectDeepKeys(bundle);
+        const keySet = new Set(keys);
+        for (const key of keys) {
+            if (isIgnored(key))
+                continue;
+            const value = getDeepValue(bundle, key);
+            if (typeof value !== 'string') {
+                // `collectDeepKeys` treats empty objects and arrays as leaves, so a
+                // non-string leaf shares its path across bundles and the key-diff can't
+                // see it. Translations leaves must be strings — report, don't skip.
+                add('wrong-type', 'error', locale, key, `non-string value at "${key}" (${describeType(value)})`);
+                continue;
+            }
+            if (value.trim() === '') {
+                // A non-base hole over a non-empty base is a user-facing regression
+                // (empty string renders); an empty base entry is merely suspicious.
+                const baseHasContent = locale !== baseLocale && (baseValueOf(key) ?? '').trim() !== '';
+                add('empty-value', baseHasContent ? 'error' : 'warning', locale, key, `empty value at "${key}"`);
+            }
+            if (value === key) {
+                add('value-equals-key', 'warning', locale, key, `value equals its key at "${key}"`);
+            }
+            if (key.endsWith('_plural')) {
+                auditPluralValue(value, locale, key, add, checks);
+            }
+        }
+        if (locale === baseLocale)
+            continue;
+        for (const key of baseKeys) {
+            if (isIgnored(key))
+                continue;
+            if (!keySet.has(key))
+                add('missing-key', 'error', locale, key, `missing key "${key}"`);
+        }
+        for (const key of keys) {
+            if (isIgnored(key))
+                continue;
+            if (!baseKeySet.has(key))
+                add('extra-key', 'warning', locale, key, `extra key "${key}"`);
+        }
+        // Param / same-as-base checks need the same leaf present (as a string) in both.
+        for (const key of keys) {
+            if (isIgnored(key) || !baseKeySet.has(key))
+                continue;
+            const value = getDeepValue(bundle, key);
+            const baseValue = baseValueOf(key);
+            if (typeof value !== 'string' || baseValue === undefined)
+                continue;
+            const baseParams = extractParamNames(baseValue);
+            const localeParams = extractParamNames(value);
+            const missing = [...baseParams].filter((p) => !localeParams.has(p));
+            const extra = [...localeParams].filter((p) => !baseParams.has(p));
+            if (missing.length || extra.length) {
+                const parts = [
+                    missing.length ? `missing {{${missing.join('}}, {{')}}}` : '',
+                    extra.length ? `unexpected {{${extra.join('}}, {{')}}}` : ''
+                ].filter(Boolean);
+                add('param-mismatch', 'error', locale, key, `param drift at "${key}": ${parts.join('; ')}`);
+            }
+            if (value === baseValue && isTranslatable(baseValue)) {
+                add('same-as-base', 'warning', locale, key, `value identical to ${baseLocale} at "${key}"`);
+            }
+        }
+    }
+    return finalize(findings);
+}
+/** Parse a `<key>_plural` JSON object and flag malformed shape / missing CLDR forms. */
+function auditPluralValue(value, locale, key, add, checks) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        add('plural-shape-invalid', 'error', locale, key, `_plural value at "${key}" is not valid JSON`);
+        return;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        add('plural-shape-invalid', 'error', locale, key, `_plural value at "${key}" is not an object`);
+        return;
+    }
+    const forms = parsed;
+    if (typeof forms.other !== 'string') {
+        add('plural-shape-invalid', 'error', locale, key, `_plural object at "${key}" lacks a string "other" form`);
+        return;
+    }
+    if (!checks['plural-category-incomplete'])
+        return;
+    const missing = requiredPluralCategories(locale).filter((cat) => typeof forms[cat] !== 'string');
+    if (missing.length) {
+        add('plural-category-incomplete', 'warning', locale, key, `_plural object at "${key}" is missing CLDR form(s) for ${locale}: ${missing.join(', ')}`);
+    }
+}
+/** Sort deterministically (locale → key → code) and split by severity. */
+function finalize(findings) {
+    findings.sort((a, b) => localeRank(a.locale) - localeRank(b.locale) ||
+        a.key.localeCompare(b.key) ||
+        a.code.localeCompare(b.code));
+    const errors = findings.filter((f) => f.severity === 'error');
+    const warnings = findings.filter((f) => f.severity === 'warning');
+    return { ok: errors.length === 0, findings, errors, warnings };
+}

package/dist/audit/unused.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Unused-key reconciler (B3) — decide which *defined* keys no source references.
+ *
+ * A key counts as used if ANY usage layer reaches it, biased hard toward "used"
+ * so a live key is never flagged for deletion: exact static call, dynamic-prefix
+ * coverage, the loose literal-pool harvest (any string literal equal to a key),
+ * an explicit dynamic-key allowlist, or a runtime-observed key. What survives all
+ * layers is reported — `confirmed` when no opaque `t(variable)` site could be
+ * hiding it, else `suspect`. Separately, static render keys absent from the
+ * defined set surface as `used-but-undefined` (a typo / stale rename that renders
+ * its raw key at runtime).
+ */
+import type { KeyUsageSite, UsageScan } from './scan/types.js';
+export interface UnusedKeyFinding {
+    key: string;
+    /** `confirmed`: no usage signal and no opaque sites. `suspect`: opaque `t(var)` sites exist. */
+    tier: 'confirmed' | 'suspect';
+}
+export interface UsedButUndefinedFinding {
+    key: string;
+    sites: KeyUsageSite[];
+}
+export interface DynamicPrefixCoverage {
+    prefix: string;
+    /** Defined keys this prefix shields from the unused list (no other usage signal). */
+    shieldedKeys: number;
+}
+export interface UnusedReport {
+    /** Defined keys reached by no usage layer. */
+    unused: UnusedKeyFinding[];
+    /** Static render keys (`t('x')`) with no matching defined key. */
+    usedButUndefined: UsedButUndefinedFinding[];
+    /** Per-prefix blast radius, so a human sees what each dynamic family hides. */
+    dynamicPrefixCoverage: DynamicPrefixCoverage[];
+    /** Count of unresolved `t(variable)` sites — why `suspect` exists. */
+    opaqueSiteCount: number;
+}
+export interface FindUnusedOptions {
+    /** Key globs (`errors.*`) built dynamically — always treated as used. */
+    dynamicKeys?: string[];
+    /** Key globs excluded from the report entirely (intentionally retained, e.g. `legacy.*`). */
+    ignoreKeys?: string[];
+    /** Keys observed at runtime (e.g. from `createMissingKeyCollector`) — treated as used. */
+    runtimeUsedKeys?: Iterable<string>;
+}
+export declare function findUnusedKeys(definedKeys: Iterable<string>, scan: UsageScan, options?: FindUnusedOptions): UnusedReport;

package/dist/audit/unused.js

@@ -0,0 +1,65 @@
+/**
+ * Unused-key reconciler (B3) — decide which *defined* keys no source references.
+ *
+ * A key counts as used if ANY usage layer reaches it, biased hard toward "used"
+ * so a live key is never flagged for deletion: exact static call, dynamic-prefix
+ * coverage, the loose literal-pool harvest (any string literal equal to a key),
+ * an explicit dynamic-key allowlist, or a runtime-observed key. What survives all
+ * layers is reported — `confirmed` when no opaque `t(variable)` site could be
+ * hiding it, else `suspect`. Separately, static render keys absent from the
+ * defined set surface as `used-but-undefined` (a typo / stale rename that renders
+ * its raw key at runtime).
+ */
+import { makeGlobMatcher } from './glob.js';
+export function findUnusedKeys(definedKeys, scan, options = {}) {
+    const defined = new Set(definedKeys);
+    const isIgnored = makeGlobMatcher(options.ignoreKeys);
+    const isAllowlisted = makeGlobMatcher(options.dynamicKeys);
+    const runtimeUsed = new Set(options.runtimeUsedKeys ?? []);
+    // `.filter(Boolean)`: an empty prefix would `startsWith`-match every key and
+    // silently shield the whole codebase. The walkers already guard, but be safe.
+    const prefixes = [...new Set(scan.dynamicPrefixes.map((entry) => entry.prefix))].filter(Boolean);
+    const hasOpaqueSites = scan.opaqueSites.length > 0;
+    const matchesPrefix = (key) => prefixes.some((prefix) => key.startsWith(prefix));
+    const isUsed = (key) => scan.staticKeys.has(key) || // layer 1 — exact static render call
+        scan.probeKeys.has(key) || //  exists() probe
+        matchesPrefix(key) || //        layer 2 — dynamic-prefix coverage
+        scan.literalPool.has(key) || // layer 3 — loose literal harvest
+        isAllowlisted(key) || //        layer 4 — explicit dynamic allowlist
+        runtimeUsed.has(key); //        layer 5 — runtime-observed
+    const unused = [];
+    for (const key of defined) {
+        if (isIgnored(key) || isUsed(key))
+            continue;
+        unused.push({ key, tier: hasOpaqueSites ? 'suspect' : 'confirmed' });
+    }
+    unused.sort((a, b) => a.key.localeCompare(b.key));
+    const usedButUndefined = [];
+    for (const [key, sites] of scan.staticKeys) {
+        if (isIgnored(key) || isAllowlisted(key) || defined.has(key))
+            continue;
+        usedButUndefined.push({ key, sites });
+    }
+    usedButUndefined.sort((a, b) => a.key.localeCompare(b.key));
+    const dynamicPrefixCoverage = prefixes
+        .map((prefix) => ({
+        prefix,
+        // Keys this prefix is the SOLE reason for keeping (no other usage layer hits
+        // them); a prefix that shields nothing (e.g. a non-i18n template) is dropped.
+        shieldedKeys: [...defined].filter((key) => key.startsWith(prefix) &&
+            !isIgnored(key) &&
+            !scan.staticKeys.has(key) &&
+            !scan.probeKeys.has(key) &&
+            !scan.literalPool.has(key) &&
+            !isAllowlisted(key) &&
+            !runtimeUsed.has(key)).length
+    }))
+        .filter((coverage) => coverage.shieldedKeys > 0)
+        .sort((a, b) => a.prefix.localeCompare(b.prefix));
+    return {
+        unused,
+        usedButUndefined,
+        dynamicPrefixCoverage,
+        opaqueSiteCount: scan.opaqueSites.length
+    };
+}

package/dist/i18n/context.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { I18nError, Locale, PluralParams, TranslationOptions, TranslationParams } from './types.js';
+import type { I18nError, I18nMissingKey, Locale, PluralParams, TranslationOptions, TranslationParams } from './types.js';
 /**
  * The constant base locale used for read-tolerant resolution when no
  * `<I18nProvider>` is mounted. A constant — never global mutable state — so a
@@ -93,6 +93,15 @@ export interface I18nConfigureOptions {
      * `console.warn`. The hook for telemetry (Sentry, structured logging).
      */
     onError?: (error: I18nError) => void;
+    /**
+     * Invoked when `t`/`translate` resolves a key *nowhere* — not the active
+     * locale, not the fallback, in no package or the global bundle — and falls back
+     * to rendering the key string itself. Off by default (read-tolerant: a
+     * provider-less render legitimately misses keys), so this only fires when you
+     * opt in — the loud signal for "this string ships as its raw key". Pair with
+     * `createMissingKeyCollector` to assert "no misses" across a test/E2E run.
+     */
+    onMissingKey?: (info: I18nMissingKey) => void;
 }
 /**
  * App-global i18n configuration. Call **once at startup** (module scope or root

package/dist/i18n/context.svelte.js

@@ -163,5 +163,7 @@ export function useI18n() {
  * ```
  */
 export function configureI18n(options) {
-    getRegistry().onError = options.onError;
+    const registry = getRegistry();
+    registry.onError = options.onError;
+    registry.onMissingKey = options.onMissingKey;
 }

package/dist/i18n/package-integration.js

@@ -15,32 +15,39 @@ import { getRegistry } from './registry.svelte.js';
  * out of the initial bundle as dynamic-import chunks, loaded only when activated.
  */
 export function createPackageI18n(packageName, translations, options) {
-    // Eager registration at module-init time. The previous lazy variant
-    // (queueMicrotask inside t()) returned the raw key on first call and
-    // never re-triggered the reactive expression that read it, so consumers
-    // saw `filter.button.add` instead of the translated string.
+    // Lazy, first-use registration — deliberately NOT at module-eval (Codeberg #22).
+    // A consumer's top-level `export const x = createPackageI18n(...)` must not call
+    // getRegistry() during module initialisation: in a reordered *production* chunk
+    // (Rollup, `sideEffects: false`) that call can run before the registry module's
+    // `class I18nRegistry` statement, hitting the class temporal dead zone →
+    // `new (undefined)()` → "is not a constructor" → blank page on hydration. The
+    // hoisted getRegistry() keeps the *getter* reachable, but the *class* it
+    // constructs is still a TDZ binding, so the hoist guard alone was insufficient.
     //
-    // Running synchronously here is safe: `createPackageI18n` is invoked at
-    // module top-level (`export const tableI18n = createPackageI18n(...)`),
-    // which is outside any $derived/$effect — so the SvelteMap mutation in
-    // `registerPackage` cannot trip the `state_unsafe_mutation` rule.
-    //
-    // Goes through `getRegistry()` (a hoisted function), NOT a module-const binding:
-    // this call fires at consumer module-eval time, and under Vite 8 / Rolldown a
-    // reordered chunk can run it before the registry module's body ran. A hoisted
-    // function binding survives that; the lazy getter then builds the registry on
-    // first touch, in whatever order the chunks happen to fire.
-    getRegistry().registerPackage(packageName, translations);
-    // Opt-in lazy locales (WP4): register dynamic-import loaders. The eager bundle
-    // above is the base; these cover the rest, loaded on demand by the provider /
-    // setLocale. Parity for lazy bundles is a runtime concern (validatePackageTranslations).
-    if (options?.loaders) {
+    // Deferring registration to the first useTranslate()/t()/exists() call removes
+    // the ordering dependency at the source: by render / first-call time every module
+    // is fully evaluated, so `new I18nRegistry()` is always safe. Registration is
+    // synchronous (it runs before the translate read), so the first call resolves the
+    // real string — unlike the old queueMicrotask variant that returned the raw key.
+    // registerPackage mutates the reactive SvelteMap, but first touch is a component
+    // init (`useTranslate` body) or a non-reactive call (`t`/tests), never inside a
+    // `$derived`, so it cannot trip `state_unsafe_mutation`.
+    let registered = false;
+    const ensureRegistered = () => {
+        if (registered)
+            return;
+        registered = true;
         const registry = getRegistry();
-        for (const [locale, loader] of Object.entries(options.loaders)) {
-            if (loader)
-                registry.registerPackageLoader(packageName, locale, loader);
+        registry.registerPackage(packageName, translations);
+        // Opt-in lazy locales (WP4): dynamic-import loaders alongside the eager base
+        // bundle, loaded on demand by the provider / setLocale.
+        if (options?.loaders) {
+            for (const [locale, loader] of Object.entries(options.loaders)) {
+                if (loader)
+                    registry.registerPackageLoader(packageName, locale, loader);
+            }
         }
-    }
+    };
     // Context-scoped hook — the SSR-correct, reactive accessor. Captures the
     // request-scoped locale state at component init (or `undefined` without a
     // provider → base locale), then resolves against the static registry. Reading
@@ -48,6 +55,7 @@ export function createPackageI18n(packageName, translations, options) {
     // call-sites re-render on locale change; reading the registry's SvelteMap makes
     // them re-render when a package registers more translations.
     const useTranslate = () => {
+        ensureRegistered();
         const state = useI18nState();
         const registry = getRegistry();
         return ((key, params, options) => registry.translate(key, state?.locale ?? BASE_LOCALE, state?.fallbackLocale ?? BASE_LOCALE, params, { packageName, ...options }));
@@ -56,15 +64,25 @@ export function createPackageI18n(packageName, translations, options) {
     // against the base locale — there is no request-scoped state outside a
     // component. Components use `useTranslate` for the reactive, provider-scoped
     // locale.
-    const t = ((key, params, options) => getRegistry().translate(key, BASE_LOCALE, BASE_LOCALE, params, {
-        packageName,
-        ...options
-    }));
-    const exists = (key) => getRegistry().exists(key, BASE_LOCALE, packageName);
-    const getLocales = () => getRegistry().getPackageLocales(packageName);
-    // No-op kept for API back-compat with callers that used to invoke `register()`
-    // before reading translations. Registration now happens eagerly above.
-    const register = () => { };
+    const t = ((key, params, options) => {
+        ensureRegistered();
+        return getRegistry().translate(key, BASE_LOCALE, BASE_LOCALE, params, {
+            packageName,
+            ...options
+        });
+    });
+    const exists = (key) => {
+        ensureRegistered();
+        return getRegistry().exists(key, BASE_LOCALE, packageName);
+    };
+    const getLocales = () => {
+        ensureRegistered();
+        return getRegistry().getPackageLocales(packageName);
+    };
+    // Eager-register escape hatch: a consumer that wants the package present before
+    // the first useTranslate()/t() (e.g. to preload a lazy locale) can call this.
+    // Previously a no-op; now it performs the idempotent first-use registration.
+    const register = () => ensureRegistered();
     return {
         useTranslate,
         t,

package/dist/i18n/registry.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { I18nError, Locale, PackageTranslations, PluralParams, TranslationLoader, TranslationOptions, TranslationParams, Translations } from './types.js';
+import type { I18nError, I18nMissingKey, Locale, PackageTranslations, PluralParams, TranslationLoader, TranslationOptions, TranslationParams, Translations } from './types.js';
 import { isLocaleSupported } from './types.js';
 /**
  * Module-global translation **registry** — the static, request-identical half of
@@ -31,9 +31,19 @@ export declare class I18nRegistry {
      * failures surface somewhere; defaults to `console.warn`.
      */
     onError?: (error: I18nError) => void;
+    /**
+     * Optional missing-key sink. Set once by the app via `configureI18n`. Unlike
+     * `onError` there is NO default `console.warn`: a provider-less, read-tolerant
+     * render legitimately misses keys, so warning on every miss would be noise.
+     * Opt-in only — the loud signal for "this key resolved nowhere" when a consumer
+     * wants it (dev overlay, telemetry, a test collector). Fires exactly once per
+     * resolved-nowhere `translate` call, just before the key-as-itself fallback.
+     */
+    onMissingKey?: (info: I18nMissingKey) => void;
     get registeredPackages(): string[];
     get isLoading(): boolean;
     private reportError;
+    private reportMissingKey;
     registerPackage(packageName: string, translations: PackageTranslations): void;
     registerTranslationLoader(locale: Locale, loader: TranslationLoader): void;
     /**

package/dist/i18n/registry.svelte.js

@@ -49,6 +49,15 @@ export class I18nRegistry {
      * failures surface somewhere; defaults to `console.warn`.
      */
     onError;
+    /**
+     * Optional missing-key sink. Set once by the app via `configureI18n`. Unlike
+     * `onError` there is NO default `console.warn`: a provider-less, read-tolerant
+     * render legitimately misses keys, so warning on every miss would be noise.
+     * Opt-in only — the loud signal for "this key resolved nowhere" when a consumer
+     * wants it (dev overlay, telemetry, a test collector). Fires exactly once per
+     * resolved-nowhere `translate` call, just before the key-as-itself fallback.
+     */
+    onMissingKey;
     get registeredPackages() {
         return Array.from(this.packageTranslations.keys());
     }
@@ -72,6 +81,19 @@ export class I18nRegistry {
                 break;
         }
     }
+    reportMissingKey(key, locale, fallbackLocale, packageName) {
+        if (!this.onMissingKey)
+            return;
+        try {
+            this.onMissingKey({ key, locale, fallbackLocale, packageName, reason: 'no-translation' });
+        }
+        catch (error) {
+            // The miss sink is observability, never load-bearing: a throwing consumer
+            // handler must not break rendering or skip the read-tolerant key-as-itself
+            // fallback. Mirrors interpolate()'s defensive treatment of consumer callbacks.
+            console.warn(`onMissingKey handler threw for key "${key}"`, error);
+        }
+    }
     // --- registration / loading (static data; idempotent, request-identical) ---
     registerPackage(packageName, translations) {
         this.packageTranslations.set(packageName, translations);
@@ -230,6 +252,12 @@ export class I18nRegistry {
             translation = this.getTranslation(key, locale) || this.getTranslation(key, fallbackLocale);
         }
         if (!translation) {
+            // Resolved nowhere — package, fallback, and global all missed. Surface the
+            // loud signal (opt-in) before the read-tolerant key-as-itself fallback.
+            // `reportMissing: false` callers (the optional `_plural` probe) opt out.
+            if (opts.reportMissing !== false) {
+                this.reportMissingKey(key, locale, fallbackLocale, opts.packageName);
+            }
             translation = key;
         }
         return opts.interpolate ? this.interpolate(translation, locale, params) : translation;
@@ -237,9 +265,13 @@ export class I18nRegistry {
     pluralize(key, params, locale, fallbackLocale, options) {
         const count = params.count;
         const pluralKey = `${key}_plural`;
+        // `reportMissing: false`: a `<key>_plural` object is optional, so this probe
+        // legitimately resolves nowhere for keys without CLDR forms — it must not fire
+        // onMissingKey. A miss on the base `key` below still reports (it's a real one).
         const pluralTranslation = this.translate(pluralKey, locale, fallbackLocale, undefined, {
             ...options,
-            interpolate: false
+            interpolate: false,
+            reportMissing: false
         });
         if (pluralTranslation !== pluralKey) {
             try {

package/dist/i18n/types.d.ts

@@ -69,6 +69,24 @@ export type I18nError = {
     type: 'load-failed-no-fallback';
     locale: Locale;
 };
+/**
+ * Surfaced through {@link I18nConfigureOptions.onMissingKey} when `translate`
+ * resolves a key *nowhere* — neither the active nor the fallback locale, in any
+ * package or the global bundle — and falls back to returning the key string
+ * itself. The loud signal for "this will render as its raw key in production".
+ */
+export interface I18nMissingKey {
+    /** The unresolved key, exactly as passed to `t` / `translate`. */
+    key: string;
+    /** Active locale at the time of the miss. */
+    locale: Locale;
+    /** Fallback locale that was also tried and also missed. */
+    fallbackLocale: Locale;
+    /** Package scope, when the call was package-scoped (`useTranslate` / `packageName`). */
+    packageName?: string;
+    /** Always `no-translation` today; a discriminant reserved for future miss reasons. */
+    reason: 'no-translation';
+}
 type WidenStringLiteralsDeep<T> = T extends string ? string : T extends Array<infer U> ? Array<WidenStringLiteralsDeep<U>> : T extends object ? {
     [K in keyof T]: WidenStringLiteralsDeep<T[K]>;
 } : T;
@@ -77,6 +95,13 @@ export interface TranslationOptions {
     packageName?: string;
     fallbackToGlobal?: boolean;
     interpolate?: boolean;
+    /**
+     * @internal Whether an unresolved key reports through `onMissingKey`. Defaults
+     * to `true`. Set `false` for internal probes that expect a miss — the
+     * `pluralize` lookup of an *optional* `<key>_plural` object, which legitimately
+     * resolves nowhere and must not masquerade as a missing translation.
+     */
+    reportMissing?: boolean;
 }
 export type TranslationLoader = (locale: Locale) => Promise<Translations>;
 export type PackageTranslationLoader = (packageName: string, locale: Locale) => Promise<Translations>;

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+export type { MissingKeyCollector, MissingKeyRecord } from './audit/missing-key-collector.js';
+export { createMissingKeyCollector } from './audit/missing-key-collector.js';
+export type { AuditTranslationsOptions, TranslationAuditReport, TranslationFinding, TranslationFindingCode, TranslationFindingSeverity } from './audit/translations.js';
+export { auditTranslations } from './audit/translations.js';
 export { I18nProvider, T } from './components/index.js';
 export type { I18nApi, I18nConfigureOptions } from './i18n/context.svelte.js';
 export { BASE_LOCALE, configureI18n, provideI18n, useI18n } from './i18n/context.svelte.js';
@@ -5,7 +9,7 @@ export type { CreatePackageI18nOptions } from './i18n/package-integration.js';
 export { createComponentI18n, createPackageI18n, createPackageTranslations, createTypedPackage, registerPackages, registerTranslationLoaders, validatePackageTranslations } from './i18n/package-integration.js';
 export type { LocaleSource, ResolveLocaleOptions } from './i18n/resolve-locale.js';
 export { resolveLocale } from './i18n/resolve-locale.js';
-export type { CreatePackageTypes, I18nComponentProps, I18nConfig, I18nError, I18nStore, Locale, PackageI18n, PackageTranslations, PluralParams, PluralRules, TranslationFunction, TranslationLoader, TranslationOptions, TranslationParams, Translations, TypedTranslationFunction } from './i18n/types.js';
+export type { CreatePackageTypes, I18nComponentProps, I18nConfig, I18nError, I18nMissingKey, I18nStore, Locale, PackageI18n, PackageTranslations, PluralParams, PluralRules, TranslationFunction, TranslationLoader, TranslationOptions, TranslationParams, Translations, TypedTranslationFunction } from './i18n/types.js';
 export { isLocaleSupported, SUPPORTED_LOCALES } from './i18n/types.js';
 export type { DeepKeys, DeepValue } from './utils/deep-keys.js';
 export { collectDeepKeys, getDeepValue, hasDeepKey } from './utils/deep-keys.js';

package/dist/index.js

@@ -1,4 +1,13 @@
-// --- Request-scoped i18n (WP2: SSR-correct, Context-based) ---
+// Public surface of @urbicon-ui/i18n — request-scoped runtime (SSR-correct,
+// context-based), package integration, and the data-level audit utilities.
+// (Export order is Biome-sorted by module path; see the per-group comments.)
+// Runtime missing-key sink: wire `createMissingKeyCollector().onMissingKey` into
+// configureI18n to assert "no raw-key renders" across a test/E2E run.
+export { createMissingKeyCollector } from './audit/missing-key-collector.js';
+// Translation audit (data-level parity & quality). Pure, dependency-free — run in
+// a vitest test (`expect(auditTranslations(bundles).ok).toBe(true)`) or via the
+// `urbicon i18n parity` CLI. The richer successor to validatePackageTranslations.
+export { auditTranslations } from './audit/translations.js';
 // Provider + general hook: mount one <I18nProvider> at the app root, read locale
 // control and locale-aware formatting via useI18n() inside components.
 export { I18nProvider, T } from './components/index.js';