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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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/README.i18n.yaml

@@ -0,0 +1,61 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/locale/README.md
+/:
+  en: d2aaa955e01c2679
+  zh: a931126ab9ab926b
+/qilin-agent-client-locale:
+  en: d02cd6b9890e9c58
+  zh: b11d4fe387081a59
+/qilin-agent-client-locale/summary:
+  en: 1c05578df3329b4f
+  zh: 623a745a5c8c67ba
+/qilin-agent-client-locale/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-client-locale/use-this-package:
+  en: 7fedfbcbc3ad8cea
+  zh: 210d6b20de8ed41e
+/qilin-agent-client-locale/use-this-package/choosing-a-language:
+  en: 72b9fd7f3a7e728d
+  zh: d2e38e1c85c76556
+/qilin-agent-client-locale/use-this-package/registering-a-dictionary:
+  en: 9b2fcfa8cae8dc4b
+  zh: 5926a024465347f5
+/qilin-agent-client-locale/use-this-package/registering-a-language-pack:
+  en: aa4e9c70523339cc
+  zh: 3359eddc4e9ef15e
+/qilin-agent-client-locale/use-this-package/what-the-host-half-does:
+  en: 8fa91333f7fc3387
+  zh: 789a9cbb3eace3b0
+/qilin-agent-client-locale/understand-the-implementation:
+  en: 288d8db39f9acfc5
+  zh: d65cf2ffae8ad35c
+/qilin-agent-client-locale/understand-the-implementation/design-concept:
+  en: 79dbe4d0f1477a53
+  zh: d3bf1ebae92ed381
+/qilin-agent-client-locale/understand-the-implementation/preference-resolution:
+  en: 4bc9dffa4629f537
+  zh: 0b5049f08416b55c
+/qilin-agent-client-locale/understand-the-implementation/dictionary-lookup:
+  en: e84e0b8712988d24
+  zh: 0adf3e8777a3efa8
+/qilin-agent-client-locale/understand-the-implementation/source-map:
+  en: ceec358b08427206
+  zh: 7fb2acb0de9fb1d1
+/qilin-agent-client-locale/further-exploration:
+  en: 9774cddcd866f390
+  zh: 009b7737a580b20a
+/qilin-agent-client-locale/model-experience:
+  en: 209321ba2d2e6710
+  zh: 21deb6c973f69b66
+/qilin-agent-client-locale/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: de54f3467ef3b9be
+/qilin-agent-client-locale/known-limitations-and-deferred-work:
+  en: 500ede048ef44c6a
+  zh: b134cb622f75b077
+/qilin-agent-client-locale/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+---
+description: "Localization for the web GUI: the zh/en preference, browser-derived fallback, typed namespace dictionaries, and the framework translation seat, for users and plugin authors."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-locale
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `qilin-client-locale` to switch the web GUI between the shipped English and Chinese locales or languages added by client plugins. User selections take effect immediately; loopback pages persist them in `$QILIN_HOME/settings.yaml`, while non-loopback pages keep them only for the current process. New browsers use the first supported language requested by the browser until an allowed stored preference arrives. Plugin authors add typed namespace dictionaries and translate through the public locale API; slot-rendered copy updates without a reload.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use it wherever the web GUI needs a language switch or translated copy: the shipped settings row covers users, and plugin authors register their own dictionaries. Nothing needs configuration to mount — the package activates with the client tree.
+
+### Choosing a language
+
+Open Settings → General and select a registered language. The active locale is applied immediately: the UI copy switches, `<html lang>` points at the external id or built-in document tag, and the choice is written to the durable settings section. A browser without an explicit Host preference selects the first registered language that matches `navigator` by full tag and then primary subtag, falling back to English. A stored external locale waits for its definition to register instead of becoming active while unavailable.
+
+### Registering a dictionary
+
+Call `ctx.locale.register(ns, { zh, en })` with a namespace merged into `LocaleNamespaceMap`; the compiler checks every key against the namespace's typed key union and requires both shipped locales. Consumers translate through `ctx.locale.bind(ns)` or the framework-injected `t` seat. A dictionary registered after the UI is already mounted is picked up without a remount.
+
+### Registering a language pack
+
+An external client plugin registers the language definition and each translated namespace as owned effects; definitions and dictionaries may register in either order:
+
+```js
+export const inject = ['locale']
+
+export function apply(ctx) {
+  ctx.effect(
+    () => ctx.locale.addLanguage({ id: 'ja', label: '日本語', fallback: 'en' }),
+    'my-locale: language',
+  )
+  ctx.effect(
+    () => ctx.locale.register('common', 'ja', {
+      cancel: 'キャンセル',
+      close: '閉じる',
+    }),
+    'my-locale: common dictionary',
+  )
+}
+```
+
+An external id is a non-empty ASCII BCP 47-style tag. Its fallback must already be registered, and the chain must terminate at `en`; unknown targets, duplicate ids, and cycles fail at registration. Lookup walks the fallback chain in the requested namespace, repeats it in `common`, then displays the key. Unloading a definition removes it from the selector and returns an active selection to the available browser/default locale.
+
+### What the Host half does
+
+The Host persists the preference through the settings service on loopback pages. The Client deliberately withholds that settings scope on non-loopback pages, so their locale selection remains process-local even though Connection authenticates every API method.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the locale service is built; observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+One `LocaleRuntime` owns the preference and the dictionary registry, and is itself the slot system's `LocaleFace`: `getSnapshot`/`subscribe` back the framework-injected `t` seat through `ctx.slots.installLocale`. The immutable snapshot carries the active locale, the selectable locales, and a monotonic revision; dictionary registration and locale switches both advance the revision, but only a switch emits the `locale/change` event. Product-authored Client UI text must enter through these typed dictionaries or an already-localized primitive prop; `verify-client-ui-i18n` enforces that source ownership ([decision](../../../.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)).
+
+### Preference resolution
+
+The provisional locale comes from the browser (`navigator.languages` matched by full tag and then primary subtag, English as the fallback), standing in until the allowed Host-backed settings scope delivers its stored preference. The Host read runs after plugin activation so an unavailable or withheld settings scope cannot block the page, and the result replaces the provisional value live. A stored external locale waits for its definition to register. `setLocale` is the only write entry; it persists even when the id already matches the active locale, because the active value may be provisional and must survive a different browser sharing the same home.
+
+### Dictionary lookup
+
+The typed object form requires complete dictionaries for both built-in locales. The per-locale form lets language packs register each namespace independently. For each key, lookup walks the active language's declared fallback chain in the requested namespace, repeats that chain in `common`, then displays the key itself. Bound translate functions retain stable identity per namespace so they can ride inject surfaces without breaking memoization.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/client/index.ts`](src/client/index.ts) | `LocaleRuntime`, dictionary registry, document language synchronization, `locale/change` event |
+| [`src/index.ts`](src/index.ts) | Node half: registers the `locale` settings namespace |
+| [`src/locale-settings.ts`](src/locale-settings.ts) | The durable schema for `locale.preference` |
+| [`src/locales/`](src/locales/) | The shipped `zh`/`en` dictionaries |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these when the locale contract is not enough: the slot face it implements, the settings surface it rides, and the persistence decision behind the preference.
+
+- [Client slot system](../ui-slots/README.md) — the slot model and the `LocaleFace` seat this package implements.
+- [Host-backed preferences decision](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md) — why the preference persists in Host settings instead of the browser.
+- [Settings group map](../../settings/README.md) — the settings service that stores the preference.
+- [Client group map](../README.md) — the browser half this package belongs to.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the locale service is a browser-side UI plugin layer that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where localization is incomplete or frozen at registration time. They are current package constraints, not a task backlog.
+
+- **Registry-held text reads its translation once** — copy captured at registration time outside the slot render path (e.g. the `/model` command description in the command registry) keeps the language it was registered under until re-registration; slot-rendered copy follows switches live.
+- **Language packs own language-specific behavior** — the registry supplies selection, persistence, browser matching, key fallback, and `<html lang>`; it does not add plural rules or bidirectional layout.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,140 @@
+---
+description: "面向用户与插件作者的 web GUI 本地化说明：zh/en 偏好、浏览器派生回退、类型化命名空间词典与框架翻译席位。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-locale
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `qilin-client-locale` 可在 web GUI 中切换内置的 English、中文 locale，或 client 插件添加的语言。用户选择会立即生效；loopback 页面把选择持久化到 `$QILIN_HOME/settings.yaml`，非 loopback 页面则只为当前进程保留选择。全新浏览器会使用浏览器请求的第一个受支持语言，直到允许读取的已存储偏好到达。插件作者可添加类型化命名空间字典，并通过公开 locale API 翻译；经 slot 渲染的文案无需重新加载即可随语言切换更新。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+只要 web GUI 需要语言切换或翻译文案就使用它：已发布的设置行覆盖用户侧，插件作者则注册自己的词典。挂载无需任何配置——本包随客户端树一起激活。
+
+### 选择语言
+
+打开“设置 → 常规”并选择一种已注册语言。生效中的 locale 会立即应用：UI 文案切换、`<html lang>` 指向外部 id 或内置语言的文档标签，选择写入持久设置分区。没有显式 Host 偏好的浏览器会按完整标签、再按主子标签选择 `navigator` 请求的第一个已注册语言，无法匹配时回退到 English。已存储的外部 locale 会等待其定义注册，不会在不可用时生效。
+
+### 注册词典
+
+用已合并进 `LocaleNamespaceMap` 的命名空间调用 `ctx.locale.register(ns, { zh, en })`；编译器会对照该命名空间的类型化键并集检查每个键，并要求两个内置 locale 齐全。消费方通过 `ctx.locale.bind(ns)` 或框架注入的 `t` 席位翻译。UI 已挂载后再注册的词典无需重新挂载即可生效。
+
+### 注册语言包
+
+外部 client 插件把语言定义和每个已翻译命名空间注册为自身拥有的 effect；定义与字典可以按任意顺序注册：
+
+```js
+export const inject = ['locale']
+
+export function apply(ctx) {
+  ctx.effect(
+    () => ctx.locale.addLanguage({ id: 'ja', label: '日本語', fallback: 'en' }),
+    'my-locale: language',
+  )
+  ctx.effect(
+    () => ctx.locale.register('common', 'ja', {
+      cancel: 'キャンセル',
+      close: '閉じる',
+    }),
+    'my-locale: common dictionary',
+  )
+}
+```
+
+外部 id 必须是非空的 ASCII BCP 47 风格标签。它的 fallback 必须已经注册，且整条链必须终止于 `en`；未知目标、重复 id 与循环会在注册时失败。查找时先在请求命名空间内遍历生效语言的 fallback 链，再在 `common` 中遍历该链，最后显示键本身。卸载语言定义会将其从选择器移除，并让生效中的选择回落到可用的浏览器语言或默认语言。
+
+### Host 半侧做什么
+
+Host 通过 settings 服务为 loopback 页面持久化偏好。Client 会刻意拒绝非 loopback 页面使用该 settings scope，因此即使 Connection 认证所有 API 方法，它们的 locale 选择仍只存在于进程内。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释 locale 服务的构建方式；可观察行为已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+一个 `LocaleRuntime` 同时拥有偏好与词典注册表，并且自身就是 slot 系统的 `LocaleFace`：`getSnapshot`／`subscribe` 通过 `ctx.slots.installLocale` 支撑框架注入的 `t` 席位。不可变快照携带生效中的 locale、可选择的 locale 列表与单调 revision；词典注册与 locale 切换都会推进 revision，但只有切换会发出 `locale/change` 事件。产品编写的 Client UI 文本必须来自这些带类型的字典，或来自已经本地化的 primitive prop；`verify-client-ui-i18n` 强制执行该源码归属（见[决策](../../../.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.zh.md)）。
+
+### 偏好解析
+
+临时 locale 来自浏览器（`navigator.languages` 先按完整标签、再按主子标签匹配，以 English 作为回退），在允许使用的 Host-backed settings scope 送达其存储偏好之前生效。Host 读取在插件激活后运行，因此 settings scope 不可用或被拒绝都不会阻塞页面，结果会实时替换临时值。已存储的外部 locale 会等待其定义注册。`setLocale` 是唯一写入入口；即使 id 已与生效中的 locale 匹配也会持久化，因为生效中的值可能是临时的，必须能在共享同一 home 的其他浏览器上存活。
+
+### 词典查找
+
+带类型的对象形式要求两个内置 locale 都有完整字典；逐 locale 形式允许语言包独立注册每个命名空间。逐键查找会先在请求命名空间中沿生效语言声明的 fallback 链查找，再在 `common` 中重复该链，最后显示键本身。绑定的翻译函数按命名空间保持稳定身份，因此可以挂在 inject 表面上而不破坏 memoization。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/client/index.ts`](src/client/index.ts) | `LocaleRuntime`、词典注册表、文档语言同步、`locale/change` 事件 |
+| [`src/index.ts`](src/index.ts) | node 半侧：注册 `locale` 设置命名空间 |
+| [`src/locale-settings.ts`](src/locale-settings.ts) | `locale.preference` 的持久 schema |
+| [`src/locales/`](src/locales/) | 已发布的 `zh`／`en` 词典 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当 locale 约定不够用时阅读以下页面：它所实现的 slot 面孔、它所依托的设置界面，以及偏好背后的持久化决策。
+
+- [客户端 slot 系统](../ui-slots/README.zh.md)——本包实现的 slot 模型与 `LocaleFace` 席位。
+- [Host 支撑偏好决策](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.zh.md)——偏好为何持久化在 Host 设置中而非浏览器里。
+- [设置组地图](../../settings/README.zh.md)——存储该偏好的设置服务。
+- [客户端组地图](../README.zh.md)——本包所属的浏览器半侧。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。locale 服务属于浏览器侧 UI 插件层，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本地化在哪些地方不完整，或在注册时被冻结。它们是当前包约束，不是任务积压。
+
+- **注册表持有的文本只读取一次翻译**——在 slot 渲染路径之外于注册时捕获的文案（例如 command 注册表中的 `/model` 命令描述）在重新注册前保持注册时的语言；slot 渲染的文案随切换实时更新。
+- **语言包负责语言特有行为**——注册表提供选择、持久化、浏览器匹配、逐 key 回退和 `<html lang>`；它不增加复数规则或双向布局。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>