@vobs/i18n 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobsjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/i18n
+ */
+import { type WritableSignal } from '@vobs/reactivity';
+import { type InjectionKey, type Owner } from '@vobs/runtime-core';
+export type LocaleCode = string;
+export type MessageValue = string;
+export type MessageParams = Readonly<Record<string, string | number | boolean | null | undefined>>;
+export type LocaleMessages = Readonly<Record<string, MessageValue>>;
+export type LocaleMessageCatalog = Readonly<Record<LocaleCode, LocaleMessages | undefined>>;
+/** DI injection key: provide(I18nKey, i18n) at app assembly; components/pages consume via useI18n (resolved along the InjectionScope parent chain). */
+export declare const I18nKey: InjectionKey<I18nInstance>;
+/** The injection capability subset useI18n needs (structurally compatible with ComponentSetupContext/PageSetupContext provide/maybeInject). */
+export interface I18nInjectionHost {
+    provide<T>(key: InjectionKey<T>, value: T): () => void;
+    maybeInject<T>(key: InjectionKey<T>): T | undefined;
+}
+/**
+ * App assembly: provides the I18n instance into the injection chain in root component/page setup;
+ * child components get it via useI18n along the InjectionScope parent chain (multiple instances can coexist, isolated by assembly level).
+ */
+export declare function provideI18n(context: I18nInjectionHost, instance: I18nInstance): () => void;
+/**
+ * Gets the I18n instance in a component/page (composition API):
+ * - component setup: `const i18n = useI18n(context)`, context is ComponentSetupContext
+ * - page setup: `const i18n = useI18n(context)`, context is PageSetupContext
+ * - the app must provideI18n(context, i18n) at the root; returns undefined when not injected, the caller decides the fallback (e.g. show the raw key).
+ */
+export declare function useI18n<Schema extends LocaleCatalogSchema = LocaleCatalogSchema>(context: I18nInjectionHost): I18nInstance<Schema> | undefined;
+/** Nested message schema: values are either strings (leaves) or nested objects (`menu.file.save` dotted paths). */
+export interface LocaleMessageSchema {
+    readonly [key: string]: MessageValue | LocaleMessageSchema;
+}
+/** Nested schema organized by locale (for defineMessages/createI18n generic inference). */
+export type LocaleCatalogSchema = Readonly<Record<LocaleCode, LocaleMessageSchema | undefined>>;
+/** Decrements recursion depth (P0-C: prevents deep schemas from triggering TS combinatorial explosion/depth limits). Any N returns a decreased value; recursion stops at zero. */
+type DecrementDepth<N extends number> = N extends 0 | 1 ? 0 : N extends 2 ? 1 : N extends 3 ? 2 : N extends 4 ? 3 : N extends 5 ? 4 : N extends 6 ? 5 : N extends 7 ? 6 : 7;
+/**
+ * Derives all leaf keys of a nested schema (dotted-path union): `{ menu: { file: { save } }, hello }` → `'menu.file.save' | 'hello'`.
+ * `Depth` (default 5) caps recursion; subtrees degrade to `string` at zero — deep schemas do not hit TS depth limits/union
+ * explosion, and top-level type safety is unaffected (P0-C).
+ */
+export type MessageKey<Schema extends LocaleMessageSchema, Depth extends number = 5> = {
+    readonly [Key in keyof Schema & string]: Schema[Key] extends MessageValue ? Key : Schema[Key] extends LocaleMessageSchema ? Depth extends 0 ? string : `${Key}.${MessageKey<Schema[Key], DecrementDepth<Depth>>}` : never;
+}[keyof Schema & string];
+/** Derives the message key union from a catalog schema (takes the first locale's schema). Depth is passed through to MessageKey (P0-C). */
+export type CatalogMessageKey<Schema extends LocaleCatalogSchema, Depth extends number = 5> = Schema[keyof Schema] extends LocaleMessageSchema ? MessageKey<Schema[keyof Schema], Depth> : string;
+/** Declares a message schema type-safely: keeps the nested structure for createI18n's key union inference. */
+export declare function defineMessages<const Schema extends LocaleMessageSchema>(messages: Schema): Schema;
+/** Missing level: 'fallback' = missing in the active locale but the fallback hit (translation fell back); 'all' = missing from every catalog. */
+export type MissingMessageLevel = 'fallback' | 'all';
+/** Diagnostic data for the missing handler: distinguishes missing levels to locate catalog configuration issues. */
+export interface MissingMessageInfo {
+    /** Missing level (see MissingMessageLevel). */
+    readonly level: MissingMessageLevel;
+    /** Configured fallback locale (undefined when not configured). */
+    readonly fallbackLocale?: LocaleCode;
+}
+export interface I18nOptions {
+    readonly locale: LocaleCode;
+    readonly fallbackLocale?: LocaleCode;
+    /**
+     * Message catalog: flat or nested (dotted paths); nested catalogs are flattened at creation.
+     * Broadly typed (LocaleCatalogSchema values may nest) — type safety comes from explicit `createI18n<typeof messages>`.
+     */
+    readonly messages?: LocaleCatalogSchema;
+    /**
+     * Missing-key handler (default console.warn + return the key).
+     * The third arg info.level distinguishes: 'fallback' (missing in the active locale, translation fell back, return value ignored),
+     * 'all' (missing from every catalog, return value is used as display text).
+     */
+    readonly missing?: (key: string, locale: LocaleCode, info?: MissingMessageInfo) => string;
+    /** Owner the I18n instance belongs to (default currentOwner); the instance is released on Owner disposal. */
+    readonly owner?: Owner;
+}
+export interface I18nInstance<Schema extends LocaleCatalogSchema = LocaleCatalogSchema> {
+    readonly locale: WritableSignal<LocaleCode>;
+    readonly fallbackLocale: LocaleCode | undefined;
+    /** Flattened catalog (dotted-path keys). */
+    readonly messages: LocaleMessageCatalog;
+    /** Translate: key is constrained by the schema type (nested keys use dotted paths). */
+    t<Key extends CatalogMessageKey<Schema>>(key: Key, params?: MessageParams): string;
+    setLocale(locale: LocaleCode): void;
+    addMessages(locale: LocaleCode, messages: LocaleMessageSchema): void;
+    hasMessage(key: string, locale?: LocaleCode): boolean;
+    formatDate(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;
+    formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit): string;
+    /** Releases the instance (idempotent). Called automatically on Owner disposal. */
+    dispose(): void;
+}
+export interface SerializedI18nState {
+    readonly locale: LocaleCode;
+    readonly fallbackLocale?: LocaleCode;
+    readonly messages: LocaleMessageCatalog;
+}
+export declare function createI18n<const Schema extends LocaleCatalogSchema = LocaleCatalogSchema>(options: I18nOptions): I18nInstance<Schema>;
+export declare function serializeI18nState(instance: I18nInstance): SerializedI18nState;
+/**
+ * Symmetrically rebuilds an I18n instance from serialized state (contract §4):
+ * serialize and hydrate are a pair — SSR serializes, and before client hydration this rebuilds,
+ * keeping first-screen translations identical to the SSR output (see the Security contract's SSR state boundary).
+ */
+export declare function createI18nFromState(state: SerializedI18nState, options?: Pick<I18nOptions, 'missing' | 'owner'>): I18nInstance;
+export {};

