@qilin-agent/client-locale 0.0.0-stage → 3.1.4

package/lib/index.js

@@ -0,0 +1,27 @@
+import z from "@qilin-agent/schemastery";
+//#region lib/types/locale-settings.js
+/** Locale preference stored in the Host user-settings document. */
+/** Settings namespace owned by the locale plugin. */
+const LOCALE_SETTINGS_NAMESPACE = "locale";
+/** Field carrying an explicit locale selection; absence delegates to the browser. */
+const LOCALE_PREFERENCE_FIELD = "preference";
+/** Accepted BCP 47-style language ids. */
+const LOCALE_ID_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u;
+/** Locale identifiers shipped by the browser client. */
+const LOCALE_IDS = ["zh", "en"];
+/** Durable locale schema; also the wire envelope the browser scope validates against. */
+const LocaleSettingsSchema = z.object({ [LOCALE_PREFERENCE_FIELD]: z.string().pattern(LOCALE_ID_PATTERN).required(false) });
+//#endregion
+//#region lib/types/index.js
+/** Host registration for the browser locale preference. */
+/**
+* Register the durable locale section when a settings provider exists.
+* @param ctx - Host context whose optional settings service owns the section.
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.register(LOCALE_SETTINGS_NAMESPACE, LocaleSettingsSchema);
+	});
+}
+//#endregion
+export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, apply };

package/lib/types/client/index.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Browser-side locale registry. Bound translation functions retain stable
+ * identity for injected consumers. The account menu is the surface that
+ * switches languages; this plugin owns the preference, the registry, and the
+ * document language attribute.
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import type { LocalizedText } from '@qilin-agent/package-manifest';
+import { type LocaleDictOf, type LocaleNamespaceMap, type Translate, type TranslateNS } from '@qilin-agent/client-ui-slots';
+import type { ConfigForm } from '@qilin-agent/client-ui-settings/client';
+import { type BuiltInLocaleId, type LocaleId, type LocaleSettings } from '../locale-settings.ts';
+import { type CommonKey } from '../locales/index.ts';
+export type { CommonKey } from '../locales/index.ts';
+export type { BuiltInLocaleId, LocaleId, LocaleSettings } from '../locale-settings.ts';
+export type { Translate, TranslateNS } from '@qilin-agent/client-ui-slots';
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Shared cross-feature vocabulary, consulted by the lookup chain after the entry's own namespace misses. */
+        common: CommonKey;
+    }
+}
+/** Locale dictionary: flat key to template string ({name} placeholders). */
+export type LocaleDict = Record<string, string>;
+/** Input accepted when a language-pack plugin adds a selectable language. */
+export interface LanguageRegistration {
+    /** Stable BCP 47-style id stored as the locale preference. */
+    id: LocaleId;
+    /** Display name written in the represented language. */
+    label: string;
+    /** Registered language consulted when this language lacks a dictionary key. */
+    fallback: LocaleId;
+}
+/** One normalized selectable locale published in snapshots. */
+export interface LocaleDefinition {
+    /** Stable id persisted by {@link LocaleRuntime.setLocale}. */
+    readonly id: LocaleId;
+    /** Display name written in the represented language. */
+    readonly label: string;
+    /** Next language in the per-key fallback chain; absent only for English. */
+    readonly fallback?: LocaleId;
+}
+/** Immutable locale state published on every change. */
+export interface LocaleSnapshot {
+    /** Active locale id. */
+    active: LocaleId;
+    /** Selectable locales in display order. */
+    locales: readonly LocaleDefinition[];
+    /** Monotonic change counter (registry or active changes). */
+    revision: number;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        locale: LocaleRuntime;
+    }
+    interface Events {
+        /**
+         * The active locale switched. Dictionary registrations do NOT emit this
+         * event (listeners may re-register slots in response, and boot registers
+         * one namespace per package); continuous render refresh rides the
+         * LocaleFace revision instead.
+         * @param snapshot - Current immutable locale snapshot.
+         * @mode emit
+         */
+        'locale/change'(snapshot: LocaleSnapshot): void;
+    }
+}
+/**
+ * English is both the locale the UI opens in when the browser names no registered
+ * language (and for non-browser runs), and the dictionary consulted after the
+ * active locale misses a key. One constant serves both because the shipped
+ * `zh`/`en` dictionaries carry identical key sets, so neither direction can
+ * leave a key unresolved; the residual case points at English rather than
+ * zh because a browser naming no registered language is the reader least
+ * likely to read Chinese.
+ */
+export declare const FALLBACK_LOCALE: BuiltInLocaleId;
+/** Shared namespace for shell-level texts. */
+export declare const COMMON_NS = "common";
+/**
+ * Dictionary registry plus locale preference. Lookup walks the active
+ * language's declared fallback chain in the entry namespace, then repeats it
+ * in the shared common namespace before showing the key itself. Reads go
+ * through {@link getLocale}; preferences change only through
+ * {@link setLocale}, while language packs extend the catalog through
+ * {@link addLanguage}. Continuous sync uses the `locale/change` event or
+ * the LocaleFace getSnapshot/subscribe pair installed through
+ * `ctx.slots.installLocale`.
+ */
+export declare class LocaleRuntime {
+    private dicts;
+    private bound;
+    private catalog;
+    private fallbackChains;
+    private snapshot;
+    private listeners;
+    private readonly ctx;
+    private readonly host;
+    /** Browser-derived locale standing wherever no explicit Host selection does. */
+    private provisional;
+    /** Last explicit selection, including one awaiting an external registration. */
+    private preference;
+    /**
+     * @param ctx - owning context (change events are emitted on it; the scope
+     * listener is released through ctx.effect on dispose).
+     * @param host - durable preference scope owned by the providing plugin;
+     * absent compositions (standalone dictionary registries) stay process-local.
+     */
+    constructor(ctx: ClientContext, host?: ConfigForm<LocaleSettings>);
+    /**
+     * Read the current immutable locale snapshot.
+     * @returns the current snapshot (stable reference until the next change).
+     */
+    getLocale(): LocaleSnapshot;
+    /**
+     * Resolve package text through the active language's declared fallback chain.
+     * Plain strings stay verbatim; maps do not consult registered dictionaries.
+     * @param text - package text whose locale keys are lowercase and include English.
+     * @returns the first available translation, including an empty string.
+     */
+    resolveText(text: LocalizedText): string;
+    /**
+     * LocaleFace getSnapshot: the current snapshot (carries `revision`; stable
+     * reference between changes, uSES-safe).
+     * @returns the current snapshot.
+     */
+    getSnapshot(): LocaleSnapshot;
+    /**
+     * LocaleFace subscribe: notified on every snapshot change (locale switch
+     * or dictionary registration — registrations bump the revision so already
+     * rendered outlets pick up late-arriving dictionaries and locale definitions).
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Switch the active locale — the only user preference write entry.
+     *
+     * The durable write happens even when the id already matches the active
+     * locale, because the active value may be a provisional browser-derived or
+     * fallback resolution that nothing has stored yet. Picking the language
+     * already on screen is still an explicit choice, and it must survive a
+     * different browser sharing the same QILIN home. Only the render notification
+     * is conditional: republishing an unchanged locale would churn every
+     * subscriber for nothing.
+     * @param id - a registered locale id; unknown ids throw.
+     */
+    setLocale(id: string): void;
+    /**
+     * Add one selectable language to the shared catalog. Its fallback must
+     * already be registered, and following fallback definitions must terminate
+     * at English. Dictionaries may register before or after this definition.
+     * Registration rechecks an unresolved Host preference and the browser's
+     * ordered language list. The caller owns the returned disposer; removing an
+     * active language falls back without clearing the stored id.
+     * @param input - stable id, self-described label, and fallback language id.
+     * @returns idempotent disposer removing this exact definition.
+     * @throws when fields are malformed, the id is occupied, or the fallback
+     * target is unknown or creates a cycle.
+     */
+    addLanguage(input: LanguageRegistration): () => void;
+    /**
+     * Adopt the scope's accepted durable selection without writing it back; an
+     * absent selection returns to the browser-derived locale.
+     * @param host - the constructor-narrowed scope driving this adoption.
+     */
+    private adopt;
+    /** Recompute browser fallback and publish the current catalog. */
+    private publishCatalog;
+    /** Resolve an explicit preference only while its definition is available. */
+    private resolveActive;
+    /** Snapshot the catalog in registration order. */
+    private localeList;
+    /** Fail a new definition whose complete fallback path does not reach English. */
+    private assertFallbackChain;
+    /** Resolve a lookup chain, falling directly to English across an unload gap. */
+    private fallbackChain;
+    /**
+     * Register a declared namespace's dictionaries, all locales in one call —
+     * the typed form: each dictionary is checked against the namespace's
+     * {@link LocaleNamespaceMap} key union (a missing or extra key is a
+     * compile error), and every shipped locale is required (bilingual balance
+     * enforced at registration). Duplicate (ns, locale) throws (single occupant; a
+     * namespace's texts have one owner). Registration bumps the revision so
+     * mounted outlets pick up late-arriving dictionaries.
+     * @param ns - a namespace merged into LocaleNamespaceMap.
+     * @param dicts - complete dictionaries keyed by built-in locale id.
+     * @returns disposer removing every locale registered by this call (idempotent).
+     */
+    register<N extends Extract<keyof LocaleNamespaceMap, string>>(ns: N, dicts: Record<BuiltInLocaleId, LocaleDictOf<N>>): () => void;
+    /**
+     * Single-locale untyped form for language-pack contributions and namespaces
+     * outside the merge table.
+     * @param ns - namespace.
+     * @param locale - locale tag.
+     * @param dict - dictionary.
+     * @returns disposer (idempotent).
+     * @throws when locale is not a BCP 47-style tag.
+     */
+    register(ns: string, locale: string, dict: LocaleDict): () => void;
+    /**
+     * Bind a declared namespace to a translate function typed to its
+     * dictionary key union (plus the shared common vocabulary) — the same key
+     * domain the framework-injected `t` seat carries. The returned reference
+     * is stable per namespace (repeat binds return the same function), so it
+     * can ride inject surfaces without breaking memoization.
+     * @param ns - a namespace merged into LocaleNamespaceMap.
+     * @returns the typed translate function (reads the active locale at call time).
+     */
+    bind<N extends Extract<keyof LocaleNamespaceMap, string>>(ns: N): TranslateNS<N>;
+    /**
+     * Untyped form for namespaces outside the merge table (dynamic
+     * composition, tests).
+     * @param ns - namespace.
+     * @returns the translate function.
+     */
+    bind(ns: string): Translate;
+    private translate;
+    private lookup;
+    /**
+     * Advance the snapshot revision and notify LocaleFace subscribers (render
+     * refresh). Only an active-locale switch additionally emits
+     * `locale/change` — dictionary registrations stay off the event so
+     * registration-heavy boot cannot storm event listeners (which may
+     * re-register slots in response).
+     */
+    private publish;
+}
+/** Required services: slot registration plus the settings transport. */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide the locale service with base dictionaries and
+ * keep `<html lang>` in step with the active locale. The account menu is the
+ * surface that switches languages; this plugin owns the preference and its
+ * registry, not a settings row.
+ * @param ctx - client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/** Host registration for the browser locale preference. */
+import type { Context } from '@qilin-agent/kylin';
+export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, type BuiltInLocaleId, type LocaleId, type LocaleSettings, } from './locale-settings.ts';
+/**
+ * Register the durable locale section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/locale-settings.d.ts

@@ -0,0 +1,22 @@
+/** Locale preference stored in the Host user-settings document. */
+import z from '@qilin-agent/schemastery';
+/** Settings namespace owned by the locale plugin. */
+export declare const LOCALE_SETTINGS_NAMESPACE = "locale";
+/** Field carrying an explicit locale selection; absence delegates to the browser. */
+export declare const LOCALE_PREFERENCE_FIELD = "preference";
+/** Accepted BCP 47-style language ids. */
+export declare const LOCALE_ID_PATTERN: RegExp;
+/** Locale identifiers shipped by the browser client. */
+export declare const LOCALE_IDS: readonly ["zh", "en"];
+/** Locale identifier shipped by the browser client. */
+export type BuiltInLocaleId = typeof LOCALE_IDS[number];
+/** Open locale identifier accepted from language-pack plugins. */
+export type LocaleId = string;
+/** Durable locale section shared by the Host schema and the browser scope. */
+export interface LocaleSettings {
+    /** Explicit locale selection; absence delegates to the browser. */
+    preference?: LocaleId;
+}
+/** Durable locale schema; also the wire envelope the browser scope validates against. */
+export declare const LocaleSettingsSchema: z<LocaleSettings>;
+//# sourceMappingURL=locale-settings.d.ts.map

