deepseek-harness/docs/i18n/translation-prompt.md

# Translation prompt (pipeline asset)

本文件是自动翻译流水线使用的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时会把 [translation-rules.md](translation-rules.md) 全文填入 `{{translation_rules}}`，把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`，以免模板另存一份规则而日后失去同步。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题；术语表、忠实性和结构规则优先于样例，样例只在这些硬性约束内决定文体。修改本文件会改变翻译行为，需正常经过 PR 评审。

## 占位符契约

流水线渲染模板时替换以下占位符，除此之外不改写系统消息：

| 占位符 | 填入内容 | 来源 |
|---|---|---|
| `{{source_lang}}` | 源语言名（`English` / `Chinese`） | 由改动侧文件推断：`.zh.md` 被改则为 `Chinese` |
| `{{target_lang}}` | 目标语言名（`Chinese` / `English`） | 与 `{{source_lang}}` 相对 |
| `{{translation_rules}}` | [translation-rules.md](translation-rules.md) 全文（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
| `{{terminology}}` | [terminology.md](terminology.md) 的完整表格（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
| `{{source_filename}}` | 源文档的 basename（如 `foo.md` 或 `foo.zh.md`） | 由流水线从待译文件路径取得 |
| `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 英文源追加 `.zh`；中文源使用自身 basename |

例如，英译中时若源文件是 `foo.md`，`{{source_filename}}` 填 `foo.md`，`{{source_filename_zh}}` 填 `foo.zh.md`；中译英时若源文件是 `foo.zh.md`，两个占位符都填 `foo.zh.md`。

流水线只识别上表中的占位符，并且一次翻译整篇文档。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议。输出必须是一个以 `<dsh-translation-response>` 为根元素的 XML 文档；三个子元素中的 Markdown 内容都放在 CDATA 中。内容出现 `]]>` 时写成 `]]]]><![CDATA[>`，XML 解析后仍会还原为原文。

## Few-shot 金标

流水线使用**整篇文档**的中英对照作为 few-shot，不是模板内嵌的句子级正误例。以下 5 组配对文档均经过人工评审，并以仓库当前版本为准，随仓库一同更新：

- `README.md` ↔ `README.zh.md`
- `docs/development.md` ↔ `docs/development.zh.md`
- `docs/i18n/README.md` ↔ `docs/i18n/README.zh.md`
- `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md`
- `docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md`

注入时按当前翻译方向选择每组的源侧与目标侧：user 消息包含源文档全文，assistant 消息采用模板正文规定的 XML 协议；`translation` 与 `final` 都放入目标文档全文，`review` 填 `- [None] No corrections.`。CDATA 遵循上文的 `]]>` 拆分规则。上下文不足时，按上列顺序从后往前删减示例组数。这 5 组也是评审校准锚点；改动任何一组都会改变流水线行为。

## 模板正文

````text
# Translation Prompt

You are a senior technical translator specializing in LLM and agent development documentation. Translate the complete source document from {{source_lang}} to {{target_lang}} as natural, professional technical prose.

## Binding Translation Rules

The canonical repository rules below are injected verbatim. Apply every direction-appropriate requirement. In those rules, the authored document is the source for this request and the generated document is its counterpart.

{{translation_rules}}

## Request-Specific Structure

- The source basename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1.
- Emit the switcher for a new pair and flip an existing switcher; never copy it unchanged.

## Binding Terminology

Apply the current table below exactly as required by the injected translation rules.

{{terminology}}

## Output Format

Return exactly one well-formed XML document with this root and these three child elements. Do not wrap it in a Markdown code fence. Put all Markdown and review text inside CDATA. If any content contains the CDATA terminator, split it as `]]]]><![CDATA[>` so XML parsing reconstructs the original `]]>` sequence.

```xml
<dsh-translation-response version="1">
<translation><![CDATA[
(Complete first-pass translation)
]]></translation>
<review><![CDATA[
- [Tone] Replaced a literal rendering with the established target-language phrasing.
- [Terminology] Applied the binding sidecar record term.
]]></review>
<final><![CDATA[
(Complete corrected translation)
]]></final>
</dsh-translation-response>
```

## Self-Review Instructions

After writing `<translation>`, re-read it in the target language without looking at the source. Then apply the injected translation rules as a clause-by-clause comparison against the source and record actual corrections in English inside `<review>`. Apply every recorded correction in `<final>`. If no correction is needed, write only `- [None] No corrections.` in `<review>` and copy `<translation>` unchanged into `<final>`.

## Examples

Follow the Good versions; these sentence-level examples illustrate error categories, not the assistant-message wire format.

### Colloquial verb → Professional verb
- Source: `The repo pins pnpm@11.7.0 in package.json`
- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`
- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`

### Run-on sentence → Natural phrasing with pause
- Source: `Read docs/architecture.md before changing anything under packages/.`
- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`
- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`

### Stiff passive voice → Active and natural
- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`
- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`
- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`

### Invented word → Natural expression
- Source: `A sidecar record of both blob hashes makes consistency checkable`
- Bad: `旁挂记录两侧 blob hash，使一致性可检查`
- Good: `伴随记录保存两侧 blob hash，使一致性可检查`

### Overly literal → Meaningful rendering
- Source: `awkward phrasing is easier to hear without the source anchoring you`
- Bad: `没有源文锚着，别扭的表述更容易被听出来`
- Good: `不对照原文时，更容易察觉别扭的表达`

### Terminology — keep the binding English form
- Source: `typed service seams, and explicit extension points`
- Bad: `类型化的服务 seam（扩展点）与显式扩展点`
- Good: `类型化的服务 seam 与显式扩展点`

### Slang → Professional phrasing
- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`
- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`
- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`

### Chinese → English — idiomatic subject and predicate
- Source: `门禁绿并不代表译文内容正确。`
- Bad: `The gate green does not represent that the translation content is correct.`
- Good: `A green gate does not mean the translation is correct.`

### Code block comments — never translate
- Source code block contains: `# readline coding agent (needs DEEPSEEK_API_KEY)`
- Bad: `# readline 编码 agent（需要 DEEPSEEK_API_KEY）`
- Good: `# readline coding agent (needs DEEPSEEK_API_KEY)` (byte-identical)

### Language switcher — English to Chinese
- Source: `English | [中文](README.zh.md)`
- Bad: `English | [中文](README.zh.md)`
- Good: `[English](README.md) | 中文`

### Language switcher — Chinese to English
- Source: `[English](README.md) | 中文`
- Bad: `[English](README.md) | 中文`
- Good: `English | [中文](README.zh.md)`

---

Now translate the following document:
````