package/dist/index.js

@@ -0,0 +1,339 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/i18n
+ */
+import { signal } from '@vobs/reactivity';
+import { createInjectionKey, currentOwner, TranslationAdapterKey, } from '@vobs/runtime-core';
+/** DI injection key: provide(I18nKey, i18n) at app assembly; components/pages consume via useI18n (resolved along the InjectionScope parent chain). */
+export const I18nKey = createInjectionKey('vobs.i18n');
+/**
+ * App assembly: provides the I18n instance into the injection chain in root component/page setup;
+ * child components get it via useI18n along the InjectionScope parent chain (multiple instances can coexist, isolated by assembly level).
+ */
+export function provideI18n(context, instance) {
+    const undoI18n = context.provide(I18nKey, instance);
+    // Register the TranslationAdapter port: template {{@key}} / :attr="@key" is translated through it (overridable by a user-defined adapter)
+    const undoAdapter = context.provide(TranslationAdapterKey, {
+        t: (key, params) => instance.t(key, params),
+        locale: instance.locale,
+    });
+    return () => {
+        undoI18n();
+        undoAdapter();
+    };
+}
+/**
+ * Gets the I18n instance in a component/page (composition API):
+ * - component setup: `const i18n = useI18n(context)`, context is ComponentSetupContext
+ * - page setup: `const i18n = useI18n(context)`, context is PageSetupContext
+ * - the app must provideI18n(context, i18n) at the root; returns undefined when not injected, the caller decides the fallback (e.g. show the raw key).
+ */
+export function useI18n(context) {
+    return context.maybeInject(I18nKey);
+}
+/** Declares a message schema type-safely: keeps the nested structure for createI18n's key union inference. */
+export function defineMessages(messages) {
+    return messages;
+}
+/** Flattens a nested schema into a dotted-path flat map (internal storage/lookup shape). */
+function flattenMessages(schema, prefix = '') {
+    const flattened = {};
+    for (const [key, value] of Object.entries(schema)) {
+        const path = prefix === '' ? key : `${prefix}.${key}`;
+        if (typeof value === 'string') {
+            flattened[path] = value;
+        }
+        else {
+            Object.assign(flattened, flattenMessages(value, path));
+        }
+    }
+    return flattened;
+}
+export function createI18n(options) {
+    const locale = signal(options.locale);
+    const catalogVersion = signal(0);
+    const catalogs = {};
+    for (const [messageLocale, catalog] of Object.entries(options.messages ?? {})) {
+        if (catalog !== undefined && catalog !== null && typeof catalog === 'object') {
+            catalogs[messageLocale] = flattenMessages(catalog);
+        }
+    }
+    const missing = options.missing ??
+        ((key, locale, info) => {
+            if (typeof console !== 'undefined') {
+                if (info?.level === 'fallback') {
+                    console.warn(`[vobs i18n] Missing message: "${key}" in locale "${locale}" (fallback "${info.fallbackLocale ?? ''}")`);
+                }
+                else {
+                    console.warn(`[vobs i18n] Missing message: "${key}"`);
+                }
+            }
+            return key;
+        });
+    const resolveMessage = (key, activeLocale, params, depth) => {
+        if (depth > 8)
+            return key;
+        const activeMessage = catalogs[activeLocale]?.[key];
+        const fallbackMessage = options.fallbackLocale === undefined ? undefined : catalogs[options.fallbackLocale]?.[key];
+        if (activeMessage === undefined && fallbackMessage === undefined) {
+            // missing from every catalog: the missing return value is used as display text.
+            return missing(key, activeLocale, {
+                level: 'all',
+                ...(options.fallbackLocale === undefined ? {} : { fallbackLocale: options.fallbackLocale }),
+            });
+        }
+        const message = activeMessage ?? fallbackMessage;
+        if (message === undefined)
+            return key;
+        if (activeMessage === undefined) {
+            // missing in the active locale but the fallback hit: diagnostics distinguish the level; translation still uses the fallback text (the missing return value is ignored).
+            void missing(key, activeLocale, {
+                level: 'fallback',
+                ...(options.fallbackLocale === undefined ? {} : { fallbackLocale: options.fallbackLocale }),
+            });
+        }
+        return formatMessage(message, activeLocale, params, (nestedKey) => resolveMessage(nestedKey, activeLocale, params, depth + 1));
+    };
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+    };
+    const owner = options.owner ?? currentOwner();
+    if (owner !== undefined) {
+        owner.own(dispose);
+    }
+    const instance = {
+        locale,
+        fallbackLocale: options.fallbackLocale,
+        get messages() {
+            return catalogs;
+        },
+        t(key, params) {
+            void catalogVersion.value;
+            return resolveMessage(key, locale.value, params, 0);
+        },
+        setLocale(nextLocale) {
+            locale.value = nextLocale;
+        },
+        addMessages(messageLocale, nextMessages) {
+            catalogs[messageLocale] = {
+                ...(catalogs[messageLocale] ?? {}),
+                ...flattenMessages(nextMessages),
+            };
+            catalogVersion.value += 1;
+        },
+        hasMessage(key, messageLocale = locale.value) {
+            return catalogs[messageLocale]?.[key] !== undefined;
+        },
+        formatDate(value, formatOptions) {
+            return cachedDateTimeFormat(locale.value, formatOptions).format(new Date(value));
+        },
+        formatNumber(value, formatOptions) {
+            return cachedNumberFormat(locale.value, formatOptions).format(value);
+        },
+        formatCurrency(value, currency, formatOptions) {
+            return cachedNumberFormat(locale.value, {
+                style: 'currency',
+                currency,
+                ...formatOptions,
+            }).format(value);
+        },
+        formatRelativeTime(value, unit) {
+            return cachedRelativeTimeFormat(locale.value).format(value, unit);
+        },
+        dispose,
+    };
+    return instance;
+}
+export function serializeI18nState(instance) {
+    return {
+        locale: instance.locale.value,
+        ...(instance.fallbackLocale === undefined ? {} : { fallbackLocale: instance.fallbackLocale }),
+        messages: instance.messages,
+    };
+}
+/**
+ * Symmetrically rebuilds an I18n instance from serialized state (contract §4):
+ * serialize and hydrate are a pair — SSR serializes, and before client hydration this rebuilds,
+ * keeping first-screen translations identical to the SSR output (see the Security contract's SSR state boundary).
+ */
+export function createI18nFromState(state, options = {}) {
+    return createI18n({
+        locale: state.locale,
+        ...(state.fallbackLocale === undefined ? {} : { fallbackLocale: state.fallbackLocale }),
+        messages: state.messages,
+        ...(options.missing === undefined ? {} : { missing: options.missing }),
+        ...(options.owner === undefined ? {} : { owner: options.owner }),
+    });
+}
+function formatMessage(message, locale, params, resolveKey) {
+    if (!message.includes('{'))
+        return message;
+    let result = '';
+    let cursor = 0;
+    while (cursor < message.length) {
+        const open = message.indexOf('{', cursor);
+        if (open < 0) {
+            result += message.slice(cursor);
+            break;
+        }
+        result += message.slice(cursor, open);
+        const close = findClosingBrace(message, open);
+        if (close < 0) {
+            result += message.slice(open);
+            break;
+        }
+        result += formatPlaceholder(message.slice(open + 1, close), locale, params, resolveKey);
+        cursor = close + 1;
+    }
+    return result;
+}
+function formatPlaceholder(source, locale, params, resolveKey) {
+    const content = source.trim();
+    if (content === '')
+        return '{}';
+    if (content.startsWith('@')) {
+        return resolveKey(content.slice(1).trim());
+    }
+    const parts = splitTopLevel(content, ',');
+    const name = parts[0]?.trim() ?? '';
+    const type = parts[1]?.trim();
+    if (type === 'plural') {
+        return formatPlural(name, parts.slice(2).join(','), locale, params, resolveKey);
+    }
+    if (type === 'select') {
+        return formatSelect(name, parts.slice(2).join(','), locale, params, resolveKey);
+    }
+    if (name === '')
+        return `{${content}}`;
+    const value = params?.[name];
+    return value === null || value === undefined ? `{${name}}` : String(value);
+}
+function findClosingBrace(message, open) {
+    let depth = 0;
+    for (let index = open; index < message.length; index += 1) {
+        const char = message[index];
+        if (char === '{')
+            depth += 1;
+        else if (char === '}') {
+            depth -= 1;
+            if (depth === 0)
+                return index;
+        }
+    }
+    return -1;
+}
+function splitTopLevel(source, separator) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const char of source) {
+        if (char === '{') {
+            depth += 1;
+            current += char;
+        }
+        else if (char === '}') {
+            depth -= 1;
+            current += char;
+        }
+        else if (char === separator && depth === 0) {
+            parts.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+function parseCases(body) {
+    const cases = [];
+    let index = 0;
+    while (index < body.length) {
+        while (index < body.length && /\s/u.test(body[index] ?? ''))
+            index += 1;
+        if (index >= body.length)
+            break;
+        const open = body.indexOf('{', index);
+        if (open < 0)
+            break;
+        const match = body.slice(index, open).trim();
+        const close = findClosingBrace(body, open);
+        if (close < 0)
+            break;
+        cases.push({ match, content: body.slice(open + 1, close) });
+        index = close + 1;
+    }
+    return cases;
+}
+function formatPlural(name, body, locale, params, resolveKey) {
+    const cases = parseCases(body);
+    const value = params?.[name];
+    if (typeof value === 'number') {
+        const category = cachedPluralRules(locale).select(value);
+        const exact = cases.find((entry) => entry.match === `=${value}`);
+        if (exact !== undefined)
+            return formatMessage(exact.content, locale, params, resolveKey);
+        const matched = cases.find((entry) => entry.match === category);
+        if (matched !== undefined)
+            return formatMessage(matched.content, locale, params, resolveKey);
+    }
+    const other = cases.find((entry) => entry.match === 'other');
+    return other === undefined ? '' : formatMessage(other.content, locale, params, resolveKey);
+}
+function formatSelect(name, body, locale, params, resolveKey) {
+    const cases = parseCases(body);
+    const value = params?.[name];
+    const stringValue = value === null || value === undefined ? undefined : String(value);
+    if (stringValue !== undefined) {
+        const matched = cases.find((entry) => entry.match === stringValue);
+        if (matched !== undefined)
+            return formatMessage(matched.content, locale, params, resolveKey);
+    }
+    const other = cases.find((entry) => entry.match === 'other');
+    return other === undefined ? '' : formatMessage(other.content, locale, params, resolveKey);
+}
+// Intl constructor cache: PluralRules/NumberFormat/DateTimeFormat/RelativeTimeFormat are expensive to construct;
+// instances for the same locale are reusable (allowed by the Intl spec, results unchanged). Module-level caches are
+// shared across instances and grow with the number of locales (bounded).
+const pluralRulesCache = new Map();
+const numberFormatCache = new Map();
+const dateTimeFormatCache = new Map();
+const relativeTimeFormatCache = new Map();
+function cachedPluralRules(locale) {
+    let rules = pluralRulesCache.get(locale);
+    if (rules === undefined) {
+        rules = new Intl.PluralRules(locale);
+        pluralRulesCache.set(locale, rules);
+    }
+    return rules;
+}
+function cachedNumberFormat(locale, options) {
+    const key = options === undefined ? locale : `${locale}\u0000${JSON.stringify(options)}`;
+    let format = numberFormatCache.get(key);
+    if (format === undefined) {
+        format = new Intl.NumberFormat(locale, options);
+        numberFormatCache.set(key, format);
+    }
+    return format;
+}
+function cachedDateTimeFormat(locale, options) {
+    const key = options === undefined ? locale : `${locale}\u0000${JSON.stringify(options)}`;
+    let format = dateTimeFormatCache.get(key);
+    if (format === undefined) {
+        format = new Intl.DateTimeFormat(locale, options);
+        dateTimeFormatCache.set(key, format);
+    }
+    return format;
+}
+function cachedRelativeTimeFormat(locale) {
+    let format = relativeTimeFormatCache.get(locale);
+    if (format === undefined) {
+        format = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+        relativeTimeFormatCache.set(locale, format);
+    }
+    return format;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vobs/i18n",
+  "version": "0.1.0",
+  "description": "Instance-based translation and Intl formatting primitives for vobs.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "vobsjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vobsjs/vobs.git",
+    "directory": "packages/features/i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/vobsjs/vobs/issues"
+  },
+  "homepage": "https://github.com/vobsjs/vobs#readme",
+  "dependencies": {
+    "@vobs/reactivity": "0.1.0",
+    "@vobs/runtime-core": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}