Proposal: make the UI locale an ordered preference list (ru -> en -> zh), so a partial translation never surfaces Chinese

[unera]

Locale preference should be an ordered list, not a single value

TL;DR. Today the UI locale is one value out of a fixed set (zh, en), and every missing string falls back to English and then to the raw dictionary key — which, for plugin-supplied text, is usually Chinese. Replace the single select with an ordered list of languages (the way browsers do Accept-Language). Lookup then walks that list per key. A Russian user gets ru → en → zh; a Ukrainian user uk → ru → en → zh; a Chinese user zh → en and sees no change at all. This unblocks every "add locale X" proposal below, because a partial translation becomes immediately usable instead of producing a Chinese/English patchwork.

What the fallback chain looks like today

Three different layers, three different answers — which is exactly why the proposals below keep re-litigating it:

Layer	Current last resort	Evidence
Core web client dictionaries	en, then the raw key	#3828 lists FALLBACK_LOCALE = 'en' and LOCALE_IDS = ['zh', 'en'] as hardcoded; #4558 describes the lookup chain as ns → common → en → key
Plugin-registered dictionaries	the raw key — and plugin string tables are authored with Chinese keys, so a missing entry renders 中文 in the middle of an English or Russian UI	dictionary registration is typed as "exactly every shipped locale" pair, #3828; the large packs count plugin dictionaries in the hundreds (522 plugin dictionaries, #10709)
Plugin manifests (title/description) and the Desktop shell	no localization channel at all, so English (or Chinese) regardless of UI language	#10708 (0 of 222 packages ship locale/ru.json), #9746, #10148, #9329

So the complaint "I turned on a second language and got Chinese characters" is not one bug but the intersection of these three:

• a community language pack translates the core namespaces, and whatever it misses comes out in English;
• the moment a plugin is involved, its dictionary has Chinese source keys, and any missing key shows Chinese text — [0.2.1-rc.3] "Application" and "Edit" stay English with a language pack while 中文 translates them #11023 ("Application" and "Edit" stay English with a language pack while 中文 translates them) is the same phenomenon from the other direction;
• plugin titles/descriptions and desktop shell copy have no channel at all, so they stay untranslated forever.

For someone who reads English but not Chinese, today's outcome is the worst of both: an interface that is partly their language, partly English, and partly Chinese.

Proposal