package/lib/types/locales/en.d.ts

@@ -0,0 +1,43 @@
+/** en base dictionary for the common namespace, checked complete against the zh key set. */
+export declare const en: {
+    ok: string;
+    cancel: string;
+    close: string;
+    copy: string;
+    copied: string;
+    'copy.failed': string;
+    'copy.value': string;
+    'copy.json': string;
+    'copy.path': string;
+    'copy.prettyJson': string;
+    'copy.compactJson': string;
+    'copy.optionsHint': string;
+    retry: string;
+    loading: string;
+    'load.failed': string;
+    submit: string;
+    submitting: string;
+    next: string;
+    previous: string;
+    skip: string;
+    delete: string;
+    edit: string;
+    save: string;
+    search: string;
+    more: string;
+    collapse: string;
+    expand: string;
+    back: string;
+    'brand.localBuild': string;
+    unknown: string;
+    none: string;
+    truncated: string;
+    'json.label': string;
+    'markdown.footnotes': string;
+    'markdown.diagram': string;
+    'markdown.enlarged': string;
+    'markdown.truncatedCharacters': string;
+    'number.thousand': string;
+    'number.million': string;
+};
+//# sourceMappingURL=en.d.ts.map

package/lib/types/locales/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The common-namespace dictionary pair. zh is the source of truth for the
+ * key set (Chinese-first repo convention); en is checked complete against it
+ * — a missing or extra en key is a compile error.
+ */
+export { zh } from './zh.ts';
+export { en } from './en.ts';
+export type { CommonKey } from './zh.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/locales/zh.d.ts

