@urbicon-ui/i18n 6.34.0 → 6.35.0

package/README.md

@@ -107,9 +107,12 @@ Each Urbicon package registers its own namespaced keys so consumers get a merged
 // Inside @urbicon-ui/blocks — src/lib/i18n/index.ts
 import { createPackageI18n } from '@urbicon-ui/i18n';
 import en from '../translations/en';
-import de from '../translations/de';
 
-export const blocksI18n = createPackageI18n('blocks', { en, de });
+// en is the eager base; de is a lazy dynamic-import loader (see "Locale
+// code-splitting" below), so English-only apps never bundle the de catalog.
+export const blocksI18n = createPackageI18n('blocks', { en }, {
+  loaders: { de: () => import('../translations/de').then((m) => m.default) }
+});
 
 // The context-scoped hook (re-exported for components)
 export const useBlocksI18n = blocksI18n.useTranslate;
@@ -205,7 +208,25 @@ export const blocksI18n = createPackageI18n(
 );
 ```
 
-Vite/Rollup splits each dynamic import into its own chunk, so only the active locale is in the initial bundle. The provider loads the active + fallback locale on mount; `setLocale` loads a target on switch. A lazy non-base initial locale renders the fallback until its chunk lands, then re-resolves reactively. Worth it past a handful of locales; eager is simpler for `en`/`de`.
+Vite/Rollup splits each dynamic import into its own chunk, so only the active locale is in the initial bundle. The provider loads the active + fallback locale on mount; `setLocale` loads a target on switch. A lazy non-base initial locale renders the fallback until its chunk lands, then re-resolves reactively.
+
+> **`@urbicon-ui/blocks` ships this way** — `en` eager, `de` lazy — so an English-only app doesn't bundle the `de` catalog.
+
+### SSR: eager-register the lazy locale for non-base apps
+
+The provider's on-mount load runs in a **client-only** `$effect`. So under SSR a lazy non-base initial locale (e.g. a German app) renders the *fallback* (English) on the server and the first client paint, then flips to German once the chunk lands — a text flash and a possible hydration text mismatch. That is not acceptable as the default for a server-rendered app in that locale.
+
+The fix is to register the bundle **eagerly, once at server/app start**. The registry is module-global and holds only static, request-identical translation data, so a single startup registration is SSR-safe (it carries no per-request state). Every package factory returns `registerLocale(locale, bundle)` for this; `@urbicon-ui/blocks` re-exports it as `registerBlocksLocale`:
+
+```ts
+// src/hooks.server.ts (or any module evaluated once at server start)
+import { registerBlocksLocale } from '@urbicon-ui/blocks';
+import de from '@urbicon-ui/blocks/i18n/de'; // the public per-locale subpath
+
+registerBlocksLocale('de', de);
+```
+
+`registerLocale` is **additive** (it merges the locale in without dropping the eager base) and **write-strict** (throws on an unsupported locale or a non-object bundle). The `de` catalog stays out of English-only client bundles — you only pull it in where it is actually rendered. Worth the loader split past a handful of locales; a fully eager `createPackageI18n(name, { en, de })` is simpler when you always ship both.
 
 ## Coexisting with an app-level i18n (e.g. Paraglide)
 
@@ -244,10 +265,11 @@ configureI18n({ onError: (e) => reportToSentry(e) });
 
 ```ts
 import { validatePackageTranslations } from '@urbicon-ui/i18n';
