@urbicon-ui/i18n 6.49.0 → 6.50.0

package/README.md

@@ -10,13 +10,11 @@ The locale lives in **context**, not a module-global singleton — so concurrent
 
 ## Installation
 
-This package ships inside the Urbicon UI monorepo. Install from repo root:
-
 ```bash
-bun install
+bun add @urbicon-ui/i18n
 ```
 
-Peer dependencies: `svelte` (^5.40 — uses runes + `createContext`-era context), `@sveltejs/kit`.
+Peer dependencies: `svelte` (^5.40 — uses runes + `createContext`-era context). No SvelteKit needed: the package imports neither `$app/*` nor `@sveltejs/kit`, so it works in any Svelte 5 project — the request-scoped locale below is what keeps it SSR-correct wherever you render.
 
 ## Quick Start
 
@@ -191,6 +189,23 @@ resolveLocale(request, {
 
 > Fully **prerendered** (static) sites have no per-request server, so resolve the locale on the client after mount instead (read a cookie/`localStorage`, then `setLocale`). The provider's base-locale-first render keeps hydration stable.
 
+## Formatting with `Intl` — `resolveDateLocale`
+
+Building your own date or number component? Never hand `Intl` an `undefined` locale: it follows the *runtime*, which is your server process during SSR and the user's browser after hydration, so the same value renders two ways across the boundary. `resolveDateLocale` is the chain the library's own components use:
+
+```ts
+import { resolveDateLocale, useI18n } from '@urbicon-ui/i18n';
+
+const i18n = useI18n();
+// `explicit prop → provider locale → BASE_LOCALE`
+const locale = $derived(resolveDateLocale(localeProp, i18n.locale));
+new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(value);
+```
+
+The two rungs are treated differently on purpose. An explicit prop is **trusted** — any BCP 47 tag is fair game, including ones this package ships no translations for (`'ja-JP'`), and a malformed one throws from `Intl` at the call site that caused it. A provider value is **verified**, because `<I18nProvider locale={x}>` does not validate `x`: `'de_DE'` and `''` would throw at render time (an SSR 500 in a component that never saw the value), while `'xx'` and `'english'` do not throw at all — `Intl` silently resolves them to the runtime default, reintroducing the divergence through the back door. Unsupported values therefore fall back to `BASE_LOCALE` and say so in DEV.
+
+Pass `'auto'` (or `undefined`) as the prop to mean "no explicit choice".
+
 ## Locale code-splitting (opt-in)
 
 By default a package registers all its locale bundles eagerly. To keep non-base locales out of the initial bundle, register them as dynamic-import loaders — the base/fallback locale stays eager, the rest load on activation:

package/dist/i18n/resolve-date-locale.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Resolve the BCP 47 tag a component formats with (`Intl.DateTimeFormat`,
+ * `Intl.NumberFormat`, `Intl.RelativeTimeFormat`).
+ *
+ * The chain is `explicit prop → i18n provider → base locale`, and the two rungs
+ * are treated differently on purpose.
+ *
+ * **The prop is trusted.** A consumer writing `locale="ja-JP"` means it, and any
+ * valid BCP 47 tag is fair game — the library has no business restricting it to
+ * the six locales it ships translations for. An invalid one throws from `Intl`,
+ * loudly, at the call site that caused it. That is the house rule: explicit
+ * input fails loudly rather than being silently repaired.
+ *
+ * **The context value is verified**, because a bad one is a very different
+ * failure. `I18nState`'s constructor does not validate its argument (only
+ * `setLocale` does — `context.svelte.ts`), so `<I18nProvider locale={x}>` puts
+ * whatever `x` is behind the `Locale` type. Before formatting read that value,
+ * a bogus one merely made translation lookups fall back. Now it reaches `Intl`,
+ * where it fails in two ways, both measured:
+ *
+ *   - `'de_DE'` (underscore) and `''` throw `RangeError` — a render-time throw,
+ *     i.e. an SSR 500, from a component that never saw the offending value;
+ *   - `'xx'`, `'zz-ZZ'`, `'english'` do NOT throw. `Intl` resolves them to the
+ *     *runtime* default — `en-US` under Bun, whatever `LANG` says under Node.
+ *     That is exactly the server/client divergence the `'auto'` default exists
+ *     to prevent, reintroduced through the back door.
+ *
+ * So an unsupported context value falls back to the base locale, which is what
+ * the rest of the i18n system does with it anyway, and says so in DEV. The
+ * component stays renderable and the diagnosis points at the provider.
+ *
+ * Lives here rather than in `blocks` (where it was written, 2026-07-31) because
+ * `table` needs the same chain for its own cells and the two packages share no
+ * code but this one — both peer-depend on this package, and both `BASE_LOCALE`
+ * and `isLocaleSupported` already live next door. A second hand-aligned copy is
+ * how the four drifted `toSlug` implementations happened (#43).
+ */
+export declare function resolveDateLocale(prop: string | undefined, contextLocale: string): string;

package/dist/i18n/resolve-date-locale.js

@@ -0,0 +1,59 @@
+import { BASE_LOCALE } from './context.svelte.js';
+import { isLocaleSupported } from './types.js';
+/**
+ * Resolve the BCP 47 tag a component formats with (`Intl.DateTimeFormat`,
+ * `Intl.NumberFormat`, `Intl.RelativeTimeFormat`).
+ *
+ * The chain is `explicit prop → i18n provider → base locale`, and the two rungs
+ * are treated differently on purpose.
+ *
+ * **The prop is trusted.** A consumer writing `locale="ja-JP"` means it, and any
+ * valid BCP 47 tag is fair game — the library has no business restricting it to
+ * the six locales it ships translations for. An invalid one throws from `Intl`,
+ * loudly, at the call site that caused it. That is the house rule: explicit
+ * input fails loudly rather than being silently repaired.
+ *
+ * **The context value is verified**, because a bad one is a very different
+ * failure. `I18nState`'s constructor does not validate its argument (only
+ * `setLocale` does — `context.svelte.ts`), so `<I18nProvider locale={x}>` puts
+ * whatever `x` is behind the `Locale` type. Before formatting read that value,
+ * a bogus one merely made translation lookups fall back. Now it reaches `Intl`,
+ * where it fails in two ways, both measured:
+ *
+ *   - `'de_DE'` (underscore) and `''` throw `RangeError` — a render-time throw,
+ *     i.e. an SSR 500, from a component that never saw the offending value;
+ *   - `'xx'`, `'zz-ZZ'`, `'english'` do NOT throw. `Intl` resolves them to the
+ *     *runtime* default — `en-US` under Bun, whatever `LANG` says under Node.
+ *     That is exactly the server/client divergence the `'auto'` default exists
+ *     to prevent, reintroduced through the back door.
+ *
+ * So an unsupported context value falls back to the base locale, which is what
+ * the rest of the i18n system does with it anyway, and says so in DEV. The
+ * component stays renderable and the diagnosis points at the provider.
+ *
+ * Lives here rather than in `blocks` (where it was written, 2026-07-31) because
+ * `table` needs the same chain for its own cells and the two packages share no
+ * code but this one — both peer-depend on this package, and both `BASE_LOCALE`
+ * and `isLocaleSupported` already live next door. A second hand-aligned copy is
+ * how the four drifted `toSlug` implementations happened (#43).
+ */
+export function resolveDateLocale(prop, contextLocale) {
+    if (prop !== undefined && prop !== 'auto')
+        return prop;
+    if (isLocaleSupported(contextLocale))
+        return contextLocale;
+    // First `import.meta.env` in this package, so the `@sveltejs/package` build
+    // advisory ("Avoid usage of `import.meta.env`") now fires here too. Same
+    // deliberate trade as in `blocks`: optional-chained so a non-Vite consumer
+    // gets `undefined` rather than a throw, and `esm-env` is not an option
+    // because it would be a runtime dependency in the published dist. The
+    // advisory is a plain string match, so `?.` does not quiet it. See the
+    // zero-dependency note in AGENTS.md — do not "fix" it by adding a dep.
+    if (import.meta.env?.DEV) {
+        console.warn(`[i18n] <I18nProvider locale="${contextLocale}"> is not a supported locale, so date and ` +
+            `number formatting falls back to "${BASE_LOCALE}". Supported: en, de, fr, es, it, nl. ` +
+            `To format in a locale the library ships no translations for, pass it to the ` +
+            `component directly (e.g. locale="ja-JP") instead of through the provider.`);
+    }
+    return BASE_LOCALE;
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export type { I18nApi, I18nConfigureOptions } from './i18n/context.svelte.js';
 export { BASE_LOCALE, configureI18n, provideI18n, useI18n } from './i18n/context.svelte.js';
 export type { CreatePackageI18nOptions } from './i18n/package-integration.js';
 export { createComponentI18n, createPackageI18n, createPackageTranslations, createTypedPackage, registerPackages, registerTranslationLoaders, validatePackageTranslations } from './i18n/package-integration.js';
+export { resolveDateLocale } from './i18n/resolve-date-locale.js';
 export type { LocaleSource, ResolveLocaleOptions } from './i18n/resolve-locale.js';
 export { resolveLocale } from './i18n/resolve-locale.js';
 export type { CreatePackageTypes, I18nComponentProps, I18nConfig, I18nError, I18nMissingKey, I18nStore, Locale, PackageI18n, PackageTranslations, PluralParams, PluralRules, TranslationFunction, TranslationLoader, TranslationOptions, TranslationParams, Translations, TypedTranslationFunction } from './i18n/types.js';

package/dist/index.js

@@ -14,6 +14,10 @@ export { I18nProvider, T } from './components/index.js';
 export { BASE_LOCALE, configureI18n, provideI18n, useI18n } from './i18n/context.svelte.js';
 // Package integration utilities
 export { createComponentI18n, createPackageI18n, createPackageTranslations, createTypedPackage, registerPackages, registerTranslationLoaders, validatePackageTranslations } from './i18n/package-integration.js';
+// The `explicit prop → provider → base locale` chain a component resolves an
+// `Intl` tag through. Distinct from `resolveLocale` below: this one answers
+// "what do I format with", not "what locale is this request in".
+export { resolveDateLocale } from './i18n/resolve-date-locale.js';
 // Server-side initial-locale resolution (cookie + Accept-Language) for the
 // provider's `locale` prop. SSR/hydration-stable.
 export { resolveLocale } from './i18n/resolve-locale.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/i18n",
-  "version": "6.49.0",
+  "version": "6.50.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": "^26.1.2",
-    "@urbicon-ui/shared-types": "6.49.0",
+    "@urbicon-ui/shared-types": "6.50.0",
     "prettier": "^3.9.6",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.1",
@@ -56,7 +56,6 @@
   "main": "dist/index.js",
   "sideEffects": false,
   "peerDependencies": {
-    "@sveltejs/kit": "^2.70.2",
     "svelte": "^5.56.8",
     "typescript": "^6.0.3",
     "@urbicon-ui/shared-types": "^6.0.0"