Create or update a zh translation PR from pingcap/docs to pingcap/docs-cn by using repo-local scripts to prepare change-unit translation inputs, apply minimal edits to the existing Chinese files, and create or update the target PR with the same branch, title, body, and label rules used in gh-util.user.js.
Use this skill when the user asks to create a Chinese translation PR in pingcap/docs-cn from an English doc change in pingcap/docs, or when they want to sync later source-PR updates into an existing translation PR.
Do not stop to ask whether to run the scripts referenced in this skill.
create mode: use it when the user gives a source PR URL and wants a new translation PR.update mode: use it when the user gives an existing translation PR URL plus a source update range and wants to sync only the new source changes into that translation PR.translate/<source-head-branch>.update mode, do not ask for the source PR URL if it can be inferred from the target translation PR body..ai/shared/repo-conventions.md.ai/shared/translation-rules.md.ai/shared/translation-terms.mdresources/terms.md when terminology is uncertaingh auth status succeeds.jq is available.docs-cn exists.origin points to your fork and upstream points to pingcap/docs-cn.Provide:
docs-cn clone pathExample:
Please create a translation PR for https://github.com/pingcap/docs/pull/22583 using /path/to/docs-cn.
Provide:
docs-cn clone pathsource update range can be:
<base>..<head> formhttps://github.com/pingcap/docs/pull/<pr-number>/commits/<sha>In update mode, infer the source PR URL in this order:
This PR is translated from: ...Only ask for the source PR URL if both inference paths fail.
When the target translation PR body references multiple source PR URLs, treat that body line as fallback context only. Use the explicit update input first.
Example:
Please sync https://github.com/pingcap/docs-cn/pull/12345 with source update range abc1234..def5678 using /path/to/docs-cn.
Prefer the scripts in .ai/skills/create-or-update-zh-translation-pr/scripts/ over retyping long commands:
prepare_translation_inputs.py: fetch PR and commit metadata with gh, apply the gh-util.user.js title/body/label rules, and generate translation-input.json plus translation-meta.envcreate_translation_branch.sh: sync the fork base branch with upstream, create or reuse the translation branch with gh, and check it out locallyapply_translation_units.py: apply only high-confidence deterministic updates to the target files and write a report of what still needs AI or human attentioncreate_translation_pr.sh: stage only the target files, commit, push, create a new translation PR, or update the existing translation PR with ghThese scripts are the preferred path because they are deterministic and easier to reuse correctly than ad hoc shell snippets.
Do not process every changed file the same way.
TOC.md and keywords.md: use structure-aware updates, not generic section translation..ai files, tidb-cloud/ files, and TOC-tidb-cloud-*.md files: skip them for docs -> docs-cn unless the user explicitly asks otherwise.Run:
python3 .ai/skills/create-or-update-zh-translation-pr/scripts/prepare_translation_inputs.py \
--mode create \
--source-pr-url "<source-pr-url>" \
--target-repo-dir "<path-to-docs-cn>"
Run:
python3 .ai/skills/create-or-update-zh-translation-pr/scripts/prepare_translation_inputs.py \
--mode update \
--target-translation-pr-url "<target-translation-pr-url>" \
--source-update-range "<commit-sha-or-base..head>" \
--target-repo-dir "<path-to-docs-cn>"
This script writes all intermediate artifacts into a temporary $WORKDIR, including:
translation-input.jsontranslation-body.mdtranslation-labels.txttarget-files.txttranslation-meta.envScript behavior in update mode:
translation/done. That label only prevents duplicate create flows.translation-input.json is a change-unit mapping, not just a section dump. It includes:
modesource_prsource_updatetarget_translation_pr in update modesource_filetarget_file_pathstatusprocessing_strategypatchchanges[].actionchanges[].section_pathchanges[].old_source_excerptchanges[].new_source_excerptchanges[].source_section_excerptchanges[].target_section_excerptRun:
bash .ai/skills/create-or-update-zh-translation-pr/scripts/create_translation_branch.sh \
"$WORKDIR/translation-meta.env"
This script uses gh for the remote branch operations and then prepares the local docs-cn worktree on the translation branch.
Run:
python3 .ai/skills/create-or-update-zh-translation-pr/scripts/apply_translation_units.py \
--meta-env "$WORKDIR/translation-meta.env" \
--write
This script is intentionally conservative. It should only auto-apply changes when it can verify them locally, such as:
It writes translation-apply-report.json into $WORKDIR.
Use translation-input.json as the source of truth for what changed, but do not treat it as the only context. For each target file:
docs-cn.translation-input.json.When applying a change unit:
section_path, source_section_excerpt, and target_section_excerpt together to locate the right place.TOC.md: match lines by link target and nearby context, then translate only the visible link text when needed.keywords.md: match and update only the affected letter blocks under TabsPanel, not the full file.Start from the deterministic script output:
translation-apply-report.json.Run this only after the translated target files are ready:
bash .ai/skills/create-or-update-zh-translation-pr/scripts/create_translation_pr.sh \
"$WORKDIR/translation-meta.env"
create mode, this creates a new translation PR.update mode, this commits and pushes the new translation changes to the existing translation branch and updates the existing translation PR metadata.update mode, preserve existing related-source references in the target translation PR body unless the current sync explicitly needs to replace them.update mode, stage only the files listed in target-files.txt and do not widen the update to unrelated local changes.This script intentionally stages only the files listed in target-files.txt.
When you finish the task, report the following information:
translation-input.json pathtranslation-apply-report.json path