@urbicon-ui/i18n 6.1.4

package/dist/i18n/types.d.ts

@@ -0,0 +1,127 @@
+import type { DeepKeys } from '../utils/deep-keys';
+/**
+ * Single source of truth for the locales the library declares support for.
+ *
+ * "Declared, data optional": `en`/`de` ship translation data; `fr`/`es`/`it`/`nl`
+ * are valid target locales a consumer can register its own bundles for. The list
+ * lives here exactly once — both the `Locale` union and the runtime
+ * `isLocaleSupported` guard derive from it, so the type and the runtime check can
+ * never drift apart (previously the same six codes were hardcoded twice).
+ */
+export declare const SUPPORTED_LOCALES: readonly ["en", "de", "fr", "es", "it", "nl"];
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+/**
+ * Runtime guard derived from {@link SUPPORTED_LOCALES} — the single source of
+ * truth. Used by both the registry and the request-scoped locale state, so the
+ * type and the runtime check can never drift apart.
+ */
+export declare function isLocaleSupported(locale: string): locale is Locale;
+export type Translations = {
+    [key: string]: string | Translations;
+};
+export type PackageTranslations = Partial<Record<Locale, Translations>>;
+/**
+ * Base translation function signature
+ */
+export type TranslationFunction = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * Translation store interface
+ */
+export interface TranslationStore {
+    locale: Locale;
+    translations: PackageTranslations;
+    t: TranslationFunction;
+}
+export type TranslationParams = Record<string, string | number | boolean | (() => string)>;
+type ExtractParams<T extends string> = T extends `${string}{{${infer Param}}}${infer Rest}` ? Param | ExtractParams<Rest> : never;
+export type TranslationParametersFor<T extends Translations, K extends DeepKeys<T>> = PathValue<T, K> extends string ? ExtractParams<PathValue<T, K>> extends never ? Record<string, never> : Record<ExtractParams<PathValue<T, K>>, string | number | boolean> : TranslationParams;
+export type TypedTranslationFunction<T extends Translations> = <K extends DeepKeys<T>>(key: K, ...args: TranslationParametersFor<T, K> extends Record<string, never> ? [params?: TranslationParams, options?: TranslationOptions] : [params: TranslationParametersFor<T, K>, options?: TranslationOptions]) => string;
+export interface I18nStore {
+    locale: Locale;
+    translations: Partial<Record<Locale, Translations>>;
+    fallbackLocale: Locale;
+    packageTranslations: Map<string, Partial<Record<Locale, Translations>>>;
+    loadedLocales: Set<Locale>;
+    loadingLocales: Set<Locale>;
+}
+export interface I18nConfig {
+    defaultLocale?: Locale;
+    fallbackLocale?: Locale;
+    translations?: Partial<Record<Locale, Translations>>;
+    detectBrowserLocale?: boolean;
+    lazyLoad?: boolean;
+    /**
+     * Optional error handler. Invoked when a registered loader rejects
+     * (loadLocale failure) or when an unsupported locale is requested
+     * (setLocale failure). When omitted, the service falls back to
+     * `console.warn` so consumers still see something during development.
+     */
+    onError?: (error: I18nError) => void;
+}
+export type I18nError = {
+    type: 'load-failed';
+    locale: Locale;
+    cause: unknown;
+} | {
+    type: 'unsupported-locale';
+    locale: string;
+} | {
+    type: 'load-failed-no-fallback';
+    locale: Locale;
+};
+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;
+export type TranslationSchema<T extends Translations> = WidenStringLiteralsDeep<T>;
+export interface TranslationOptions {
+    packageName?: string;
+    fallbackToGlobal?: boolean;
+    interpolate?: boolean;
+}
+export type TranslationLoader = (locale: Locale) => Promise<Translations>;
+export type PackageTranslationLoader = (packageName: string, locale: Locale) => Promise<Translations>;
+type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : never : P extends keyof T ? T[P] : never;
+export interface PluralRules {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+export interface PluralParams extends TranslationParams {
+    count: number;
+}
+export type ValidateTemplate<T extends string> = T extends `${string}{{${string}}}${string}` ? T : never;
+export type CreatePackageTypes<T extends Translations> = {
+    keys: DeepKeys<T>;
+    params: {
+        [K in DeepKeys<T>]: PathValue<T, K> extends string ? ExtractParams<PathValue<T, K>> extends never ? Record<string, never> : Record<ExtractParams<PathValue<T, K>>, string | number | boolean> : Record<string, never>;
+    };
+};
+export interface PackageI18n<T extends Translations> {
+    /**
+     * Context-scoped translation **hook**. Call during component initialisation to
+     * get a typed `t` bound to the nearest `<I18nProvider>`'s locale (or the base
+     * locale when none is mounted). This is the SSR-correct, reactive accessor —
+     * re-exported by consumers as `use<Package>I18n`.
+     */
+    useTranslate: () => TypedTranslationFunction<T>;
+    /**
+     * Typed `t` for non-component use (tests, server-side utilities) where no
+     * component context is available. Not bound to a `<I18nProvider>`. In
+     * components always prefer {@link useTranslate}, which is provider-scoped and
+     * reactive.
+     */
+    t: TypedTranslationFunction<T>;
+    exists: (key: string) => boolean;
+    getLocales: () => Locale[];
+    register: () => void;
+    types: CreatePackageTypes<T>;
+}
+export interface I18nComponentProps {
+    locale?: Locale;
+    fallbackToGlobal?: boolean;
+    useI18n?: boolean;
+}
+export {};

package/dist/i18n/types.js

@@ -0,0 +1,18 @@
+/**
+ * Single source of truth for the locales the library declares support for.
+ *
+ * "Declared, data optional": `en`/`de` ship translation data; `fr`/`es`/`it`/`nl`
+ * are valid target locales a consumer can register its own bundles for. The list
+ * lives here exactly once — both the `Locale` union and the runtime
+ * `isLocaleSupported` guard derive from it, so the type and the runtime check can
+ * never drift apart (previously the same six codes were hardcoded twice).
+ */
+export const SUPPORTED_LOCALES = ['en', 'de', 'fr', 'es', 'it', 'nl'];
+/**
+ * Runtime guard derived from {@link SUPPORTED_LOCALES} — the single source of
+ * truth. Used by both the registry and the request-scoped locale state, so the
+ * type and the runtime check can never drift apart.
+ */
+export function isLocaleSupported(locale) {
+    return SUPPORTED_LOCALES.includes(locale);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { I18nProvider, T } from './components';
+export type { I18nApi, I18nConfigureOptions } from './i18n/context.svelte';
+export { BASE_LOCALE, configureI18n, provideI18n, useI18n } from './i18n/context.svelte';
+export type { CreatePackageI18nOptions } from './i18n/package-integration';
+export { createComponentI18n, createPackageI18n, createPackageTranslations, createTypedPackage, registerPackages, registerTranslationLoaders, validatePackageTranslations } from './i18n/package-integration';
+export type { LocaleSource, ResolveLocaleOptions } from './i18n/resolve-locale';
+export { resolveLocale } from './i18n/resolve-locale';
+export type { CreatePackageTypes, I18nComponentProps, I18nConfig, I18nError, I18nStore, Locale, PackageI18n, PackageTranslations, PluralParams, PluralRules, TranslationFunction, TranslationLoader, TranslationOptions, TranslationParams, Translations, TypedTranslationFunction } from './i18n/types';
+export { isLocaleSupported, SUPPORTED_LOCALES } from './i18n/types';
+export type { DeepKeys, DeepValue } from './utils/deep-keys';
+export { collectDeepKeys, getDeepValue, hasDeepKey } from './utils/deep-keys';

package/dist/index.js

@@ -0,0 +1,13 @@
+// --- Request-scoped i18n (WP2: SSR-correct, Context-based) ---
+// 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';
+export { BASE_LOCALE, configureI18n, provideI18n, useI18n } from './i18n/context.svelte';
+// Package integration utilities
+export { createComponentI18n, createPackageI18n, createPackageTranslations, createTypedPackage, registerPackages, registerTranslationLoaders, validatePackageTranslations } from './i18n/package-integration';
+// Server-side initial-locale resolution (cookie + Accept-Language) for the
+// provider's `locale` prop. SSR/hydration-stable.
+export { resolveLocale } from './i18n/resolve-locale';
+// Supported-locale list + runtime guard — single source of truth; `Locale` derives from it.
+export { isLocaleSupported, SUPPORTED_LOCALES } from './i18n/types';
+export { collectDeepKeys, getDeepValue, hasDeepKey } from './utils/deep-keys';

package/dist/utils/deep-keys.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Utility type to extract all possible deep keys from a nested object
+ * Used for type-safe translation key access
+ */
+export type DeepKeys<T> = T extends Record<string, unknown> ? {
+    [K in keyof T]: K extends string ? T[K] extends Record<string, unknown> ? `${K}` | `${K}.${DeepKeys<T[K]>}` : `${K}` : never;
+}[keyof T] : never;
+/**
+ * Utility type to get the value at a specific deep key path
+ */
+export type DeepValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? DeepValue<T[K], Rest> : never : P extends keyof T ? T[P] : never;
+/**
+ * Runtime function to get nested value from object
+ */
+export declare function getDeepValue<T extends Record<string, unknown>>(obj: T, path: string): unknown;
+/**
+ * Runtime function to check if a deep key exists in an object
+ */
+export declare function hasDeepKey<T extends Record<string, unknown>>(obj: T, path: string): boolean;
+/**
+ * Runtime counterpart to the `DeepKeys` type: collects every leaf-key path of a
+ * nested translation object (dotted, e.g. `form.label.required`). A leaf is any
+ * non-object value (the translation strings); nested objects recurse. Used by
+ * `validatePackageTranslations` to diff locale bundles structurally — two
+ * bundles with the same leaf-key set are key-compatible.
+ */
+export declare function collectDeepKeys(obj: Record<string, unknown>, prefix?: string): string[];

package/dist/utils/deep-keys.js

@@ -0,0 +1,54 @@
+/**
+ * Runtime function to get nested value from object
+ */
+export function getDeepValue(obj, path) {
+    const keys = path.split('.');
+    let value = obj;
+    for (const key of keys) {
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        value = value[key];
+    }
+    return value;
+}
+/**
+ * Runtime function to check if a deep key exists in an object
+ */
+export function hasDeepKey(obj, path) {
+    const keys = path.split('.');
+    let value = obj;
+    for (const key of keys) {
+        if (typeof value !== 'object' || value === null || !(key in value)) {
+            return false;
+        }
+        value = value[key];
+    }
+    return true;
+}
+/**
+ * Runtime counterpart to the `DeepKeys` type: collects every leaf-key path of a
+ * nested translation object (dotted, e.g. `form.label.required`). A leaf is any
+ * non-object value (the translation strings); nested objects recurse. Used by
+ * `validatePackageTranslations` to diff locale bundles structurally — two
+ * bundles with the same leaf-key set are key-compatible.
+ */
+export function collectDeepKeys(obj, prefix = '') {
+    const entries = Object.entries(obj);
+    // An empty nested object still occupies its key path — emit it instead of
+    // recursing into nothing, so `{ a: {} }` yields `['a']` rather than `[]`.
+    // Otherwise a structural divergence like `{a:{}}` vs `{a:'x'}` would go
+    // undetected. (The empty ROOT object, prefix='', correctly yields `[]`.)
+    if (entries.length === 0)
+        return prefix ? [prefix] : [];
+    const out = [];
+    for (const [key, value] of entries) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            out.push(...collectDeepKeys(value, path));
+        }
+        else {
+            out.push(path);
+        }
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@urbicon-ui/i18n",
+  "version": "6.1.4",
+  "description": "Runes-based localization for Svelte 5 apps and the Urbicon UI design system",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/urbicon/ui.git",
+    "directory": "packages/i18n"
+  },
+  "homepage": "https://ui.urbicon.de",
+  "bugs": "https://codeberg.org/urbicon/ui/issues",
+  "keywords": [
+    "svelte",
+    "i18n",
+    "internationalization",
+    "localization",
+    "urbicon-ui",
+    "design-system"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@sveltejs/kit": "^2.65.2",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@types/node": "^25.9.3",
+    "@urbicon-ui/shared-types": "6.1.4",
+    "prettier": "^3.8.4",
+    "prettier-plugin-svelte": "^4.1.1",
+    "prettier-plugin-tailwindcss": "^0.8.0",
+    "svelte": "^5.56.3",
+    "svelte-check": "^4.6.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*",
+    "README.md"
+  ],
+  "main": "dist/index.js",
+  "sideEffects": false,
+  "peerDependencies": {
+    "@sveltejs/kit": "^2.65.2",
+    "svelte": "^5.56.3",
+    "@urbicon-ui/shared-types": "^6.0.0"
+  },
+  "scripts": {
+    "dev": "svelte-package --watch",
+    "build": "svelte-kit sync && svelte-package",
+    "clean": "rm -rf dist .svelte-kit",
+    "clean-all": "bun --bun run clean && rm -rf node_modules",
+    "package": "svelte-kit sync && svelte-package",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "format": "biome format --write . && prettier --write \"**/*.svelte\"",
+    "lint": "biome check . && svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "svelte": "./dist/index.js",
+  "type": "module",
+  "types": "./dist/index.d.ts"
+}