translate-language

Translate docs into one language

This repo is a GitBook project. Translations are branch-based: each language lives in its own git branch (not a /locale/ folder). The English branch en is the single source of truth; every other branch is a translation that drifts behind it.

This skill lives on the en branch only. Translation branches do not carry the skill — they carry their own glossaries.md (see Glossaries below).

Your job: bring a target language branch closer to en by translating the requested scope, and open a PR into that language branch.

Inputs

• Target language (required) — e.g. chinese. Maps to a branch name (see below).
• Scope (optional) — a section (e.g. "Trading Tools"), a list of pages, or "all missing pages". If unspecified, ask the user whether to do one section (pilot) or the full gap. Default to a single named section for a first run.

Supported language branches

git ls-remote --heads origin is the authority. Known translation branches:

en is the source. en_bkup is a backup — never target it.

Procedure

1. List supported languages & confirm target

• git fetch origin en <target-branch>
• Confirm the target branch exists in the table above (or via git ls-remote --heads origin).
• Run git log -1 --format='%ci' origin/en and origin/<target> to report how stale the translation is.

2. Set up the working branch

• Create the dev branch off the target language branch (so the PR diffs against it): git checkout -B <work-branch> origin/<target-branch>
• Load the target branch's glossaries.md (its translation glossary). If the branch has no glossaries.md yet, seed one for this language (English source term → translation, plus a register note and the keep-in-English list).
• Determine the scope's English source files from origin/en (use SUMMARY.md and the directory tree). Compare the en and target SUMMARY.md to find pages with no translated counterpart.

3. Per-section translation subagents

For the chosen scope, materialize the English source files into the working tree (git checkout origin/en -- <path>/), then spawn one translation subagent per coherent sub-area (run them in parallel). Each subagent:

1. Translates the assigned .md files in place into the target language.
2. Handles images — see the IMAGE POLICY below. This is the most common gap.
3. Follows the TRANSLATION POLICY checklist below.

Give every translation subagent the policy plus the contents of the target branch's glossaries.md in its prompt.

4. Update SUMMARY.md (mirror the en IA)

Add the new/updated entries to the target branch's SUMMARY.md, mirroring the current English information architecture (same section grouping and same path/to/file.md paths as en), but with translated titles. Keep emojis. Mandatory: when the English docs use new directory paths that the language branch's SUMMARY does not yet reference (a path migration, e.g. legacy chan-pin//products/ → trade//earn/), the SUMMARY.md update must ship in the same PR — never leave new pages unlinked or the nav pointing at old paths.

5. Copy referenced image assets ⚠️ critical

GitBook image refs point at .gitbook/assets/<file> relative to repo root. These binary assets exist on en but are usually absent on the language branch, so images render broken/omitted. After translating, scan every translated file for .gitbook/assets/... references and git checkout origin/en -- "<asset>" for any that are missing on the target branch. (Filenames often contain spaces and parentheses — quote them. Watch for Screenshot ...png names and filenames containing a U+202F narrow no-break space before AM/PM — match the exact bytes, not a regular space.)

6. Commit & open PR

• Commit translations and assets (separate, clearly-described commits are fine).
• Push the work branch.
• Open a PR with base = the target language branch (NOT en, NOT the repo default).
• PR body: scope, conventions applied, and a note that a native-speaker review is recommended before merge.
• Do not merge. If git push is blocked (403) in this environment, retry; the GitHub MCP branch/PR tools may have write access even when raw git does not.

TRANSLATION POLICY (rules every translation subagent must follow)

• P1 Frontmatter — keep --- delimiters and YAML keys; translate only natural-language values (e.g. description:). Never translate keys like icon:.
• P2 Structure — preserve heading levels, list nesting, tables, blockquotes, and GitBook blocks ({% hint %}, {% tabs %}, <figure>, <table>).
• P3 Links & paths — never alter URLs, relative link targets, or anchors. Translate only human-readable link text.
• P4 Images present — every image reference in the en source must exist in the translation, and the referenced .gitbook/assets/<file> must be included in the branch (copied from en if missing). No broken/omitted images.
• P5 Brand/terms — keep product/brand names in English (PancakeSwap, MEV Guard, Social Login, Pancake Gifts, veCAKE, CAKE, etc.) and keep acronyms (MEV, RPC, FAQ, APR, IFO, TWAP) as-is. This includes versioned upgrade names — e.g. "Tokenomics 3.0", "PancakeSwap Infinity", "v3/v2" — keep the English product name even when surrounding descriptive words are translated. The branch's glossaries.md holds the full keep-in-English list.
• P6 Inline tokens — never change HTML entities ( ), code spans/blocks, or placeholders (e.g. {Gift_Code}).
• P7 Emojis — preserve emojis in headings and titles.
• P8 SUMMARY — new pages added under the correct section mirroring the en IA; titles translated; file paths identical to en; no dangling links. The SUMMARY nav title should be consistent with the page's translated H1 (the P5 acronym exception applies — e.g. "FAQ" in nav vs "常见问题解答" in the H1 is acceptable).
• P9 Completeness — no untranslated English prose left behind (other than the allowed brand/technical terms in P5).
• P10 Glossary & register — apply the target branch's glossaries.md consistently, including its register note (e.g. Chinese uses the informal 你).

Glossaries

Each translation branch carries its own glossaries.md at the repo root, keyed to the English source of truth (English term → translation, plus a register note and the keep-in-English list). The English column is canonical and identical across languages, so the branches stay decoupled — editing one language's glossary never touches another.

Workflow: after checking out the target branch (step 2), read its glossaries.md and pass it to every translation subagent. When you settle a new term during a run, add it to that branch's glossaries.md only. If a branch has no glossaries.md yet, create one.