dsh-plugin-better-locale card
dsh-plugin-better-locale
中文 | English
A DSH web plugin that ships bundled third-language dictionaries (Japanese / Korean / French / German / ... — 19 languages) for DSH's own built-in UI namespaces, plus a compile-time drift engine that keeps the dictionaries tracking every DSH release. Languages are registered through DSH v0.1.2-alpha.1's native language-pack API (locale.addLanguage + locale.register(ns, locale, dict)), so they appear directly in DSH's own Language settings row; uncovered copy falls back along DSH's per-key fallback chain.
| |
|---|
| Package | @huanlin/dsh-plugin-better-locale |
| Repo | huanlinoto/dsh-plugin-better-locale |
| Requires | DSH dsh-v0.1.5-rc.1 or newer |
| License | AGPL-3.0 |
Invariants
This package publishes no ./invariant export. Per the DSH invariant rules effective since v0.1.2-rc.1, an invariant is only published when independent observations can diverge; here every language contribution (catalog entry + namespace dictionaries) is registered through ctx.effect, so fiber disposal / HMR removes exactly what was added (covered by tests/apply.spec.ts), and the plugin holds no mutable state of its own — the empty invariant companion was therefore removed.
Supported languages
| Language | id | Label |
|---|
| Japanese | ja | 日本語 |
| Korean | ko | 한국어 |
| French | fr | Français |
| German | de | Deutsch |
| Portuguese | pt | Português |
| Arabic | ar | العربية |
| Hindi | hi | हिन्दी |
| Indonesian | id | Bahasa Indonesia |
| Turkish | tr | Türkçe |
| Vietnamese | vi | Tiếng Việt |
| Thai | th | ไทย |
| Russian | ru | Русский |
| Italian | it | Italiano |
| Dutch | nl | Nederlands |
| Swedish | sv | Svenska |
| Polish | pl | Polski |
| Traditional Chinese (HK) | zh-HK | 繁體中文（香港） |
| Traditional Chinese (TW) | zh-TW | 繁體中文（台灣） |
| Traditional Chinese (MO) | zh-MO | 繁體中文（澳門） |
Install
# npm registry
dsh plugin --profile web add "@huanlin/dsh-plugin-better-locale"
# or github ref
dsh plugin --profile web add "github:huanlinoto/dsh-plugin-better-locale"
After install, restart dsh web and hard-refresh the browser (Ctrl+Shift+R).
Usage
Open Settings → General → Language: every bundled language is listed alongside DSH's built-in 中文 / English. Pick one and the whole UI switches immediately — the selection persists in DSH's durable locale.preference setting (survives browsers and devices sharing the same DSH home), and <html lang> follows.
Uncovered namespaces / keys fall back through DSH's per-key fallback chain (selected language → declared fallback → en; the Traditional Chinese variants declare zh, so their gaps show Simplified Chinese rather than English). Coverage table: TRANSLATION.md (regenerate with pnpm run gen:translations).
Coverage & scope
- DSH itself only: the dictionaries translate DSH's built-in namespaces (
common / settings.locale / command / ... — every namespace merged into DSH's LocaleNamespaceMap, 39 namespaces / 1233 keys × 19 languages at current coverage). The scope is machine-locked at compile time: pnpm typecheck fails if the dictionaries miss an upstream namespace/key (drift) or carry one upstream does not own (trespass).
- The drift engine: after upgrading the DSH checkout, run
pnpm typecheck — red means upstream added or renamed copy; translate until green. scripts/check-upstream-merges.mjs (part of the same command) fails when a new upstream merge module is not yet imported by the assertion file, so new namespaces can never slip in unnoticed.
- Third-party plugins are out of scope by design: a plugin's own namespaces belong to that plugin. Unmigrated plugins coexist with zero errors (their copy falls back to English); migration is a few lines of native API — see the Developer Guide.
Migration from 0.1.x (v0.1.2-alpha.1 adaptation)
0.1.x injected third languages by monkey-patching LocaleRuntime.prototype.lookup and borrowing DSH's English slot (selection in a custom settings row, persisted to localStorage, English-only activation). DSH v0.1.2-alpha.1 made all of that native, and the plugin dropped the hack:
- the custom "Language override" settings row is gone — use DSH's native Language row;
- persistence moved from browser localStorage to DSH's
locale.preference setting;
- the override now works with any DSH active locale (no "switch to English first" step);
- the
ctx.betterLocale service was removed — register plugin dictionaries through ctx.locale directly.
Known limitations
- Coverage is a process, not a promise: the dictionaries track the upstream merge table exactly at each release of this plugin (currently 39 namespaces / 1233 keys × 19 languages); between a DSH upgrade and a better-locale update, new upstream copy falls back along the fallback chain. Run
pnpm typecheck in the repo to see any gap.
- Traditional Chinese variants fall back to Simplified Chinese:
zh-HK / zh-TW / zh-MO declare fallback: 'zh' — missing keys show the Simplified dictionary (chain zh-TW → zh → en), not English.
- Third-party plugin copy is not translated here: those namespaces belong to their plugins (see the Developer Guide); expect English for unmigrated plugins while a third language is active.
- Web only: the client bundle targets the browser; it does not run in Node.
License
AGPL-3.0