@@ -0,0 +1,45 @@
+/** zh base dictionary for the common namespace: cross-feature standard words. */
+export declare const zh: {
+    ok: string;
+    cancel: string;
+    close: string;
+    copy: string;
+    copied: string;
+    'copy.failed': string;
+    'copy.value': string;
+    'copy.json': string;
+    'copy.path': string;
+    'copy.prettyJson': string;
+    'copy.compactJson': string;
+    'copy.optionsHint': string;
+    retry: string;
+    loading: string;
+    'load.failed': string;
+    submit: string;
+    submitting: string;
+    next: string;
+    previous: string;
+    skip: string;
+    delete: string;
+    edit: string;
+    save: string;
+    search: string;
+    more: string;
+    collapse: string;
+    expand: string;
+    back: string;
+    'brand.localBuild': string;
+    unknown: string;
+    none: string;
+    truncated: string;
+    'json.label': string;
+    'markdown.footnotes': string;
+    'markdown.diagram': string;
+    'markdown.enlarged': string;
+    'markdown.truncatedCharacters': string;
+    'number.thousand': string;
+    'number.million': string;
+};
+/** The common vocabulary key union (zh is the key-set source of truth). */
+export type CommonKey = keyof typeof zh;
+//# sourceMappingURL=zh.d.ts.map

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@qilin-agent/client-locale",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Locale plugin: Host-backed preference, extensible language catalog, browser fallback, and typed built-in dictionaries",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/locale"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/client-connection",
+        "@qilin-agent/client-ui-renderer",
+        "@qilin-agent/client-ui-settings",
+        "@qilin-agent/api-remotes"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/api-remotes": "3.1.4",
+    "@qilin-agent/client-store": "3.1.4",
+    "@qilin-agent/client-test-runtime": "3.1.4",
+    "@qilin-agent/client-ui-primitives": "3.1.4",
+    "@qilin-agent/client-ui-renderer": "3.1.4",
+    "@qilin-agent/client-ui-slots": "3.1.4",
+    "@qilin-agent/package-manifest": "3.1.4",
+    "@qilin-agent/settings": "3.1.4",
+    "@qilin-agent/client-connection": "3.1.4",
+    "@qilin-agent/client-ui-settings": "3.1.4"
+  },
+  "dependencies": {
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }