dsh-plugin-readme-zh

dsh plugin --profile web add dsh-plugin-readme-zh

Chinese Plugin Docs

English | 中文（由本插件自动翻译）

Translate the documentation of any installed plugin on the Plugins page into Simplified Chinese — both the long detail document and the list-row title/description one-liners — keep every result in a persistent cache, and re-translate only the parts a plugin update actually changes.

Summary

DSH plugins ship their user documentation as an English README (or a meta.detail document), and their list rows show the bundle's meta.title / meta.description with a literal English fallback. This bundle does two things:

1. Adds a 中文说明 control to the head of every installed plugin's detail page. The control opens a dialog with the translated long document, live progress, and cache statistics.

2. Makes the Plugins list itself render Chinese: it translates each bundle's short one-line meta and writes the result into the bundle's own locale files, so the host's normal locale resolution displays it natively — no client-side DOM patching.

All translations are produced by the model selected as the agent default (or an explicitly configured provider and model), and are stored under $DSH_HOME/plugin-data/dsh-plugin-readme-zh/ (Markdown segments plus short strings).

Use this plugin

1. Install the bundle. On every start it automatically translates the list one-liners of all installed plugins (in the background; already-cached strings cost nothing).

2. Open Settings → Plugins: installed rows now show Chinese one-line descriptions next to their package names.

3. Open any installed plugin's detail page; its header shows a 中文说明 button. Select it.

4. On first use the document is translated and the dialog shows a progress bar. Later visits read the cache and open instantly.

5. 重新翻译 forces a fresh translation. 翻译全部已安装插件 translates every installed plugin's long document in the background (and refreshes the list one-liners too); progress appears beside the button.

6. 复制中文 copies the translated Markdown.

The detail button is hidden when the plugin has no readable document, its files are unavailable, or its document is already Chinese.

How the list rows become Chinese

Opt-in via metaSidecars: true (off by default). When enabled, for each profile-installed bundle the translations are kept in its own package directory:

• locale/zh.json gains meta.title / meta.description (merged into any existing file; author-provided Chinese is never touched);
• when the package ships no locale/ directory at all, a locale/en.json mirroring the original English text is added too, because the loader reads no locale dictionaries without the English seed file;
• when the package declares an exports map, the standard DSH entry "./locale/.json": "./locale/.json" is appended so the module resolver can see the locale files (packages without an exports map need nothing).

These are small, additive, idempotent writes into the installed package's own directory; a pnpm install that re-extracts the package simply resets it, and the next start re-applies it from the string cache.

Understand the cache

Every document is split into ordered Markdown segments:

• fenced code blocks, HTML comment blocks, and standalone HTML tag lines are kept verbatim and never sent to the model;
• the text is cut at every Markdown heading (# … ######) first, so each section becomes its own chunk group: inserting or reordering a section changes only that section's hashes, not the rest of the document;
• within a section, prose is packed into chunks of at most 3000 characters at line boundaries;
• each chunk is keyed by the SHA-256 of its exact source text.

The cache file records the document hash, the chunk hashes, and their translations. When a plugin is updated:

• unchanged chunks keep their hash and are reused;
• only chunks whose source text changed are sent to the model;
• a version bump with an identical document costs no model calls at all.

A translation interrupted by a restart keeps its finished chunks, so the next run continues instead of starting over.

Configuration

Set these fields on the bundle row in the profile patch when the defaults do not fit:

Field · Default · Meaning

engine · auto · auto prefers the model service and falls back to the translator service; llm requires a model; translator uses only ctx.translator.

provider · agent default · Model provider route for translation.

model · agent default · Model id for translation.

reasoningEffort · off when supported · Reasoning effort for the translation call.

maxTokens · 8192 · Output-token cap per chunk.

translatorProvider · bing · Provider used when the translator fallback runs.

metaSidecars · false · Opt-in: also write the translated list-row one-liners into the installed packages' own locale/ files (plus one standard exports entry where needed) so the Plugins list renders Chinese natively. Off by default — a public install keeps its hands off other packages. Set true to enable the list-row feature.

The translation prompt requires the model to preserve Markdown syntax, code, URLs, file paths, package names, and identifiers, and to return only the translated fragment.

Limitations

• The long detail document and the list-row one-line meta are translated; deep configuration field labels, row titles, and in-document strings stay in their original language.
• The first translation of a long document needs one model call per chunk; a 30 KB README usually takes a handful of calls.
• Transient model failures are retried on the model itself (three attempts with backoff). Only a structural failure (no provider, missing credentials, exceeded context window) uses the anonymous translator fallback, and that decision is made per chunk.
• A chunk that is almost entirely code or symbols and still comes back without Chinese text is kept verbatim and counted under keptSource; it stays that wa

…(truncated)