Add Traditional Chinese (zh-Hant) UI locale

[MumuTW]

Summary

Orca ships five UI locales (en, zh, ko, ja, es), where zh is Simplified Chinese. There is no Traditional Chinese catalog, so zh-TW / zh-HK users get the English UI.

The codebase already accounts for Traditional Chinese

This isn't an oversight — src/shared/ui-locale.ts:22-29 has an explicit carve-out:

if (primary === 'zh') {
  if (tag.startsWith('zh-tw') || tag.startsWith('zh-hk') || tag.startsWith('zh-hant')) {
    return DEFAULT_UI_LOCALE   // -> 'en'
  }
  return 'zh'
}

With Language: System on a zh-TW machine, Orca deliberately resolves to English rather than serving Simplified. That is the right call given the available catalogs — Simplified is not an acceptable substitute for a Traditional reader, and silently serving it would be worse than English.

The naming reinforces that this space was left open: the picker label is already scoped as 中文（简体） rather than a bare 中文 (src/renderer/src/i18n/supported-languages.ts:38, src/renderer/src/i18n/locales/zh.json), so adding 中文（繁體） alongside it needs no renaming of the existing option.

So the groundwork is done. What's missing is the catalog.

Why it's worth adding

Traditional Chinese isn't a spelling variant of Simplified — beyond the script itself, a lot of the technical vocabulary diverges in ways that make a Simplified catalog read as clearly foreign to a zh-TW/zh-HK user (e.g. 软件/軟體, 程序/程式, 界面/介面, 服务器/伺服器, 缓存/快取). Machine-converting zh.json character-by-character would produce Traditional characters with Mainland terminology, which is usually judged worse than leaving it in English.

Taiwan and Hong Kong are a meaningful share of the Chinese-speaking developer population, and right now they're the only group among Orca's covered languages that gets routed to English by design.

Suggested implementation

Adding a locale looks contained. Touch points:

• src/renderer/src/i18n/locales/zh-TW.json — new catalog
• src/shared/ui-locale.ts — add to SUPPORTED_UI_LOCALES; change the zh-tw / zh-hk / zh-hant branch to return the new locale instead of DEFAULT_UI_LOCALE
• src/shared/ui-language.ts — new UI_LANGUAGE_* constant, add to the union and UI_LANGUAGE_VALUES
• src/renderer/src/i18n/supported-languages.ts — add to UI_LANGUAGE_CHOICES and UI_LANGUAGE_CHOICE_FALLBACKS (中文（繁體）)
• src/renderer/src/i18n/i18n.ts — add to NON_DEFAULT_LOCALE_LOADERS
• src/main/i18n/main-i18n.ts:24-27 — the main process lazy-loads the same renderer catalogs, so its loader map needs the entry too
• src/renderer/src/components/settings/appearance-search.ts:34-52 — add 中文（繁體） to the search keywords

The lazy-loading backend means a sixth catalog costs nothing at cold start.

I'm a zh-TW speaker and happy to help review or proofread a Traditional catalog if that's useful — the mechanical conversion is the easy part, the terminology pass is where it needs a native reader.

Environment

• Orca 1.4.155 (stable), macOS (Darwin 25.5.0), arm64
• System locale zh-TW, UI resolves to English

[AmethystLiang]

Would love to add this! We're refactoring how we do i18n to make it maintainable.

Once that's done. Will comment here and we can add the new zh-TW translation

[MumuTW]

Thanks — that makes sense, and I'd rather land this after the refactor than fight it.

Since the format is still open, one input worth having on the table: zh-TW does not need to be a sixth hand-maintained catalog. It can be derived from zh.

I built this to check whether the idea survives contact with the real catalog, and it does — 11,159 keys, generated end to end:

pnpm derive:zh-tw-catalog     # regenerate zh-TW.json from zh.json
pnpm verify:zh-tw-catalog     # fails if the committed file has drifted

Why derivation rather than translation

Traditional Chinese is not a spelling variant of Simplified, but the delta from zh is far smaller and far more mechanical than the delta from en. OpenCC s2twp covers script plus the obvious Taiwan vocabulary (软件→軟體, 程序→程式, 界面→介面, 服务器→伺服器, 缓存→快取). What it does not get right is a bounded, enumerable list — and that list is the actual review surface:

