# 中英文支持 / English support

This document describes the language contract for the maintained version of `dsh-git-worktree`. It is not a backport commitment for 0.4.0.

## Selecting a language

The plugin follows DSH's language selection; it does not add a separate language switch. Select **English** in DSH to use English across the plugin UI, Console operations, tools, and `/worktree` commands. Select Chinese to retain Chinese messages.

The Client reads and subscribes to the public `@deepseek-ai/dsh-client-locale` runtime. The official-derived Workspace UI keeps its upstream locale implementation; only plugin-owned additions use the plugin catalog. No generated dependency bundle is edited.

## Host language and compatibility

There are two request paths:

| Surface | Language source | Missing information |
| --- | --- | --- |
| Client UI | DSH Client locale runtime | Chinese |
| Client → Worktree Console Remote | Active Client language, snapshotted into a trailing optional `locale` argument on each call | Host settings, then Chinese |
| Tools and `/worktree` commands | Public Host settings service: `get('locale').preference`, snapshotted for each invocation | Chinese |

The inspected DSH packages are version `0.1.2-rc.1`. The locale Host entry registers the `locale` settings namespace and its `preference` field. Tool and command invocation interfaces do not expose the browser's resolved locale. DSH's automatic browser-language resolution is a Client behavior and does not guarantee a saved Host preference.

**Limitation:** with automatic browser English and no saved DSH language preference, the UI and its Console requests can be English while tools and commands fall back to Chinese. Explicitly selecting English in DSH supplies the preference needed by all surfaces. The plugin does not guess from user text, machine locale, or the last browser request, and does not write a preference on the user's behalf.

Host language is scoped with `AsyncLocalStorage`, not a mutable process-wide language variable. Async operations retain their invocation's snapshot even if a concurrent request uses another language or the setting changes. An explicit Console request locale takes precedence over the Host setting. Old wire callers may omit locale; the new Client passes every positional slot required by the strict DSH Remote SDK. The additional field accepts only `zh`, `en`, or omission.

Tool/command registration descriptions, command hints, and generic tool presentation titles are shared, replayable metadata without an Agent context. They use static Chinese / English text rather than binding the shared registration to one user's preference. Dynamic execution results and command output use the invocation language.

Historical user-authored summaries and suggested commit messages remain stored content, not retranslated text. The existing cleanup recovery discriminants remain unchanged in storage; only a finite allowlist of known legacy system cleanup messages is localized at the public projection boundary. Unknown persisted or third-party errors pass through unchanged.

Error codes, result shapes, Git operations, review confirmation, cleanup decisions, and persisted schemas remain independent of translated text. Plugin-owned messages are translated at their source. Paths, branches, user-written titles and summaries, identifiers, and raw Git/filesystem/carrier error details are not translated.

## Catalogs and contributions

- `src/i18n/core.ts`: supported languages, normalization, typed keys and interpolation.
- `src/i18n/client-messages.ts`: plugin-owned Client messages.
- `src/i18n/host-messages.ts`: Host messages.
- `src/i18n/transport-messages.ts`: Client transport diagnostics.
- `src/client/i18n.tsx`: DSH Client locale bridge.
- `src/i18n/host.ts`: Host settings lookup and invocation scope.

Every entry has both `zh` and `en`. Preserve the meaning of existing Chinese copy and use matching named `{placeholder}` parameters in both languages. Insert dynamic values through parameters rather than constructing translation keys or translating user content. The typed translator checks keys and required parameters; tests verify language behavior and catalog agreement.

When adding a message, classify it first: plugin-owned UI (including accessibility text), official-derived UI, Host user message, model-facing instruction, or developer-only log. Keep the official UI's locale mechanism and source-version/hash validation intact. Comments, development logs, and machine-readable values are not UI translation targets.

## Source inventory

The initial extraction contains 380 Client entries, 364 Host entries, and 2 transport entries. Counts are informational, not stable identifiers.

| Category | Covered sources / handling |
| --- | --- |
| Plugin Client UI | Create/review tool rows, pre-session toggle, target status/actions, manager, review/preview/preflight/recovery panels, sidebar/task labels, tooltips, placeholders, accessibility labels, and operation feedback |
| Official-derived UI | Upstream Workspace locale remains in place; plugin augmentation is localized, source version and SHA-256 checks retained |
| Host user messages | Session checkout domain and Apply engine, Console control plane/projection/Diff/errors, Git/files/registry adapters, tools and `/worktree` output |
| Shared metadata | Bilingual tool/command registration and generic presentation titles; no request-local state stored in shared registrations |
| Non-translation data | User text, paths, branch/Session/Git IDs, error codes, persisted schemas, internal artifact labels and model protocol/context instruction text |
| Developer material | Code comments, maintenance scripts and raw process diagnostics are not end-user UI strings |

An AST scan after extraction finds six Chinese literal fragments outside the catalogs: five existing cleanup-reason discriminant fragments and one legacy transport codec-rejection marker. These are compatibility recognizers, not unlocalized UI output.

## Verification boundaries

Automated tests cover normalization, Chinese fallback, interpolation, Client language changes, Host async isolation, and strict Console transport compatibility, alongside existing Client and Host behavior. Type checking, build, upstream sidebar validation, and publish-integrity checks are separate gates. Mock and DOM-based component tests are not deployment or browser E2E evidence; actual Web/Docker validation, when performed, must be reported separately in the delivery report.