-import { blocksTranslations } from '$lib/i18n';
+import en from '$lib/translations/en';
+import de from '$lib/translations/de'; // import lazy bundles directly for the check
 
 it('en/de key parity', () => {
-  expect(validatePackageTranslations('blocks', blocksTranslations).errors).toEqual([]);
+  expect(validatePackageTranslations('blocks', { en, de }).errors).toEqual([]);
 });
 ```
 

package/dist/i18n/package-integration.d.ts

@@ -62,6 +62,7 @@ export declare function createTypedPackage<const T extends Translations>(package
     exists: (key: string) => boolean;
     getLocales: () => Locale[];
     register: () => void;
+    registerLocale: (locale: Locale, bundle: Translations) => void;
     types: CreatePackageTypes<T>;
 };
 /**
@@ -91,6 +92,7 @@ export declare function createComponentI18n<const T extends Translations>(packag
     exists: (key: string) => boolean;
     getLocales: () => Locale[];
     register: () => void;
+    registerLocale: (locale: Locale, bundle: Translations) => void;
     types: CreatePackageTypes<T>;
 };
 /**

package/dist/i18n/package-integration.js

@@ -1,6 +1,7 @@
 import { collectDeepKeys } from '../utils/deep-keys.js';
 import { BASE_LOCALE, useI18nState } from './context.svelte.js';
 import { getRegistry } from './registry.svelte.js';
+import { isLocaleSupported, SUPPORTED_LOCALES } from './types.js';
 /**
  * Creates a standardized i18n integration for a package.
  *
@@ -83,12 +84,38 @@ export function createPackageI18n(packageName, translations, options) {
     // 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();
+    // Eager, additive registration of one locale's bundle — the SSR escape hatch for
+    // a locale that is otherwise declared as a lazy `options.loaders` entry. The
+    // provider only loads lazy chunks in a client-only `$effect`, so a lazy non-base
+    // locale renders the *fallback* (base) locale during SSR and the first client
+    // paint, then flips once the chunk lands. A server-rendered app in that locale
+    // therefore ships the wrong-language strings and risks a hydration text
+    // mismatch. Registering the imported bundle here — once at server/app start,
+    // where it is request-identical static data on the module-global registry —
+    // makes the locale present for the very first render instead. Merges (does NOT
+    // clobber the eager base bundle) via registry.registerPackageLocale.
+    //
+    // Write-strict: throws on an unsupported locale or a non-object bundle rather
+    // than silently registering garbage under a bogus key.
+    const registerLocale = (locale, bundle) => {
+        if (!isLocaleSupported(locale)) {
+            throw new Error(`[i18n] ${packageName}.registerLocale: unsupported locale "${String(locale)}". ` +
+                `Supported: ${SUPPORTED_LOCALES.join(', ')}.`);
+        }
+        if (!bundle || typeof bundle !== 'object' || Array.isArray(bundle)) {
+            const kind = bundle === null ? 'null' : Array.isArray(bundle) ? 'array' : typeof bundle;
+            throw new Error(`[i18n] ${packageName}.registerLocale("${locale}"): bundle must be a translations object, got ${kind}.`);
+        }
+        ensureRegistered();
+        getRegistry().registerPackageLocale(packageName, locale, bundle);
+    };
     return {
         useTranslate,
         t,
         exists,
         getLocales,
         register,
+        registerLocale,
         types: {}
     };
 }

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

@@ -53,6 +53,24 @@ export declare class I18nRegistry {
      * initial chunk until the locale is activated.
      */
     registerPackageLoader(packageName: string, locale: Locale, loader: () => Promise<Translations>): void;
+    /**
+     * Additively register one locale's already-loaded bundle for a package — the
+     * synchronous, eager counterpart to {@link loadPackageLocale}.
+     *
+     * Unlike {@link registerPackage} (which `.set`s the *whole* package entry and so
+     * drops any sibling locale already registered), this **merges** the single
+     * locale into the existing entry, preserving the eager base bundle. That makes
+     * it the correct primitive for an eager-register escape hatch: a consumer that
+     * has passed a locale as a lazy `loader` can register its imported bundle up
+     * front (e.g. once at SSR/app start) so the very first server render already
+     * resolves that locale — no fallback-locale flash, no hydration text mismatch —
+     * instead of waiting for the provider's client-only on-mount chunk load.
+     *
+     * A fresh object reference is written so the reactive SvelteMap notifies
+     * `$derived` readers (an in-place mutation would not). Idempotent-friendly:
+     * re-registering the same locale simply overwrites it with identical data.
+     */
+    registerPackageLocale(packageName: string, locale: Locale, data: Translations): void;
     hasLoader(locale: Locale): boolean;
     isLoaded(locale: Locale): boolean;
     private loaderKeyLocale;

package/dist/i18n/registry.svelte.js

@@ -109,6 +109,28 @@ export class I18nRegistry {
     registerPackageLoader(packageName, locale, loader) {
         this.packageLoaders.set(`${packageName}::${locale}`, loader);
     }
+    /**
+     * Additively register one locale's already-loaded bundle for a package — the
+     * synchronous, eager counterpart to {@link loadPackageLocale}.
+     *
+     * Unlike {@link registerPackage} (which `.set`s the *whole* package entry and so
+     * drops any sibling locale already registered), this **merges** the single
+     * locale into the existing entry, preserving the eager base bundle. That makes
+     * it the correct primitive for an eager-register escape hatch: a consumer that
+     * has passed a locale as a lazy `loader` can register its imported bundle up
+     * front (e.g. once at SSR/app start) so the very first server render already
+     * resolves that locale — no fallback-locale flash, no hydration text mismatch —
+     * instead of waiting for the provider's client-only on-mount chunk load.
+     *
+     * A fresh object reference is written so the reactive SvelteMap notifies
+     * `$derived` readers (an in-place mutation would not). Idempotent-friendly:
+     * re-registering the same locale simply overwrites it with identical data.
+     */
+    registerPackageLocale(packageName, locale, data) {
+        const existing = this.packageTranslations.get(packageName) ?? {};
+        this.packageTranslations.set(packageName, { ...existing, [locale]: data });
+        this.addTranslations(locale, { [packageName]: data });
+    }
     hasLoader(locale) {
         if (this.translationLoaders.has(locale))
             return true;
@@ -190,15 +212,13 @@ export class I18nRegistry {
         this.loadingPackageLocales.add(key);
         try {
             const data = await loader();
-            // New object reference per merge so the SvelteMap notifies subscribers
-            // (SvelteMap.set only signals when the value reference changes — an in-place
-            // mutation would NOT re-run the $derived reads). `existing` is read AFTER the
-            // await, so two concurrent loads of different non-base locales for the same
+            // Delegate the additive merge to registerPackageLocale (same primitive the
+            // eager escape hatch uses). It reads `existing` fresh — here, AFTER the
+            // await — so two concurrent loads of different non-base locales for the same
             // package (e.g. de + fr) each see the other's already-merged result and don't
-            // lose a write.
-            const existing = this.packageTranslations.get(packageName) ?? {};
-            this.packageTranslations.set(packageName, { ...existing, [locale]: data });
-            this.addTranslations(locale, { [packageName]: data });
+            // lose a write, and it writes a new object reference so the SvelteMap
+            // notifies its `$derived` subscribers.
+            this.registerPackageLocale(packageName, locale, data);
             return true;
         }
         catch (error) {

package/dist/i18n/types.d.ts

@@ -142,6 +142,16 @@ export interface PackageI18n<T extends Translations> {
     exists: (key: string) => boolean;
     getLocales: () => Locale[];
     register: () => void;
+    /**
+     * Eagerly and **additively** register one locale's already-imported bundle for
+     * this package — the SSR escape hatch for a locale declared as a lazy
+     * `options.loaders` entry. Call once at server/app start (with e.g.
+     * `import de from '@urbicon-ui/blocks/i18n/de'`) so the first server render
+     * already resolves that locale instead of rendering the fallback until the
+     * client-only on-mount chunk load lands. Merges — it does not drop the eager
+     * base bundle. Throws on an unsupported locale or a non-object bundle.
+     */
+    registerLocale: (locale: Locale, bundle: Translations) => void;
     types: CreatePackageTypes<T>;
 }
 export interface I18nComponentProps {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/i18n",
-  "version": "6.34.0",
+  "version": "6.35.0",
   "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.5",
-    "@urbicon-ui/shared-types": "6.34.0",
+    "@urbicon-ui/shared-types": "6.35.0",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",