• 面板 must be masked, not post-corrected. s2twp reads 面 as the noodle sense inside certain compounds (快速面板 → 快速麵板), so the term is protected before conversion.
• 通过 is two different words. Prepositional "by means of" → 透過; resultative "passed" → 通過 (unchanged). The distinction is syntactic, so no pattern over the Chinese can decide it — 检查已通过 and 可通过 SSH 登录 share a prefix. These are keyed against their en.json source, which is only possible because the derivation sees English too.
• 配置 → 設定, except when it names a file format. "MCP config" / "SSH config" / "Ghostty config" keep 配置.
• A term table for what s2twp leaves as Mainland usage: 訪問→存取, 計算機→電腦 (計算機 is a calculator in Taiwan), 單擊→按一下, 終端→終端機, 守護程序→常駐程式.

Every one of those is a line in a table with a comment, reviewable by a native reader without reading 13k lines of JSON.

The part that actually matters for maintainability

I rebased this across 76 upstream commits today. zh.json had moved in 8 of them. The check said:

zh-TW.json is out of sync with zh.json.
Run `node config/scripts/derive-zh-tw-catalog.mjs` to regenerate it.

One command and it was current again. A hand-maintained sixth catalog would have silently rotted instead — and rotted worst on exactly the strings that changed most recently.

On the rebased branch pnpm typecheck is clean and pnpm test passes at 3422 files / 36495 tests, with the only failures being the 2 in src/relay/agent-exec-handler.test.ts that fail identically on a clean main. Locale parity holds at 11,159 keys across all six catalogs.

That regeneration also surfaced two real conversion bugs, which I fixed the right way — by adding a rule, not by patching the JSON:

• 进行复制 → 進行復制: s2twp read 复 as "again". 復制 is never the copy sense. (2 occurrences against 229 correct 複製.)
• 局域网 → 區域網: Taiwan says 區域網路.

The ask

Not "please merge this now." It's that the new format should have a concept for a locale whose source of truth is another locale plus a rule set.

If the bilingual source lands without it, zh-TW's only path back in is as a full sixth catalog with its own review state for all 11k keys — which is the thing this refactor is trying to get away from. Getting it in while the format is still undecided costs a lot less than retrofitting it later.

Concretely, what a derived locale needs from the format:

1. A way to declare zh-TW.source = zh plus a rule-set reference, instead of 11k independent entries.
2. Review state that attaches to rules, not to every derived string — a native reviewer signs off on "計算機→電腦", not on the 40 strings containing it.
3. A build step that regenerates derived locales and fails on drift, so a zh edit can't silently stale zh-TW.

Happy to reshape the implementation onto whatever PR B settles on — the rule set is the durable part and it ports. And I'm a zh-TW speaker, so I can carry the terminology review either way.

One related thing I noticed while doing this, since it's the same underlying problem: regenerating zh-TW faithfully reproduced zh's untranslated strings — Details, Needs attention, the whole Agent Dashboard block, the Codex config-sync messages. That is exactly the failure #8512 describes, visible from a second angle: zh-TW can never owe less than zh owes. I've opened #10672 for one instance of it (the 19 browser.loadFailure.* keys, English in all four target catalogs since the certificate-error work).

[nwparker]

Thanks for raising this, and sorry for the slow response.

We are not adding new UI locales at the moment. Orca ships en/es/ja/ko/zh, and each locale carries ongoing cost past the initial catalog — every new English string needs re-translating, the build-time repair policy needs per-locale glossary and override rules, and mistranslations land in surfaces nobody on the team can read. We are working through a backlog of correctness bugs in the five we already ship, and taking on a sixth before that is under control would not serve the people who ended up using it.

Closing as not-planned so the tracker reflects where we actually are, rather than leaving it open indefinitely. This is a capacity call and not a permanent no — if it changes we will come back to this thread first.

[nwparker]

I'm sorry — I closed this as "not planned", and that was the wrong call. Reopening it.

We aren't adding new built-in locales right now, and that part was accurate. But this is a reasonable request from someone who wants to use Orca in their own language, and closing it made it look like the answer was no. It isn't.

