Communitygithub.com

English Document Translation

Used when the user requests translation of an English document into Chinese, generation of a `-中文版` suffixed Chinese version file, or requests 'one-to-one translation / full translation / localization' of an English Markdown file (especially SKILL.md, technical documentation). Trigger words: translation, localization, Chinese version, zh-CN, translate, one-to-one.

What is English Document Translation?

The English Document Translation skill is a specialized AI agent skill designed for one-to-one translation of English Markdown files into Chinese. Its primary purpose is to produce a semantically equivalent Chinese version of the original document, preserving all structural elements (headings, paragraphs, lists, tables, code blocks, charts) without any additions, deletions, mergers, splits, or paraphrasing. The skill operates by delegating the actual translation task to a general-purpose sub-agent, ensuring the parent agent does not read the source text, perform the translation, or consume context itself. It supports both individual files and directories, automatically skipping files that already have a `-中文版.md` counterpart to avoid redundant work. The skill enforces strict translation rules, including retaining untranslated code blocks, inline code, and URLs, while translating frontmatter descriptions and link text. After translation, the parent agent validates the output using a diff-like check against the rules and reports only the final status (success/failure/omission list) to the user, providing a clean and efficient workflow for technical document localization without polluting the main agent's context.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zhcmeng/shared-skills/tree/HEAD/plugin/skills/translate-docs

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does English Document Translation do?

Overview

Translate English Markdown documents one-to-one into Chinese, producing a same-name -中文版.md file (X.md → X-中文版.md), placed in the same directory as the original. The core principle is one-to-one: heading levels, paragraphs, lists, tables, code blocks, and charts are fully corresponding—no additions, deletions, merging/splitting paragraphs, or paraphrasing.

The entire translation process is completed within a sub-agent—this agent is only responsible for locating the target, dispatching the sub-agent, validating the result, and reporting to the user. It does not read the original text, translate it personally, or consume its own context.

Translation Rules (One-to-One Specification)

The following rules are what the sub-agent executes and what this agent uses to validate the output:

  1. Output: English X.md → same directory X-中文版.md.
  2. Frontmatter: name: retains the original English; description: is translated into Chinese; other fields (if any) translate their values.
  3. Explanatory Sentence: After the frontmatter, before the main body heading, insert a blockquote line: > 📝 This document is a Chinese translation of \`. The English original takes precedence; in case of any discrepancy, refer to the original.If the source version is known, write it asTranslated from v`.
  4. Code Blocks Not Translated: All fenced code blocks (, dot, mermaid, bash, etc.) are preserved as-is—not translated, indentation unchanged, lines not removed.
  5. Inline Code Preserved: Content inside backticks (skill names, file paths, commands, identifiers, URLs) is preserved in English as-is.
  6. First Occurrence of Terms: When a technical term first appears, use the format "Chinese (English)"; thereafter, only Chinese may be used.
  7. Tables: Translate headers and text cells; preserve cells that are pure code/paths/identifiers.
  8. Links: Preserve the URL, translate the link text.
  9. Footnotes: For footnote definitions ([^n]: url), preserve the URL, translate the explanatory text; footnote references ([^n]) in the body are preserved as-is.
  10. Line Breaks: Hard line breaks in the English source file are not preserved in Chinese (no line breaks within Chinese paragraphs); paragraph boundaries and empty lines are preserved.

Workflow

Whether it's a single document or a directory, always dispatch a sub-agent for translation—this agent does not translate itself.

  1. Locate Target: Get $ARGUMENTS—it is the file path, directory, or skill name (e.g., superpowers:brainstorming → locate its SKILL.md). If $ARGUMENTS is empty, report an error and exit immediately—do not guess.
  2. Determine Files to Translate:
    • Single document → that 1 file.
    • Directory → list all .md files under the directory, excluding those that already have a corresponding -中文版.md (skip existing; do not re-translate).
  3. Parallel Dispatch Sub-Agents: For each file to translate, dispatch one general-purpose sub-agent with model: "haiku" and a prompt using the template below filled with the target file path. Dispatch all sub-agents in one message (multiple Agent calls in parallel).
  4. Validate and Report: After sub-agents return, this agent runs a diff-style validation on each output (against the rules above) to confirm one-to-one completeness; only report the result (success/failure/list of omissions) to the user—do not report the translation process.

Sub-Agent Prompt Template

The general-purpose sub-agent does not inherit this skill's rules; the prompt must be self-contained:

You are an English document translation agent. Translate the specified English Markdown file one-to-one into Chinese, producing a same-name `-中文版.md` file (`X.md` → `X-中文版.md`) placed in the same directory as the original.

Rules:
- One-to-one: heading levels, paragraphs, lists, tables, code blocks, and charts fully correspond—no additions, deletions, merging/splitting paragraphs, or paraphrasing.
- Frontmatter: name retains English, description is translated into Chinese.
- After frontmatter, before the main body heading, insert a blockquote line: > 📝 This document is a Chinese translation of `<original file name>`. The English original takes precedence; in case of any discrepancy, refer to the original.
- Code blocks not translated: all fenced code blocks (including dot/mermaid) are preserved as-is.
- Inline code preserved in English (skill names, file paths, commands, URLs).
- First occurrence of terms uses the format "Chinese (English)".
- Tables: translate text, preserve code; links: preserve URL, translate text; footnotes: preserve URL, translate explanation.
- No hard line breaks within Chinese paragraphs.

Target file: <absolute path>
Translate only this one file, then write a one-line summary (file name + success/failure).

Constraints

  • One-to-one is a hard requirement: no additions/deletions, no merging/splitting paragraphs, no paraphrasing.
  • Code blocks must never be translated (including dot/mermaid diagrams—node labels within the diagram also remain in English).
  • English file names/paths/skill names/commands must be preserved as-is.
  • The translation process must always be completed within a sub-agent; this agent does not read the original text or translate it personally.
  • The translation target comes from $ARGUMENTS; when it is a skill name (e.g., superpowers:brainstorming), the agent itself locates the file path of that skill's SKILL.md—do not assume a local absolute path.
  • Directory mode, by default, skips files that already have a -中文版.md; only override and re-translate when the user explicitly requests it.

Related Skills