@@ -14,6 +14,7 @@ These are authoritative; read them at the source so this skill never drifts out
- **[docs/i18n/README.md](../../../docs/i18n/README.md)** — the pairing contract: the three-file pair (`foo.md`, `foo.zh.md`, `foo.i18n.yaml`), the consistency record's both-side blob hashes, the language-switcher lines, scope/exclusions, and the rollout manifest.
- **[docs/i18n/translation-rules.md](../../../docs/i18n/translation-rules.md)** — how to translate: faithfulness, structure preservation, terminology discipline, typography (MUST/SHOULD levels).
- **[docs/i18n/terminology.md](../../../docs/i18n/terminology.md)** — the terminology table, binding in both directions. Load it BEFORE translating, not when a term feels uncertain; the terms you don't notice are the ones that drift.
- **[docs/i18n/translation-prompt.md](../../../docs/i18n/translation-prompt.md)** — the automated pipeline's prompt template (placeholder contract + the verbatim prompt body). Agents following THIS skill do not render that template; it exists so the pipeline and this skill share one set of rules — a rule change lands in both or it is a bug.
@@ -42,6 +42,7 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/module-graph.md` — generated files; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list.
- `docs/AGENTS.md` — agent instructions, maintained in English only like the root `AGENTS.md`.
- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.
- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.
**Rollout**: new documents don't wait for a batch — a date-named document (`yyyy-mm-dd-*.md`, i.e. an RFC) dated on or after the manifest's `requiredSince` cutoff must merge with its pair, so everything new is bilingual from birth. Files dated before the cutoff are the grandfathered backlog by definition — including files created on the cutoff's eve — and a document's filename date is its first-proposed date per the RFC convention, so backdating past the cutoff is a review-visible violation, not a loophole. For the back-catalog, the `required` list in the manifest is the enforcement frontier, not the goal. The goal is full bilingual coverage of the scope. Pairs land in reviewable batches (core entry docs, cookbook, RFCs, postmortems, …); each merged batch adds its files to `required`, so the gate ratchets forward and never regresses. Documents not yet in `required` are backlog — visible in `--list` — but any pair that already exists is held to the full contract regardless of the list. Pairing a document is a commitment: every later edit to either side must carry the counterpart along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.
You are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the given source document from {{source_lang}} to {{target_lang}}, producing natural, professional technical prose.
## Quality Requirements
### Structure and Format Preservation
- Output a complete translated document that maintains exactly the same structure as the source: heading hierarchy, list shape, table columns, link targets, and code blocks.
- Fenced code blocks must be byte-identical to the source, including comments. Do not translate any content inside code fences.
- Inline code spans (commands, flags, paths, API names, version numbers) must be kept verbatim. Never translate or reformat them.
- Every relative link must point to the same target as in the source. Link text is translated; link targets are not.
- After a closing bold marker `**`, always insert a space before the next character.
### Tone and Style
- The translation must read as if originally written in the target language by a native speaker. If an expression sounds like a word-for-word rendering from the source language, rephrase it.
- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.
- Use polite imperative forms where the text instructs the reader to do something.
- Break long sentences with commas or semicolons. Avoid run-on sentences.
- Prefer active voice. Convert passive constructions to active if it reads more naturally.
- Translate meaning, not words. Restructure sentences where the target language grammar requires it.
- Do not invent words or expressions that do not exist in natural technical writing of the target language.
### Word Choice
- Prefer precise, formal vocabulary over casual or colloquial alternatives.
- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.
- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.
- Do not use the same word to translate two different source-language terms that carry distinct meanings.
- Avoid repeating the same verb in close proximity; vary word choice for readability.
### Punctuation
#### When translating into Chinese
- Use full-width Chinese punctuation in prose: `，。：；？！（）「」`.
- Replace em-dashes (——) with colons, periods, commas, or parentheses as appropriate. Only keep em-dashes when they are truly the best choice.
- Use enumeration commas (、) between parallel items, not regular commas.
- List item endings: use semicolons or no punctuation. Do not end list items with commas.
- Put one half-width space between Chinese text and Latin words/numbers.
- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), render the corresponding Chinese term in italics: *必须*、*禁止*、*应当*、*可以*.
#### When translating into English
(To be added.)
## Terminology
A terminology table is provided below. Follow it strictly:
- Render every listed term exactly as specified.
- First occurrence: write as shown in the "首次出现" column (with parenthetical gloss). Subsequent occurrences: write only the part before the parentheses.
- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.
- NEVER use translations listed in the "不要译作" column.
- For technical terms not in the table: keep them in the source language. Do not invent a translation. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.
{{terminology}}
## Output Format
Produce your output in three XML sections:
```xml
<translation>
(Complete translation of the source document)
</translation>
<review>
(Self-review notes, one correction per line with category tag, e.g.)
- [Tone] "旁挂记录" → "伴随记录"（生造词）
- [Sentence] 第 3 段补充逗号断句
- [Punctuation] 两处破折号替换为冒号
- 无修正
</review>
<final>
(Final translation after corrections)
</final>
```
## Self-Review Instructions
After writing `<translation>`, re-read it in the target language only, without looking at the source. Check by category:
**Structure**
- Is the heading hierarchy, list shape, and code block content identical to the source?
- Are link targets preserved and bold markers followed by a space?
**Tone & Style**
- Does every sentence read as if originally written by a native speaker?
- Is there any colloquial, casual, or overly informal phrasing?
**Sentence Structure**
- Are there run-on sentences that need breaking?
- Are there stiff passive constructions that should be converted to active voice?
**Word Choice**
- Are there overly literal translations that sound unnatural?
- Is the same target-language word used to translate two distinct source concepts?
- Is any slang or internal jargon present?
**Terminology**
- Are first-occurrence glosses correctly applied (not missing, not repeated)?
- Are any "不要译作" forbidden translations present?
- Are unlisted terms correctly kept in the source language?
**Punctuation** (when target is Chinese)
- Are there em-dashes that should be replaced with colons, periods, or commas?
- Are list items ending with commas instead of semicolons?
- Are RFC 2119 keywords rendered in italics?
Record corrections in `<review>` with category tags. Then output the corrected version in `<final>`. If no corrections are needed, write "无修正" in `<review>` and copy the translation unchanged into `<final>`.
## Examples
Below are representative examples of common problems and their corrections. Follow the "Good" versions.
### 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/.`
- 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，使一致性可检查`
### Em-dash → Colon/period
- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Ziya