The direction we're working toward is plugin language packs, so a locale can be maintained by the people who actually read it instead of becoming in-tree translation debt that ships mistranslations to users in surfaces nobody on the team can check.

Most of that mechanism is already in the repo today:

• a plugin manifest declares contributes.languagePacks: [{ locale, path }]
• the pack is a plain catalog JSON with the same key shape as src/renderer/src/i18n/locales/en.json
• packs are content-integrity verified and approval-gated at install, then registered into i18next at runtime
• they appear in Settings → Appearance → Language next to the built-in locales
• Intl formatting — dates, relative times, plural and number rules — resolves through the locale tag the pack declares

What's missing is the authoring side: no guide, no scaffolding to generate a starter catalog from en.json, no re-sync story when English strings change, and the glossary/repair tooling used for the built-in locales isn't exposed to pack authors. That's the work in front of us, and I'm not going to invent a date for it.

Leaving this open to track the request. Thanks for raising it, and sorry for the way I handled it.

[a-lang]

Hello — I built a human-reviewed Traditional Chinese (zh-TW) language
pack for Orca: https://github.com/a-lang/orca-traditional-chinese

What's inside:

• Full coverage of the pack-translatable catalog: 12,529 / 12,531
  keys (99.98%), excluding the 180 plugin-protected security-copy keys under
  auto.components.settings.plugin* that plugin packs cannot override by
  design, plus 2 inline CSS animation styles that exceed the artifact string
  limit and are not translatable prose (both fall back to English
  automatically).
• Human-translated and reviewed as Taiwan Traditional Chinese — not an
  OpenCC conversion of the Simplified catalog. Terminology follows a zh-TW
  glossary (儲存庫 / 終端 / 外掛程式 / 預設 …) and every string was
  re-verified against the English source; placeholders, brand names, and
  code literals are preserved verbatim.
• Installation: add the repository as a marketplace source in
  Settings → Plugins (Git URL https://github.com/a-lang/orca-traditional-chinese.git,
  ref main), install the Traditional Chinese Language Pack listing
  (a-lang.traditional-chinese), then pick the Traditional Chinese (zh-TW)
  entry in Settings → Appearance → Language. Keys not yet translated fall
  back to English automatically.
• The language picker currently shows zh-TW — a-lang.traditional-chinese;
  a native display name (中文（繁體）) for plugin packs would be great to have
  — feat(plugins): allow language packs to declare a native display name #13140 already tracks exactly that.

This follows the plugin language-pack route you pointed contributors to in
#10592. The catalog is also a natural seed for a future built-in zh-TW
locale if Orca reopens built-in locales — happy to coordinate with the
existing PRs (#10604, #14223) when the time comes.

Thanks for Orca; happy to iterate on review feedback.

[mark22013333]

I published another zh-TW language pack that follows the plugin route suggested above: https://github.com/mark22013333/orca-zh-tw

How it differs from the existing community pack: developer terms stay in English (agent, worktree, session, repo, commit, branch, diff, PR, rebase, checkout, …), which is how many Taiwanese developers read tooling UIs. Everything else uses Taiwan Traditional Chinese (終端機, 工作區, 設定, 檔案 …).

• Built against 1.4.214 en.json. It covers every key a pack is allowed to carry; the 180 protected auto.components.settings.plugin* keys and the 2 oversize CSS values stay English by design.
• How it was made: I converted the Simplified catalog with OpenCC s2twp as a base, restored the English terms (checking the English source first, so 代理 becomes "agent" only when the source says agent, not proxy), and then had AI reviewers check every string against the English source in batches. After that, a separate reviewer sampled the result, and I fixed what it found by checking the settings pages on screen.
• Validated with Orca's own parsePluginLanguagePackArtifact, parsePluginManifest and the marketplace schema. I also installed it end to end through Settings → Plugins → Add marketplace source (git URL, ref main) on a clean profile.

Install, either way:

• Settings → Plugins → Install plugin → Git URL: https://github.com/mark22013333/orca-zh-tw.git#v1.0.0 (pinned to the v1.0.0 release)
• Marketplace source: add https://github.com/mark22013333/orca-zh-tw.git with ref main, then install 繁體中文（台灣）

Then choose zh-TW — mark22013333.zh-tw under Appearance → Language.

Feedback on wording is welcome in that repo.