* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
description, kind
| description | kind |
|---|---|
| Localization for the web GUI: language preferences, browser-derived fallback, typed namespace dictionaries, and the framework translation seat, for users and plugin authors. | package-reference |
@deepseek-ai/dsh-client-locale
English | 中文
Summary
Use dsh-client-locale to switch the web GUI between the shipped English, Chinese, Japanese, Spanish, French, German, Russian, and Brazilian Portuguese (pt, including pt-PT browser requests) locales or languages added by client plugins. User selections take effect immediately; every authenticated browser persists them as locale.preference in $DSH_HOME/cordis.patch.yml through the Host settings service. New browsers use the first supported language requested by the browser until the Host read delivers a stored preference. 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
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
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
The Language row uses a smaller label gutter in narrow browser settings; Windows and macOS desktop windows retain the standard spacing.
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.
Native shells may provide __DSH_LOCALE__ with an asynchronous read() and an onChange(locale) callback. Initialization supplies the current Host preference and ordered OS languages before the Client mounts. Automatic selection stays provisional; only Settings selections write locale.preference. A fresh read on each page load prevents a stale preload preference after reload. Ordinary browsers keep navigator-based detection and their existing settings-scope policy.
Registering a dictionary
Call ctx.locale.register(ns, { zh, en, ja }) with a namespace merged into LocaleNamespaceMap; the compiler checks every key against the namespace's typed key union and requires both baseline locales (zh and en). Additional locale ids are optional, and their dictionaries are checked against the same namespace keys. 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. Preserve named placeholders, slash commands, and API field names verbatim in translations; pnpm run check:i18n checks first-party dictionaries and rejects zero-width spaces (U+200B) and byte-order marks (U+FEFF) in locale resources.
Resolving package text
Use ctx.locale.resolveText(text) for LocalizedText, such as installed plugin titles and descriptions. Literal strings are returned unchanged. Translation maps use lowercase language ids, require an en fallback, and follow the active language's declared fallback chain. They do not consult or register namespace dictionaries.
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:
export const inject = ['locale']
export function apply(ctx) {
ctx.effect(
() => ctx.locale.addLanguage({ id: 'it', label: 'Italiano', fallback: 'en' }),
'my-locale: language',
)
ctx.effect(
() => ctx.locale.register('common', 'it', {
cancel: 'Annulla',
close: 'Chiudi',
}),
'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
Every authenticated browser persists the preference through the Host settings service under the shared settings scope policy.
Understand the implementation
Implementation internals — click to expand
This section explains how the locale service is built; observable behavior is covered in 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).
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 Host settings scope delivers its stored preference. The Host read runs after plugin activation so an unavailable 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
Document language synchronization writes <html lang> only when its value changes; dictionary-only revisions leave the attribute untouched.
The typed object form requires complete dictionaries for both baseline 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 |
LocaleRuntime, dictionary registry, Language row registration, locale/change event |
src/index.ts |
Node half: registers the locale settings namespace |
src/locale-settings.ts |
The durable schema for locale.preference |
src/locales/ |
The shipped language dictionaries |
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 — the slot model and the
LocaleFaceseat this package implements. - historical Host-backed preferences decision — why the preference persists in Host settings instead of the browser.
- Settings group map — the settings service that stores the preference.
- Client group map — the browser half this package belongs to.
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
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
/modelcommand 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.
Dev Note
Working context for maintainers — click to expand
None.