@urbicon-ui/i18n 6.3.9 → 6.3.11

package/README.md

@@ -302,6 +302,41 @@ import type {
 
 `en`, `de` ship data. `fr`, `es`, `it`, `nl` are declared target locales (in the `Locale` union / `SUPPORTED_LOCALES`) — register your own bundles for them via `createPackageI18n`.
 
+## Translation Auditing
+
+Three layers catch i18n problems — untranslated strings, unused keys, and copy that bypassed i18n entirely. The data-level audit and the runtime sink ship from the main entry (dependency-free, usable in a Vitest test); the source scanner lives on the dev-only `@urbicon-ui/i18n/audit` subpath; the `urbicon i18n` CLI (`@urbicon-ui/design`) is the filesystem front end over all three.
+
+**1. Data-level parity & quality** — `auditTranslations(packageName, bundles)` diffs locale bundles for missing/extra keys, empty values, interpolation-param drift (`{{name}}` in one locale but not another), value-equals-key placeholders, and malformed / CLDR-incomplete `_plural` objects. Pure and deterministic — run it as a test (the richer successor to `validatePackageTranslations`, kept for back-compat):
+
+```ts
+import { auditTranslations } from '@urbicon-ui/i18n';
+import { appTranslations } from '$lib/i18n';
+
+it('translations are in parity', () => {
+  expect(auditTranslations('app', appTranslations).ok).toBe(true);
+});
+```
+
+**2. Runtime missing-key sink** — `onMissingKey` (via `configureI18n`) fires when a key resolves nowhere and would render as its raw string. `createMissingKeyCollector()` packages it for tests/E2E — assert that nothing rendered a raw key, including dynamically-built keys a static scan can't see:
+
+```ts
+import { configureI18n, createMissingKeyCollector } from '@urbicon-ui/i18n';
+
+const misses = createMissingKeyCollector();
+configureI18n({ onMissingKey: misses.onMissingKey });
+// … render / exercise the app …
+expect(misses.isClean()).toBe(true);
+```
+
+**3. Source scan & CLI** — `urbicon i18n` scans your sources for **unused** keys (defined but referenced nowhere), **used-but-undefined** keys (a typo that renders raw), and **hardcoded** UI strings. Run it under Bun (it loads `.ts` locale bundles):
+
+```bash
+urbicon i18n audit src/ --translations src/lib/translations  # parity + unused + hardcoded
+urbicon i18n unused --dynamic-keys 'errors.*' --json         # just the scan, allowlisting dynamic key families
+```
+
+It gates (exit 1) on parity errors + used-but-undefined; unused keys and hardcoded strings are advisory (`--strict` gates them too). The pure scanner core — `scanSources`, `findUnusedKeys`, `findHardcodedStrings` — is on the `@urbicon-ui/i18n/audit` subpath for programmatic use, with `typescript` + `svelte` as optional peers it lazily imports. See the [CI gate template](../design/templates/ci-github.yml).
+
 ## Development
 
 ```bash

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/i18n",
-  "version": "6.3.9",
+  "version": "6.3.11",
   "description": "Runes-based localization for Svelte 5 apps and the Urbicon UI design system",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@types/node": "^25.9.4",
-    "@urbicon-ui/shared-types": "6.3.9",
+    "@urbicon-ui/shared-types": "6.3.11",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",