doc-i18n: Bilingual Documentation Translation Skill

Purpose

Translate, compare, and synchronize bilingual (Chinese / English) Markdown documentation in path-based i18n projects. Ensure structural alignment, content consistency, and adherence to project-specific conventions.

When to Use

• Translating a documentation file from one language to another
• Comparing two language versions for content drift or missing sections
• Checking translation coverage across the documentation tree
• Fixing heading IDs, internal links, or container syntax after translation
• Creating a new translation file from an existing source

Workflow

Phase 1: Analyze

Before making any changes, analyze the task:

1. Identify the source and target files. Determine the translation direction:

   • English to Chinese: docs/pages/{path}.md to docs/pages/zh/{path}.md
   • Chinese to English: docs/pages/zh/{path}.md to docs/pages/{path}.md

2. Read both files (source and target). If the target file does not exist, note that a new file must be created.

3. Generate a diff report listing:

   • Headings present in source but missing/untranslated in target
   • Paragraphs or sections with untranslated content (e.g., Chinese text in the English file)
   • Structural differences (extra/missing sections, reordered content)
   • Code blocks or examples that differ
   • Internal link path issues (see Link Rules below)
   • Heading ID mismatches (see Heading ID Rules below)

4. Present the report to the user before proceeding. If the task is a full translation, proceed directly after the report.

Phase 2: Translate

Apply translations following these rules:

Content Rules