1. Preference is a list. locale.preference becomes an ordered array instead of a single id. The settings UI shows it as a reorderable list with add/remove (a language picker plus up/down or drag), exactly like a browser's language settings.
2. Lookup walks the list. For each key, try each language in order, then the existing final fallback (en, then the raw key). No key changes meaning; no dictionary format changes.
3. LOCALE_IDS stops being a closed set of choices. It becomes "dictionaries shipped by this build"; selectable values are whatever dictionaries are registered at runtime (this is the same direction as 消除硬编码的两语言假设，使发行语言集合成为单一可配置来源 #3828 and Feature request: let community plugins register new UI languages (i18n) #4558 — please treat those two as the prerequisite, not as competing proposals).
4. Backwards compatible. A stored single string is read as a one-element list. Browser detection already parses Accept-Language; keep the whole ordered list instead of narrowing it to the first match, which also fixes the "es-AR served as Arabic" ([Bug] report: DeepSeek UI served in Arabic when browser locale is es-AR / es_AR #11688) and "fr-be served as Belarusian" ([Bug] Locale `fr-be` (Belgian French) incorrectly served as Belarusian (`be`) UI #6133) class of bugs.
5. Nothing regresses for zh users. With zh first, behaviour is identical to today.

Why this is worth doing before more locales are merged: every proposal listed below ships one more dictionary and then faces the same complaint — a translated UI with untranslated islands, where the island language depends on which layer missed the key. An ordered list makes the island language a user choice (English before Chinese, or no Chinese at all), and it makes partial packs useful on the day they land instead of "complete enough" only at 100%.

The change surface is small: the settings schema (string → ordered array), one lookup loop, and one settings widget. It does not require touching 26 packages' locales.ts files (#3828 does that work separately).

Related discussions

Same proposal, different layer (prerequisites):

• 消除硬编码的两语言假设，使发行语言集合成为单一可配置来源 #3828 — remove the hardcoded two-language assumption, make the shipped set a single source of truth
• Feature request: let community plugins register new UI languages (i18n) #4558 — let community plugins register new UI languages at runtime
• DSH Plugin 缺少Manifest设计和i18n国际化支持 #777 — plugin manifest and i18n support
• Let language packs supply plugin display text (titles and descriptions) #9746 — let language packs supply plugin display text
• Russian (ru) plugin descriptors are missing — 0 of 222 packages ship locale/ru.json #10708 — no plugin descriptor ships locale/ru.json (0 of 222)
• Desktop shell copy (welcome window, app menu) is unreachable from a language pack #10148, Localize the Desktop shell copy (menu bar is English-only outside zh) #9329 — desktop shell copy is unreachable from a pack / English-only outside zh
• Add a public pluralization hook so language packs can render correct plurals #10147 — pluralization hook for language packs
• Let a deployment override a few strings of another locale namespace (e.g. conversation hero.headline) #7781 — override a few strings of another namespace

Built-in locale proposals (all would benefit from an ordered preference rather than another single choice):

• Russian: Proposal: Russian (ru) as a third GUI locale #3390, Proposal: add Russian (ru) locale to the Web UI (zh/en/ru) #4172, 将俄语 (ru) 纳入内置界面语言 (ship Russian as a built-in locale) #5071, Official optional Russian language pack (built-in locales are closed; a complete external pack exists) #11585
• Turkish: Idea: Official Turkish (tr) UI language for DeepSeek Harness #11015
• Korean: Proposal: ship Korean as a built-in locale (branch ready) #10687
• Dutch: feat(locale): ship Dutch (nl) as a first-party language (zh/en/nl) - branch ready #5431
• Portuguese (pt-BR): feat(i18n): Native Brazilian Portuguese (pt-BR) Localization, Language Onboarding & UI Ergonomics #6340
• Polish: Polish (pl) language pack for DSH Web — dsh-locale-pl #6365
• Spanish: DSH | dsh-locale-es | Spanish (es) language pack for the DSH Web UI #6560, [Plugin] dsh-locale-es-419: Latin American Spanish (Español Latinoamérica) for DeepSeek Harness Web & Desktop #10078
• Persian: Persian language pack: 240 translations and RTL support for DSH Web #7404

Language packs already shipped by the community:

• Russian: Russian language pack for the web UI (community bundle) #4433, Complete Russian (ru) locale for the web client — ready to upstream #4673, Russian language pack for the Web UI — deepseek-harness-locale-ru #5070, DSH | dsh-client-locale-ru | Russian (ru) language pack for the dsh web GUI #5582, DSH | dsh-locale-ru | Native Russian localization for the Web UI #7159, Russian localization plugin for the Harness UI — dsh-client-locale-ru (52 namespaces, 2626 strings) #8824, dsh-locale-ru — unofficial Russian localization for DSH #9073, Russian locale pack ready (57/57 namespaces, 2625/2629 strings) — request to consider bundling #9182, Russian (ru) language pack — 594 namespaces, 69 177 strings, 522 plugin dictionaries #10709, Russian language pack for the web GUI (65 namespaces, 2,915 strings) #10891, Russian language pack (2615 UI strings) — and a request: the desktop shell is English-only for every non-zh locale #8759
• Turkish: 🇹🇷 Turkish Language Pack for DeepSeek Harness — dsh-client-locale-tr #8746, Turkish Language Pack for DeepSeek Harness Desktop — Community Contribution #11484
• Portuguese: Brazilian Portuguese (pt-BR) locale plugin #5894, pt-BR language pack plugin — full UI translation (62 namespaces, 2,799 strings) #11009
• Spanish: [Plugin] dsh-locale-es-419: Latin American Spanish (Español Latinoamérica) for DeepSeek Harness Web & Desktop #10078
• Persian: Persian language pack: 240 translations and RTL support for DSH Web #7404

Observable symptoms this would fix or make user-controlled:

• 多语言切换还没有完全适配 #300 — language switching is not fully wired
• [0.2.1-rc.3] "Application" and "Edit" stay English with a language pack while 中文 translates them #11023 — a language pack leaves "Application"/"Edit" in English while 中文 translates them
• Russian language pack (2615 UI strings) — and a request: the desktop shell is English-only for every non-zh locale #8759, Localize the Desktop shell copy (menu bar is English-only outside zh) #9329, Desktop shell copy (welcome window, app menu) is unreachable from a language pack #10148 — the desktop shell stays English for every non-zh locale
• [Bug] report: DeepSeek UI served in Arabic when browser locale is es-AR / es_AR #11688, [Bug] Locale `fr-be` (Belgian French) incorrectly served as Belarusian (`be`) UI #6133 — locale detection maps a browser tag to the wrong language
• 复制内置 Preset 后描述固定为中文，无法随界面语言显示 #5615, 自定义 Agent Preset 的 name/description 无法随界面语言本地化 #3610 — preset names/descriptions cannot follow the UI language
• Предложение: локализуемые описания навыков (и других строк от хоста) #11533 — skill descriptions are not localizable

Notes

• I am not asking for new translations here. This is about the preference model, which is why it is worth deciding once, before another dozen packs are written against the current one.
• If a patch would be considered, the change is small and I would be glad to prepare it against packages/client/locale. Since patches are not accepted in this repository, I am raising it as a discussion; a downstream fork already needs exactly this because our own plugins ship en/ru dictionaries on top of Chinese source keys.
• Terminology used above is the one from 消除硬编码的两语言假设，使发行语言集合成为单一可配置来源 #3828/Feature request: let community plugins register new UI languages (i18n) #4558 so the three threads can be read together.

[mkfeyman]

Supporting this proposal from the Turkish language-pack side (#11015), with a few implementation observations from DSH 0.2.1-rc.3 that may help scope it.

Current state (from the shipped dsh-client-locale bundles):

• The durable preference is a single string: LocaleSettingsFields.preference = z.string().pattern(...), and LocaleRuntime.setLocale(id) writes exactly one id through the settings scope.
• Fallback chains already exist, but they are language-defined, not user-ordered: addLanguage({ id, label, fallback }) takes one fallback, must terminate at en, and translate() walks fallbackChain(active) in the requested namespace, then repeats it in common, then shows the key. resolveText() uses the same chain for manifest LocalizedText.
• Browser detection narrows to one match: detectBrowserLocale() iterates the ordered navigator.languages/shell list and returns the first exact/primary match; the rest of the order is discarded. That is the es-AR/fr-be-class bug.
• The snapshot is { active: string, locales, revision }, and locale/change only carries the single active id.

So the missing piece is exactly what you describe: a user-ordered array. Fallback machinery and per-locale dictionary registration (register(ns, locale, dict)) already support community languages without touching dictionaries' format.

Compatibility notes that would keep existing packs working:

• Read a stored string as a one-element array; always write an array.
• Keep snapshot.active = first available entry in the preference list (so html lang, __DSH_LOCALE__.onChange, and current snapshot consumers stay valid), and extend the snapshot/event with the list rather than replacing active.
• Decide the interaction with per-language fallback explicitly: either "list + en + key" (predictable) or "expand each list entry with its own fallback chain, then en" (more inclusive, but ordering surprises). The proposal text implies the first; documenting it would prevent future re-litigation.
• Keep resolveText's en terminal and the manifest contract unchanged.

Testing offer: our pack is 100% translated (64 namespaces / 2,910 keys), so it is a clean positive case; we can also produce a deliberately partial Turkish fixture (e.g. 60% keys) plus a plugin namespace registered only in en/zh to reproduce the "Chinese island" symptom and validate [tr, en, zh] versus the current single-chain behaviour. Happy to share the data and review the settings migration/widget.

[mkfeyman]

Update: I prepared a concrete draft for this proposal (not a submitted PR — upstream does not accept external PRs) plus a fixture. Both are public:

• Patch draft against dsh-v0.2.1-rc.3 (tag commit 1f81c047), 11 files under packages/client/locale (settings schema, bootstrap, runtime, settings row, locales, tests):
  https://github.com/mkfeyman/dsh-turkish-locale/blob/main/patches/0001-ordered-locale-preference.patch
• Design notes, verification status and apply instructions:
  https://github.com/mkfeyman/dsh-turkish-locale/blob/main/patches/README.md
• Fixture: a deterministic 59.4% Turkish subset (1728 / 2910 keys) plus expected-behavior.json samples for ["tr","en"], ["en","tr"], ["tr","zh"] and the legacy single selection:
  https://github.com/mkfeyman/dsh-turkish-locale/tree/main/fixtures

Key choices in the draft, matching the compatibility notes above:

• a stored string is read as a one-element list, and setLocale() keeps writing that legacy form; the new UI writes an array through setPreferences();
• snapshot.active stays the first registered entry, so <html lang>, locale/change, slots.installLocale and the native __DSH_LOCALE__ bridge keep their current contracts; the snapshot gains preference;
• lookup expands each preferred language's declared fallback chain, deduplicates, and ends at en (a one-element preference reproduces today's chain exactly);
• reorder-only updates bump the revision without emitting locale/change;
• detectBrowserLocales keeps the browser's whole ordered list instead of narrowing to one match.

Caveats: no pnpm checkout/toolchain was available in the environment where I produced this, so the updated tests and TypeScript are unverified — the hunks were applied programmatically against the tag sources only. Happy to iterate on the patch, or hand the fixture to whoever writes the real one.

[mkfeyman]

Validation update on the draft:

• I bundled the patched LocaleRuntime with its framework imports stubbed and ran it against the 59.4% fixture: 17/17 semantic checks pass, and all 10 changed/new TypeScript files pass a syntax/transpile check. Covered: ordered lookup ([tr,en] vs [en,tr]), legacy string migration, resolveText, a zh-only dictionary reached before the raw key, browser-order retention, persistence shapes (string vs array), and revision/locale/change behaviour on reorder.
  Report: https://github.com/mkfeyman/dsh-turkish-locale/blob/main/patches/validation-report.json
• I also installed the fixture as a real temporary tr-partial language pack in DSH 0.2.1-rc.3 and selected it in Settings → General → Language. The screenshot shows the exact symptom this proposal addresses — Turkish where the subset has a key, English islands everywhere else:
  https://github.com/mkfeyman/dsh-turkish-locale/blob/main/docs/partial-pack-demo.png
• The demo pack was removed afterwards; the fixture and screenshot remain public.

Still pending on my side: running the updated specs through the repository's own vitest/tsc (no checkout/toolchain in the environment where the draft was produced). The patch and report are linked from the repository README if anyone wants to pick it up.

[Ragnoryok1]

Thanks for pulling thirty-odd threads into one place — and for using the numbers from #10709.

Three measurements from a pack that ships against the current model (594 namespaces, 69 177 strings, @ragnoryok1/dsh-client-locale-ru), offered as data rather than opinion.

Per release. dsh-v0.2.2-alpha.2 added 745 strings across nine new namespaces — liveshare 224, forgePanel 199, stats 177, creationRecommendations 55, cuaPermissions 49, pluginRecommendations 25, actionCards 14, fileDrag and messageQuotes 1 each — plus 108 keys inside namespaces that already had translations. That is 853 strings in one release, against a tree that had no such change in the previous four.

Layer 2, as observed in the vendored dictionaries. Of the 522 plugin dictionaries in the pack, the majority are authored with Chinese keys: a string such as 下一步:改用其他方法重新检验 is a key, and a missing entry renders that key rather than falling back.

A correction to layer 3, from the tree rather than from the issue list. The desktop shell is not English-only for every non-zh locale. apps/desktop/src/locale.ts carries roughly 1.4k Russian strings, and apps/desktop/installer/locales/ru_RU.json is one of eight installer languages (de, en, es, fr, ja, pt, ru, zh). So that layer does have a localization channel for at least one non-zh language today.

Plugin manifests remain the one layer with no channel. Titles and one-liners live in package metadata outside every namespace. 0.2.2 rewrote 11 of the descriptions and lowercased 14 titles, and the coverage figure is 0 of 222 packages shipping locale/ru.json (#10708).

One more fact that bears on the shipped set: 0.2.2-alpha.2 requires @deepseek-ai/cordis@~4.0.6-alpha.1, so a locale package pinned to the previous range fails with ERESOLVE at install time, before any locale setting is read.

If it is useful, I can answer questions about any of the numbers above.

[mkfeyman]

Thanks — these are exactly the numbers the preference-model discussion needed, and they change two parts of my mental model.

Cross-checks from the Turkish pack side (64 namespaces / 2,910 strings on 0.2.1-rc.3):

• Release churn matches. Any community pack is pinned to a source version; the 853 strings added in 0.2.2-alpha.2 would be a full re-extraction for us. An ordered preference does not reduce that cost, but it makes the uncovered part usable and visible meanwhile instead of forcing a pack to be all-or-nothing.
• Layer 2 needs one nuance in the proposal text. An ordered list only avoids the Chinese island when some consulted dictionary owns the entry. I tested this with the draft patch and a zh-only namespace: with [tr, zh, en] the zh dictionary value is rendered, while today's single tr → en chain renders the raw key (which can be Chinese). For a key absent from every dictionary, or a plugin that registers only zh, ordering alone still shows the key. So ordered preference is necessary but not sufficient for layer 2 — it should pair with a registration rule (English fallback required) or a key-source policy. Did the 522 dictionaries in your pack come from per-locale registrations (zh-only) or typed zh/en pairs? That determines whether ordering alone resolves the symptom for your users.
• Layer 3 — thanks for the correction. I only had the rc.3 tree, where the shell copy stayed English under tr. Is the ~1.4k Russian shell text reachable from a language pack, or is it compiled into apps/desktop? If it is built-in, it is a separate channel from this proposal.
• Cordis ERESOLVE is a concrete blocker. Our Turkish locale bundle declares no cordis dependency at all (it imports none) and installs cleanly; 0.2.2-alpha.2's locale plugin itself peers workspace:~ (≈ ~4.0.6-alpha.1 once published), so a pack that imports cordis and pins ~4.0.5 fails before any locale setting is read. Packs that do not import cordis should omit the peer range entirely; packs that do need a deliberately broad range until the protocol stabilizes.
• Manifest gap: we see the same with tr — plugin titles/descriptions ship en/zh LocalizedText, so the Plugins page stays English under Turkish. Ordered preference cannot reach that layer; DSH Plugin 缺少Manifest设计和i18n国际化支持 #777/Let language packs supply plugin display text (titles and descriptions) #9746 remain the prerequisite there.

Our side: the patch draft targets rc.3 and has a validated runtime harness plus a 59.4 % Turkish fixture (links in the previous comments). It needs rebasing to 0.2.2-alpha.2, which added six built-in common dictionaries and changed the locale client/bootstrap/settings. If you are willing, your 594-namespace pack would be the best acceptance fixture for the rebased patch — I can prepare it and ping you.

[mkfeyman]

Rebase update, since your 0.2.2 numbers made the earlier draft stale:

• The patch is now rebased to dsh-v0.2.2-alpha.2 (commit f3803c96):
  https://github.com/mkfeyman/dsh-turkish-locale/blob/main/patches/0002-ordered-locale-preference-0.2.2.patch
  It carries the six new built-in dictionaries (ja/es/fr/de/ru/pt) through the ordered catalog and adds the Language-row copy for all eight shipped languages; the rc.3 variant stays available for the installed build.
• Harness re-run against the 0.2.2 locale source: 17/17 semantic checks, 10/10 files syntax-checked (ordered lookup, legacy string migration, resolveText, browser order, zh-only dictionary before raw key, persistence shapes, reorder events):
  https://github.com/mkfeyman/dsh-turkish-locale/blob/main/patches/validation-report-0.2.2.json
• Fixture caveat is recorded explicitly: it stays rc.3-based, so the 0.2.2 delta you measured (9 namespaces / 853 strings) falls through to English in fixture tests rather than pretending to be covered:
  https://github.com/mkfeyman/dsh-turkish-locale/blob/main/fixtures/version-coverage.json
• I also re-checked the 0.2.2 source: locale.preference is still a single string, and the six new dictionaries are registered through addLanguage + per-locale register in apply. So the ordered preference remains the missing piece; what changed is that users would now be able to order built-in languages alongside pack languages, not just pick between two.

The acceptance-test offer stands: running your 594-namespace pack against this rebased patch would show whether the ordering holds on real Chinese-keyed dictionaries. If you can share the locale data (or point me to its licence), I can also produce a fixture from your pack so the test does not depend on your local install.

One question that decides whether ordering alone fixes layer 2 for your users: are the 522 plugin dictionaries registered as per-locale (zh-only) entries, or as typed zh/en pairs? For typed pairs the ordered list resolves the Chinese island; for zh-only registrations a registration rule (mandatory en) or a key-source policy is still needed.