From 00d59988d8a706a40fe77fe63887d6fc94d4cd57 Mon Sep 17 00:00:00 2001
From: ComfyUI Wiki <contact@comfyui-wiki.com>
Date: Mon, 30 Mar 2026 00:20:07 +0800
Subject: [PATCH 1/5] Add automated translation sync workflow with DeepSeek API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- .github/workflows/translation-sync.yml: triggers on push to main,
  detects which language files are out of sync, runs translation script,
  creates a PR for review
- .github/scripts/translate-sync.py: diff-based translation — only
  translates changed sections (split by headings), skips files already
  updated in the same commit
- .github/scripts/translation-config.json: language config, easily
  extensible to add new languages

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/scripts/translate-sync.py       | 427 ++++++++++++++++++++++++
 .github/scripts/translation-config.json |  23 ++
 .github/workflows/translation-sync.yml  | 121 +++++++
 3 files changed, 571 insertions(+)
 create mode 100644 .github/scripts/translate-sync.py
 create mode 100644 .github/scripts/translation-config.json
 create mode 100644 .github/workflows/translation-sync.yml

diff --git a/.github/scripts/translate-sync.py b/.github/scripts/translate-sync.py
new file mode 100644
index 00000000..c5b03569
--- /dev/null
+++ b/.github/scripts/translate-sync.py
@@ -0,0 +1,427 @@
+#!/usr/bin/env python3
+"""
+Translation sync script for ComfyUI docs.
+
+Usage:
+    python translate-sync.py --before <sha> --after <sha> [--dry-run]
+
+For each changed English .mdx file, checks which language translations are
+out of sync and translates only the changed sections using DeepSeek API.
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    from openai import OpenAI
+except ImportError:
+    print("Error: openai package required. Run: pip install openai")
+    sys.exit(1)
+
+SCRIPT_DIR = Path(__file__).parent
+REPO_ROOT = SCRIPT_DIR.parent.parent
+CONFIG_PATH = SCRIPT_DIR / "translation-config.json"
+
+
+def load_config() -> dict:
+    with open(CONFIG_PATH) as f:
+        return json.load(f)
+
+
+def get_changed_files(before_sha: str, after_sha: str, exclude_dirs: list[str]) -> list[str]:
+    """Get English .mdx files changed between two commits."""
+    result = subprocess.run(
+        ["git", "diff", "--name-only", "--diff-filter=ACMRT", before_sha, after_sha],
+        capture_output=True, text=True, cwd=REPO_ROOT
+    )
+    files = []
+    for line in result.stdout.strip().splitlines():
+        if not line.endswith(".mdx"):
+            continue
+        # Skip language dirs
+        if any(line.startswith(d + "/") for d in exclude_dirs):
+            continue
+        files.append(line)
+    return files
+
+
+def get_files_changed_in_range(before_sha: str, after_sha: str) -> set[str]:
+    """Get all files (any language) changed in the commit range."""
+    result = subprocess.run(
+        ["git", "diff", "--name-only", before_sha, after_sha],
+        capture_output=True, text=True, cwd=REPO_ROOT
+    )
+    return set(result.stdout.strip().splitlines())
+
+
+def get_file_diff(before_sha: str, after_sha: str, filepath: str) -> str:
+    """Get the unified diff of a file between two commits."""
+    result = subprocess.run(
+        ["git", "diff", before_sha, after_sha, "--", filepath],
+        capture_output=True, text=True, cwd=REPO_ROOT
+    )
+    return result.stdout
+
+
+def split_into_sections(content: str) -> list[dict]:
+    """
+    Split MDX content into sections by top-level headings (## or ###).
+    Returns list of {"heading": str, "content": str, "level": int}
+    """
+    lines = content.splitlines(keepends=True)
+    sections = []
+    current_heading = None
+    current_level = 0
+    current_lines = []
+    frontmatter_done = False
+    frontmatter_lines = []
+    in_frontmatter = False
+
+    for i, line in enumerate(lines):
+        # Handle frontmatter
+        if i == 0 and line.strip() == "---":
+            in_frontmatter = True
+            frontmatter_lines.append(line)
+            continue
+        if in_frontmatter:
+            frontmatter_lines.append(line)
+            if line.strip() == "---":
+                in_frontmatter = False
+                frontmatter_done = True
+            continue
+
+        heading_match = re.match(r'^(#{2,3})\s+(.+)', line)
+        if heading_match:
+            # Save current section
+            if current_lines:
+                sections.append({
+                    "heading": current_heading,
+                    "level": current_level,
+                    "content": "".join(current_lines)
+                })
+            current_heading = heading_match.group(2).strip()
+            current_level = len(heading_match.group(1))
+            current_lines = [line]
+        else:
+            current_lines.append(line)
+
+    # Save last section
+    if current_lines:
+        sections.append({
+            "heading": current_heading,
+            "level": current_level,
+            "content": "".join(current_lines)
+        })
+
+    return {
+        "frontmatter": "".join(frontmatter_lines),
+        "sections": sections
+    }
+
+
+def get_changed_headings_from_diff(diff: str) -> set[str]:
+    """Extract headings of sections that were changed in the diff."""
+    changed_headings = set()
+    current_heading = None
+
+    for line in diff.splitlines():
+        # Track which heading we're under in the diff
+        heading_match = re.match(r'^[+-]\s*(#{2,3})\s+(.+)', line)
+        if heading_match:
+            current_heading = heading_match.group(2).strip()
+            changed_headings.add(current_heading)
+        elif line.startswith('+') or line.startswith('-'):
+            if current_heading:
+                changed_headings.add(current_heading)
+
+    return changed_headings
+
+
+def translate_content(
+    client: OpenAI,
+    content: str,
+    target_language: str,
+    target_language_name: str,
+    preserve_terms: list[str],
+    is_full_file: bool = False,
+    existing_translation: Optional[str] = None
+) -> str:
+    """Translate MDX content using DeepSeek API."""
+    preserve_str = ", ".join(preserve_terms)
+
+    if existing_translation:
+        system_prompt = f"""You are a technical documentation translator. Translate the given MDX content into {target_language_name}.
+
+Rules:
+- Preserve ALL MDX component tags exactly: <Card>, <Accordion>, <AccordionGroup>, <Note>, <Warning>, <Tip>, <Steps>, <Step>, <Tab>, <Tabs>, <Columns>, <video>, etc.
+- Preserve ALL code blocks (``` ``` ```) without translating the code inside
+- Preserve ALL link URLs (href values) — only translate visible link text if appropriate
+- Preserve frontmatter keys but translate their string values (title, description, sidebarTitle)
+- Do NOT translate these technical terms: {preserve_str}
+- Do NOT translate image paths, file paths, or URLs
+- Translate naturally and accurately for {target_language_name} readers
+- Return ONLY the translated content, no explanations"""
+
+        user_prompt = f"""Update this {target_language_name} translation to match the new English source.
+Only update the parts that changed — preserve existing translations where the English is unchanged.
+
+New English source:
+{content}
+
+Current {target_language_name} translation (for reference):
+{existing_translation}"""
+    else:
+        system_prompt = f"""You are a technical documentation translator. Translate the given MDX content into {target_language_name}.
+
+Rules:
+- Preserve ALL MDX component tags exactly: <Card>, <Accordion>, <AccordionGroup>, <Note>, <Warning>, <Tip>, <Steps>, <Step>, <Tab>, <Tabs>, <Columns>, <video>, etc.
+- Preserve ALL code blocks (``` ``` ```) without translating the code inside
+- Preserve ALL link URLs (href values) — only translate visible link text if appropriate
+- Preserve frontmatter keys but translate their string values (title, description, sidebarTitle)
+- Do NOT translate these technical terms: {preserve_str}
+- Do NOT translate image paths, file paths, or URLs
+- Translate naturally and accurately for {target_language_name} readers
+- Return ONLY the translated content, no explanations"""
+
+        user_prompt = f"Translate this MDX documentation into {target_language_name}:\n\n{content}"
+
+    response = client.chat.completions.create(
+        model="deepseek-chat",
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt}
+        ],
+        temperature=0.2,
+    )
+    return response.choices[0].message.content.strip()
+
+
+def translate_frontmatter(
+    client: OpenAI,
+    frontmatter: str,
+    target_language_name: str,
+    existing_frontmatter: Optional[str] = None
+) -> str:
+    """Translate only the translatable frontmatter values."""
+    if not frontmatter.strip():
+        return frontmatter
+
+    prompt = f"""Translate the values of these YAML frontmatter fields into {target_language_name}.
+Only translate: title, description, sidebarTitle.
+Keep all other keys and values exactly as-is.
+Return only the frontmatter block including the --- delimiters.
+
+{frontmatter}"""
+
+    if existing_frontmatter:
+        prompt += f"\n\nExisting {target_language_name} frontmatter for reference:\n{existing_frontmatter}"
+
+    response = client.chat.completions.create(
+        model="deepseek-chat",
+        messages=[{"role": "user", "content": prompt}],
+        temperature=0.1,
+    )
+    return response.choices[0].message.content.strip()
+
+
+def process_file(
+    client: OpenAI,
+    en_filepath: str,
+    lang: dict,
+    before_sha: str,
+    after_sha: str,
+    config: dict,
+    dry_run: bool = False
+) -> Optional[str]:
+    """
+    Translate a single file for a single language.
+    Returns the lang_filepath if translation was written, None otherwise.
+    """
+    # Determine language file path
+    if en_filepath.startswith("snippets/"):
+        snippets_dir = lang.get("snippets_dir", f"snippets/{lang['code']}")
+        lang_filepath = en_filepath.replace("snippets/", f"{snippets_dir}/", 1)
+    else:
+        lang_filepath = f"{lang['dir']}/{en_filepath}"
+
+    en_abs = REPO_ROOT / en_filepath
+    lang_abs = REPO_ROOT / lang_filepath
+
+    if not en_abs.exists():
+        print(f"  [SKIP] English source not found: {en_filepath}")
+        return None
+
+    en_content = en_abs.read_text(encoding="utf-8")
+    existing_content = lang_abs.read_text(encoding="utf-8") if lang_abs.exists() else None
+    is_new_file = existing_content is None
+
+    print(f"  → {'[NEW]' if is_new_file else '[UPDATE]'} {lang_filepath}")
+
+    if dry_run:
+        return lang_filepath
+
+    preserve_terms = config.get("preserve_terms", [])
+
+    if is_new_file:
+        # Translate the whole file
+        translated = translate_content(
+            client, en_content,
+            target_language=lang["code"],
+            target_language_name=lang["name"],
+            preserve_terms=preserve_terms,
+            is_full_file=True
+        )
+        lang_abs.parent.mkdir(parents=True, exist_ok=True)
+        lang_abs.write_text(translated, encoding="utf-8")
+    else:
+        # Diff-based: only translate changed sections
+        diff = get_file_diff(before_sha, after_sha, en_filepath)
+        changed_headings = get_changed_headings_from_diff(diff)
+
+        parsed_en = split_into_sections(en_content)
+        parsed_lang = split_into_sections(existing_content)
+
+        # Build heading -> section map for existing translation
+        lang_sections_map = {s["heading"]: s for s in parsed_lang["sections"]}
+
+        # Translate frontmatter if it changed (check diff)
+        frontmatter_changed = any(
+            line.startswith(('+', '-')) and ('title:' in line or 'description:' in line or 'sidebarTitle:' in line)
+            for line in diff.splitlines()
+            if not line.startswith('+++') and not line.startswith('---')
+        )
+
+        new_frontmatter = parsed_lang["frontmatter"]
+        if frontmatter_changed or not parsed_lang["frontmatter"].strip():
+            print(f"    Translating frontmatter...")
+            new_frontmatter = translate_frontmatter(
+                client, parsed_en["frontmatter"],
+                target_language_name=lang["name"],
+                existing_frontmatter=parsed_lang["frontmatter"]
+            )
+
+        # For each section in new English, translate if changed
+        new_sections = []
+        for en_section in parsed_en["sections"]:
+            heading = en_section["heading"]
+            if heading in changed_headings or heading not in lang_sections_map:
+                print(f"    Translating section: {heading or '(intro)'}...")
+                existing_section_content = lang_sections_map.get(heading, {}).get("content")
+                translated_section = translate_content(
+                    client, en_section["content"],
+                    target_language=lang["code"],
+                    target_language_name=lang["name"],
+                    preserve_terms=preserve_terms,
+                    existing_translation=existing_section_content
+                )
+                new_sections.append(translated_section)
+            else:
+                # Keep existing translation unchanged
+                new_sections.append(lang_sections_map[heading]["content"])
+
+        # Reassemble file
+        result = new_frontmatter + "\n" + "\n".join(new_sections)
+        lang_abs.write_text(result, encoding="utf-8")
+
+    return lang_filepath
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Sync translations for changed MDX files")
+    parser.add_argument("--before", required=True, help="Before commit SHA")
+    parser.add_argument("--after", required=True, help="After commit SHA")
+    parser.add_argument("--dry-run", action="store_true", help="Show what would be translated without calling API")
+    parser.add_argument("--output-summary", help="Write PR body summary to this file")
+    args = parser.parse_args()
+
+    config = load_config()
+    languages = config["languages"]
+    exclude_dirs = config["exclude_dirs"]
+
+    api_key = os.environ.get("DEEPSEEK_API_KEY")
+    if not api_key and not args.dry_run:
+        print("Error: DEEPSEEK_API_KEY environment variable not set")
+        sys.exit(1)
+
+    client = None
+    if not args.dry_run:
+        client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com")
+
+    # Get changed English files
+    changed_files = get_changed_files(args.before, args.after, exclude_dirs)
+    if not changed_files:
+        print("No English MDX files changed. Nothing to translate.")
+        sys.exit(0)
+
+    # Get all files changed in commit range (to detect already-synced translations)
+    all_changed = get_files_changed_in_range(args.before, args.after)
+
+    print(f"Changed English files: {len(changed_files)}")
+    for f in changed_files:
+        print(f"  {f}")
+
+    # For each language, find files that need translation
+    translated_files: dict[str, list[str]] = {}
+
+    for lang in languages:
+        lang_dir = lang["dir"]
+        needs_translation = []
+
+        for en_file in changed_files:
+            # Determine expected lang file path
+            if en_file.startswith("snippets/"):
+                snippets_dir = lang.get("snippets_dir", f"snippets/{lang['code']}")
+                lang_file = en_file.replace("snippets/", f"{snippets_dir}/", 1)
+            else:
+                lang_file = f"{lang_dir}/{en_file}"
+
+            # Skip if this lang file was already updated in the same commit range
+            if lang_file in all_changed:
+                print(f"[{lang['code']}] Already synced: {lang_file}")
+                continue
+
+            needs_translation.append(en_file)
+
+        if not needs_translation:
+            print(f"[{lang['code']}] All files already in sync.")
+            continue
+
+        print(f"\n[{lang['code']}] Files to translate: {len(needs_translation)}")
+        translated = []
+        for en_file in needs_translation:
+            result = process_file(client, en_file, lang, args.before, args.after, config, args.dry_run)
+            if result:
+                translated.append(result)
+
+        if translated:
+            translated_files[lang["name"]] = translated
+
+    if not translated_files:
+        print("\nAll translations are already in sync.")
+        sys.exit(0)
+
+    # Write summary for PR body
+    summary_lines = ["## Translation Sync Summary\n"]
+    for lang_name, files in translated_files.items():
+        summary_lines.append(f"### {lang_name}")
+        for f in files:
+            summary_lines.append(f"- `{f}`")
+        summary_lines.append("")
+
+    summary = "\n".join(summary_lines)
+    print("\n" + summary)
+
+    if args.output_summary:
+        Path(args.output_summary).write_text(summary, encoding="utf-8")
+
+    print("\nDone.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/scripts/translation-config.json b/.github/scripts/translation-config.json
new file mode 100644
index 00000000..764cae41
--- /dev/null
+++ b/.github/scripts/translation-config.json
@@ -0,0 +1,23 @@
+{
+  "languages": [
+    {
+      "code": "ja",
+      "name": "Japanese",
+      "dir": "ja",
+      "snippets_dir": "snippets/ja"
+    },
+    {
+      "code": "zh-CN",
+      "name": "Simplified Chinese",
+      "dir": "zh-CN",
+      "snippets_dir": "snippets/zh"
+    }
+  ],
+  "exclude_dirs": ["ja", "zh-CN", "snippets/ja", "snippets/zh"],
+  "preserve_terms": [
+    "ComfyUI", "LoRA", "VAE", "CLIP", "checkpoint", "ControlNet",
+    "KSampler", "UNet", "API", "JSON", "MDX", "GitHub", "Hugging Face",
+    "Civitai", "ComfyUI Manager", "safetensors", "GGUF", "SDXL", "SD1.5",
+    "Stable Diffusion", "Black Forest Labs", "Stability AI", "RealESRGAN"
+  ]
+}
diff --git a/.github/workflows/translation-sync.yml b/.github/workflows/translation-sync.yml
new file mode 100644
index 00000000..6f40899d
--- /dev/null
+++ b/.github/workflows/translation-sync.yml
@@ -0,0 +1,121 @@
+name: Translation Sync
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**/*.mdx'
+      - '!ja/**/*.mdx'
+      - '!zh-CN/**/*.mdx'
+      - '!snippets/ja/**/*.mdx'
+      - '!snippets/zh/**/*.mdx'
+  workflow_dispatch:
+    inputs:
+      before_sha:
+        description: 'Before commit SHA (leave empty to use HEAD~1)'
+        required: false
+      after_sha:
+        description: 'After commit SHA (leave empty to use HEAD)'
+        required: false
+
+jobs:
+  sync-translations:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install openai
+
+      - name: Determine commit range
+        id: commits
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            BEFORE="${{ github.event.inputs.before_sha }}"
+            AFTER="${{ github.event.inputs.after_sha }}"
+            if [ -z "$BEFORE" ]; then BEFORE=$(git rev-parse HEAD~1); fi
+            if [ -z "$AFTER" ]; then AFTER=$(git rev-parse HEAD); fi
+          else
+            BEFORE="${{ github.event.before }}"
+            AFTER="${{ github.event.after }}"
+          fi
+          echo "before=$BEFORE" >> $GITHUB_OUTPUT
+          echo "after=$AFTER" >> $GITHUB_OUTPUT
+          echo "short_sha=$(echo $AFTER | cut -c1-7)" >> $GITHUB_OUTPUT
+
+      - name: Run translation sync
+        id: translate
+        env:
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+        run: |
+          python .github/scripts/translate-sync.py \
+            --before ${{ steps.commits.outputs.before }} \
+            --after ${{ steps.commits.outputs.after }} \
+            --output-summary /tmp/pr-summary.md
+        continue-on-error: false
+
+      - name: Check for translation changes
+        id: check_changes
+        run: |
+          if git diff --quiet && git ls-files --others --exclude-standard | grep -q ".mdx"; then
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+          elif ! git diff --quiet; then
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "No translation changes to commit."
+          fi
+
+      - name: Create branch and commit translations
+        if: steps.check_changes.outputs.has_changes == 'true'
+        run: |
+          BRANCH="i18n/sync-${{ steps.commits.outputs.short_sha }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add "ja/" "zh-CN/" "snippets/ja/" "snippets/zh/" 2>/dev/null || true
+          git diff --cached --quiet || git commit -m "i18n: sync translations for ${{ steps.commits.outputs.short_sha }}"
+          git push origin "$BRANCH"
+          echo "branch=$BRANCH" >> $GITHUB_ENV
+
+      - name: Build PR body
+        if: steps.check_changes.outputs.has_changes == 'true'
+        run: |
+          TRIGGER_SHA="${{ steps.commits.outputs.after }}"
+          SHORT_SHA="${{ steps.commits.outputs.short_sha }}"
+          cat > /tmp/pr-body.md << EOF
+          This PR was auto-generated by the translation sync workflow.
+
+          **Triggered by:** [\`$SHORT_SHA\`](https://github.com/${{ github.repository }}/commit/$TRIGGER_SHA)
+
+          $(cat /tmp/pr-summary.md 2>/dev/null || echo "See changed files for details.")
+
+          ---
+          > Please review the translations before merging.
+          > To add a new language, add an entry to \`.github/scripts/translation-config.json\`.
+          EOF
+
+      - name: Create Pull Request
+        if: steps.check_changes.outputs.has_changes == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh pr create \
+            --title "[i18n] Sync translations for ${{ steps.commits.outputs.short_sha }}" \
+            --body-file /tmp/pr-body.md \
+            --base main \
+            --head "${{ env.branch }}" \
+            --label "translation" || echo "PR may already exist for this branch"

From 89807039a627b09faaa8531382dbf78c717fe4a4 Mon Sep 17 00:00:00 2001
From: ComfyUI Wiki <contact@comfyui-wiki.com>
Date: Mon, 30 Mar 2026 09:33:25 +0800
Subject: [PATCH 2/5] Fix translation sync: index-based section matching, zh
 dir, workflow fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Use section index position instead of heading text to match sections
  between English and translated files (language-agnostic)
- Fix language dir: zh-CN → zh, snippets/zh
- Fix workflow: use step output for branch name instead of env var
- Fix workflow: use gh pr create body inline to avoid heredoc issues
- Add .env to .gitignore

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/scripts/translate-sync.py       | 116 ++++++++++++------------
 .github/scripts/translation-config.json |   6 +-
 .github/workflows/translation-sync.yml  |  42 ++++-----
 3 files changed, 78 insertions(+), 86 deletions(-)

diff --git a/.github/scripts/translate-sync.py b/.github/scripts/translate-sync.py
index c5b03569..fb8760ce 100644
--- a/.github/scripts/translate-sync.py
+++ b/.github/scripts/translate-sync.py
@@ -44,7 +44,6 @@ def get_changed_files(before_sha: str, after_sha: str, exclude_dirs: list[str])
     for line in result.stdout.strip().splitlines():
         if not line.endswith(".mdx"):
             continue
-        # Skip language dirs
         if any(line.startswith(d + "/") for d in exclude_dirs):
             continue
         files.append(line)
@@ -69,22 +68,20 @@ def get_file_diff(before_sha: str, after_sha: str, filepath: str) -> str:
     return result.stdout
 
 
-def split_into_sections(content: str) -> list[dict]:
+def split_into_sections(content: str) -> dict:
     """
     Split MDX content into sections by top-level headings (## or ###).
-    Returns list of {"heading": str, "content": str, "level": int}
+    Returns {"frontmatter": str, "sections": [{"heading", "level", "content"}]}
     """
     lines = content.splitlines(keepends=True)
     sections = []
     current_heading = None
     current_level = 0
     current_lines = []
-    frontmatter_done = False
     frontmatter_lines = []
     in_frontmatter = False
 
     for i, line in enumerate(lines):
-        # Handle frontmatter
         if i == 0 and line.strip() == "---":
             in_frontmatter = True
             frontmatter_lines.append(line)
@@ -93,12 +90,10 @@ def split_into_sections(content: str) -> list[dict]:
             frontmatter_lines.append(line)
             if line.strip() == "---":
                 in_frontmatter = False
-                frontmatter_done = True
             continue
 
         heading_match = re.match(r'^(#{2,3})\s+(.+)', line)
         if heading_match:
-            # Save current section
             if current_lines:
                 sections.append({
                     "heading": current_heading,
@@ -111,7 +106,6 @@ def split_into_sections(content: str) -> list[dict]:
         else:
             current_lines.append(line)
 
-    # Save last section
     if current_lines:
         sections.append({
             "heading": current_heading,
@@ -125,22 +119,31 @@ def split_into_sections(content: str) -> list[dict]:
     }
 
 
-def get_changed_headings_from_diff(diff: str) -> set[str]:
-    """Extract headings of sections that were changed in the diff."""
-    changed_headings = set()
-    current_heading = None
-
+def get_changed_section_indices(diff: str, en_sections: list[dict]) -> set[int]:
+    """
+    Determine which section indices (0-based) changed by matching changed
+    lines from the diff against each section's content.
+    Language-agnostic: does not rely on heading text matching.
+    """
+    changed_lines: set[str] = set()
     for line in diff.splitlines():
-        # Track which heading we're under in the diff
-        heading_match = re.match(r'^[+-]\s*(#{2,3})\s+(.+)', line)
-        if heading_match:
-            current_heading = heading_match.group(2).strip()
-            changed_headings.add(current_heading)
-        elif line.startswith('+') or line.startswith('-'):
-            if current_heading:
-                changed_headings.add(current_heading)
+        if line.startswith('+++') or line.startswith('---'):
+            continue
+        if line.startswith('+') or line.startswith('-'):
+            stripped = line[1:].strip()
+            if stripped:
+                changed_lines.add(stripped)
+
+    if not changed_lines:
+        return set()
 
-    return changed_headings
+    changed_indices: set[int] = set()
+    for i, section in enumerate(en_sections):
+        section_lines = {l.strip() for l in section["content"].splitlines() if l.strip()}
+        if section_lines & changed_lines:
+            changed_indices.add(i)
+
+    return changed_indices
 
 
 def translate_content(
@@ -155,19 +158,20 @@ def translate_content(
     """Translate MDX content using DeepSeek API."""
     preserve_str = ", ".join(preserve_terms)
 
-    if existing_translation:
-        system_prompt = f"""You are a technical documentation translator. Translate the given MDX content into {target_language_name}.
+    system_prompt = f"""You are a technical documentation translator. Translate the given MDX content into {target_language_name}.
 
 Rules:
 - Preserve ALL MDX component tags exactly: <Card>, <Accordion>, <AccordionGroup>, <Note>, <Warning>, <Tip>, <Steps>, <Step>, <Tab>, <Tabs>, <Columns>, <video>, etc.
-- Preserve ALL code blocks (``` ``` ```) without translating the code inside
+- Preserve ALL code blocks (```...```) without translating the code inside
 - Preserve ALL link URLs (href values) — only translate visible link text if appropriate
+- Preserve image alt text as-is if it already exists in the target language; otherwise translate it
 - Preserve frontmatter keys but translate their string values (title, description, sidebarTitle)
 - Do NOT translate these technical terms: {preserve_str}
 - Do NOT translate image paths, file paths, or URLs
 - Translate naturally and accurately for {target_language_name} readers
 - Return ONLY the translated content, no explanations"""
 
+    if existing_translation:
         user_prompt = f"""Update this {target_language_name} translation to match the new English source.
 Only update the parts that changed — preserve existing translations where the English is unchanged.
 
@@ -177,18 +181,6 @@ def translate_content(
 Current {target_language_name} translation (for reference):
 {existing_translation}"""
     else:
-        system_prompt = f"""You are a technical documentation translator. Translate the given MDX content into {target_language_name}.
-
-Rules:
-- Preserve ALL MDX component tags exactly: <Card>, <Accordion>, <AccordionGroup>, <Note>, <Warning>, <Tip>, <Steps>, <Step>, <Tab>, <Tabs>, <Columns>, <video>, etc.
-- Preserve ALL code blocks (``` ``` ```) without translating the code inside
-- Preserve ALL link URLs (href values) — only translate visible link text if appropriate
-- Preserve frontmatter keys but translate their string values (title, description, sidebarTitle)
-- Do NOT translate these technical terms: {preserve_str}
-- Do NOT translate image paths, file paths, or URLs
-- Translate naturally and accurately for {target_language_name} readers
-- Return ONLY the translated content, no explanations"""
-
         user_prompt = f"Translate this MDX documentation into {target_language_name}:\n\n{content}"
 
     response = client.chat.completions.create(
@@ -243,7 +235,6 @@ def process_file(
     Translate a single file for a single language.
     Returns the lang_filepath if translation was written, None otherwise.
     """
-    # Determine language file path
     if en_filepath.startswith("snippets/"):
         snippets_dir = lang.get("snippets_dir", f"snippets/{lang['code']}")
         lang_filepath = en_filepath.replace("snippets/", f"{snippets_dir}/", 1)
@@ -280,19 +271,22 @@ def process_file(
         lang_abs.parent.mkdir(parents=True, exist_ok=True)
         lang_abs.write_text(translated, encoding="utf-8")
     else:
-        # Diff-based: only translate changed sections
+        # Diff-based: only translate changed sections, match by index position
         diff = get_file_diff(before_sha, after_sha, en_filepath)
-        changed_headings = get_changed_headings_from_diff(diff)
 
         parsed_en = split_into_sections(en_content)
         parsed_lang = split_into_sections(existing_content)
 
-        # Build heading -> section map for existing translation
-        lang_sections_map = {s["heading"]: s for s in parsed_lang["sections"]}
+        en_sections = parsed_en["sections"]
+        lang_sections = parsed_lang["sections"]
+
+        # Get changed section indices using content matching (language-agnostic)
+        changed_indices = get_changed_section_indices(diff, en_sections)
 
-        # Translate frontmatter if it changed (check diff)
+        # Translate frontmatter only if translatable fields changed
         frontmatter_changed = any(
-            line.startswith(('+', '-')) and ('title:' in line or 'description:' in line or 'sidebarTitle:' in line)
+            line.startswith(('+', '-')) and
+            any(k in line for k in ('title:', 'description:', 'sidebarTitle:'))
             for line in diff.splitlines()
             if not line.startswith('+++') and not line.startswith('---')
         )
@@ -306,13 +300,13 @@ def process_file(
                 existing_frontmatter=parsed_lang["frontmatter"]
             )
 
-        # For each section in new English, translate if changed
+        # Match sections by index — language-agnostic
         new_sections = []
-        for en_section in parsed_en["sections"]:
-            heading = en_section["heading"]
-            if heading in changed_headings or heading not in lang_sections_map:
+        for i, en_section in enumerate(en_sections):
+            if i in changed_indices:
+                heading = en_section["heading"]
                 print(f"    Translating section: {heading or '(intro)'}...")
-                existing_section_content = lang_sections_map.get(heading, {}).get("content")
+                existing_section_content = lang_sections[i]["content"] if i < len(lang_sections) else None
                 translated_section = translate_content(
                     client, en_section["content"],
                     target_language=lang["code"],
@@ -321,11 +315,21 @@ def process_file(
                     existing_translation=existing_section_content
                 )
                 new_sections.append(translated_section)
+            elif i < len(lang_sections):
+                # Keep existing translation at same index position
+                new_sections.append(lang_sections[i]["content"])
             else:
-                # Keep existing translation unchanged
-                new_sections.append(lang_sections_map[heading]["content"])
+                # New section added beyond existing translation length
+                heading = en_section["heading"]
+                print(f"    Translating new section: {heading or '(intro)'}...")
+                translated_section = translate_content(
+                    client, en_section["content"],
+                    target_language=lang["code"],
+                    target_language_name=lang["name"],
+                    preserve_terms=preserve_terms,
+                )
+                new_sections.append(translated_section)
 
-        # Reassemble file
         result = new_frontmatter + "\n" + "\n".join(new_sections)
         lang_abs.write_text(result, encoding="utf-8")
 
@@ -353,20 +357,17 @@ def main():
     if not args.dry_run:
         client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com")
 
-    # Get changed English files
     changed_files = get_changed_files(args.before, args.after, exclude_dirs)
     if not changed_files:
         print("No English MDX files changed. Nothing to translate.")
         sys.exit(0)
 
-    # Get all files changed in commit range (to detect already-synced translations)
     all_changed = get_files_changed_in_range(args.before, args.after)
 
     print(f"Changed English files: {len(changed_files)}")
     for f in changed_files:
         print(f"  {f}")
 
-    # For each language, find files that need translation
     translated_files: dict[str, list[str]] = {}
 
     for lang in languages:
@@ -374,14 +375,12 @@ def main():
         needs_translation = []
 
         for en_file in changed_files:
-            # Determine expected lang file path
             if en_file.startswith("snippets/"):
                 snippets_dir = lang.get("snippets_dir", f"snippets/{lang['code']}")
                 lang_file = en_file.replace("snippets/", f"{snippets_dir}/", 1)
             else:
                 lang_file = f"{lang_dir}/{en_file}"
 
-            # Skip if this lang file was already updated in the same commit range
             if lang_file in all_changed:
                 print(f"[{lang['code']}] Already synced: {lang_file}")
                 continue
@@ -406,7 +405,6 @@ def main():
         print("\nAll translations are already in sync.")
         sys.exit(0)
 
-    # Write summary for PR body
     summary_lines = ["## Translation Sync Summary\n"]
     for lang_name, files in translated_files.items():
         summary_lines.append(f"### {lang_name}")
@@ -420,7 +418,7 @@ def main():
     if args.output_summary:
         Path(args.output_summary).write_text(summary, encoding="utf-8")
 
-    print("\nDone.")
+    print("Done.")
 
 
 if __name__ == "__main__":
diff --git a/.github/scripts/translation-config.json b/.github/scripts/translation-config.json
index 764cae41..9fc9d843 100644
--- a/.github/scripts/translation-config.json
+++ b/.github/scripts/translation-config.json
@@ -7,13 +7,13 @@
       "snippets_dir": "snippets/ja"
     },
     {
-      "code": "zh-CN",
+      "code": "zh",
       "name": "Simplified Chinese",
-      "dir": "zh-CN",
+      "dir": "zh",
       "snippets_dir": "snippets/zh"
     }
   ],
-  "exclude_dirs": ["ja", "zh-CN", "snippets/ja", "snippets/zh"],
+  "exclude_dirs": ["ja", "zh", "snippets/ja", "snippets/zh"],
   "preserve_terms": [
     "ComfyUI", "LoRA", "VAE", "CLIP", "checkpoint", "ControlNet",
     "KSampler", "UNet", "API", "JSON", "MDX", "GitHub", "Hugging Face",
diff --git a/.github/workflows/translation-sync.yml b/.github/workflows/translation-sync.yml
index 6f40899d..02f5c4dd 100644
--- a/.github/workflows/translation-sync.yml
+++ b/.github/workflows/translation-sync.yml
@@ -7,7 +7,7 @@ on:
     paths:
       - '**/*.mdx'
       - '!ja/**/*.mdx'
-      - '!zh-CN/**/*.mdx'
+      - '!zh/**/*.mdx'
       - '!snippets/ja/**/*.mdx'
       - '!snippets/zh/**/*.mdx'
   workflow_dispatch:
@@ -57,7 +57,6 @@ jobs:
           echo "short_sha=$(echo $AFTER | cut -c1-7)" >> $GITHUB_OUTPUT
 
       - name: Run translation sync
-        id: translate
         env:
           DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
         run: |
@@ -65,14 +64,13 @@ jobs:
             --before ${{ steps.commits.outputs.before }} \
             --after ${{ steps.commits.outputs.after }} \
             --output-summary /tmp/pr-summary.md
-        continue-on-error: false
 
       - name: Check for translation changes
         id: check_changes
         run: |
-          if git diff --quiet && git ls-files --others --exclude-standard | grep -q ".mdx"; then
+          if ! git diff --quiet; then
             echo "has_changes=true" >> $GITHUB_OUTPUT
-          elif ! git diff --quiet; then
+          elif git ls-files --others --exclude-standard | grep -q "\.mdx$"; then
             echo "has_changes=true" >> $GITHUB_OUTPUT
           else
             echo "has_changes=false" >> $GITHUB_OUTPUT
@@ -80,42 +78,38 @@ jobs:
           fi
 
       - name: Create branch and commit translations
+        id: create_branch
         if: steps.check_changes.outputs.has_changes == 'true'
         run: |
           BRANCH="i18n/sync-${{ steps.commits.outputs.short_sha }}"
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git checkout -b "$BRANCH"
-          git add "ja/" "zh-CN/" "snippets/ja/" "snippets/zh/" 2>/dev/null || true
+          git add "ja/" "zh/" "snippets/ja/" "snippets/zh/" 2>/dev/null || true
           git diff --cached --quiet || git commit -m "i18n: sync translations for ${{ steps.commits.outputs.short_sha }}"
           git push origin "$BRANCH"
-          echo "branch=$BRANCH" >> $GITHUB_ENV
+          echo "branch=$BRANCH" >> $GITHUB_OUTPUT
 
-      - name: Build PR body
+      - name: Create Pull Request
         if: steps.check_changes.outputs.has_changes == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           TRIGGER_SHA="${{ steps.commits.outputs.after }}"
           SHORT_SHA="${{ steps.commits.outputs.short_sha }}"
-          cat > /tmp/pr-body.md << EOF
-          This PR was auto-generated by the translation sync workflow.
+          SUMMARY=$(cat /tmp/pr-summary.md 2>/dev/null || echo "See changed files for details.")
 
-          **Triggered by:** [\`$SHORT_SHA\`](https://github.com/${{ github.repository }}/commit/$TRIGGER_SHA)
+          gh pr create \
+            --title "[i18n] Sync translations for ${SHORT_SHA}" \
+            --body "This PR was auto-generated by the translation sync workflow.
+
+          **Triggered by:** [\`${SHORT_SHA}\`](https://github.com/${{ github.repository }}/commit/${TRIGGER_SHA})
 
-          $(cat /tmp/pr-summary.md 2>/dev/null || echo "See changed files for details.")
+          ${SUMMARY}
 
           ---
           > Please review the translations before merging.
-          > To add a new language, add an entry to \`.github/scripts/translation-config.json\`.
-          EOF
-
-      - name: Create Pull Request
-        if: steps.check_changes.outputs.has_changes == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh pr create \
-            --title "[i18n] Sync translations for ${{ steps.commits.outputs.short_sha }}" \
-            --body-file /tmp/pr-body.md \
+          > To add a new language, add an entry to \`.github/scripts/translation-config.json\`." \
             --base main \
-            --head "${{ env.branch }}" \
+            --head "${{ steps.create_branch.outputs.branch }}" \
             --label "translation" || echo "PR may already exist for this branch"

From 99ca3dff1badcba291a9a16bf62ffc2aeaa57ca4 Mon Sep 17 00:00:00 2001
From: ComfyUI Wiki <contact@comfyui-wiki.com>
Date: Mon, 30 Mar 2026 09:39:28 +0800
Subject: [PATCH 3/5] fix: clean up extra blank lines in reassembled
 translation files

---
 .github/scripts/translate-sync.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/scripts/translate-sync.py b/.github/scripts/translate-sync.py
index fb8760ce..2c81c3da 100644
--- a/.github/scripts/translate-sync.py
+++ b/.github/scripts/translate-sync.py
@@ -330,7 +330,9 @@ def process_file(
                 )
                 new_sections.append(translated_section)
 
-        result = new_frontmatter + "\n" + "\n".join(new_sections)
+        # Join sections preserving their original whitespace, add trailing newline
+        joined = "".join(s.rstrip() + "\n" for s in new_sections)
+        result = new_frontmatter.rstrip() + "\n\n" + joined.rstrip() + "\n"
         lang_abs.write_text(result, encoding="utf-8")
 
     return lang_filepath

From bdb1afee68ba8553e7b47ad1a03307f231843033 Mon Sep 17 00:00:00 2001
From: ComfyUI Wiki <contact@comfyui-wiki.com>
Date: Wed, 1 Apr 2026 11:34:29 +0800
Subject: [PATCH 4/5] Rewrite section matching to use diff hunk line numbers

Replace content-based index matching with proper unified diff hunk
header parsing (@@ -a,b +c,d @@). Changed line ranges in the new file
are mapped to section indices via line number overlap, making the logic
fully language-agnostic and correctly handling inserted, deleted, or
reordered sections.

Also add .env to .gitignore.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/scripts/translate-sync.py | 291 +++++++++++++++++-------------
 .gitignore                        |   1 +
 2 files changed, 169 insertions(+), 123 deletions(-)

diff --git a/.github/scripts/translate-sync.py b/.github/scripts/translate-sync.py
index 2c81c3da..9a9d9998 100644
--- a/.github/scripts/translate-sync.py
+++ b/.github/scripts/translate-sync.py
@@ -7,6 +7,13 @@
 
 For each changed English .mdx file, checks which language translations are
 out of sync and translates only the changed sections using DeepSeek API.
+
+Section matching strategy:
+  Uses unified diff hunk headers (@@ -a,b +c,d @@) to get the exact line
+  ranges that changed in the new English file. These are mapped to section
+  indices by comparing line numbers against each section's start/end lines.
+  This is language-agnostic and correctly handles inserted, deleted, or
+  reordered sections.
 """
 
 import argparse
@@ -68,41 +75,69 @@ def get_file_diff(before_sha: str, after_sha: str, filepath: str) -> str:
     return result.stdout
 
 
-def split_into_sections(content: str) -> dict:
+def parse_sections(content: str) -> dict:
     """
-    Split MDX content into sections by top-level headings (## or ###).
-    Returns {"frontmatter": str, "sections": [{"heading", "level", "content"}]}
+    Parse MDX content into frontmatter + sections split by ## / ### headings.
+
+    Returns:
+      {
+        "frontmatter": str,
+        "frontmatter_lines": int,
+        "sections": [
+          {
+            "heading": str | None,
+            "level": int,
+            "content": str,
+            "start_line": int,   # 1-based, inclusive
+            "end_line": int,     # 1-based, inclusive
+          }
+        ]
+      }
     """
     lines = content.splitlines(keepends=True)
-    sections = []
-    current_heading = None
-    current_level = 0
-    current_lines = []
-    frontmatter_lines = []
+    frontmatter_lines_list = []
     in_frontmatter = False
+    fm_done = False
 
     for i, line in enumerate(lines):
         if i == 0 and line.strip() == "---":
             in_frontmatter = True
-            frontmatter_lines.append(line)
+            frontmatter_lines_list.append(line)
             continue
         if in_frontmatter:
-            frontmatter_lines.append(line)
+            frontmatter_lines_list.append(line)
             if line.strip() == "---":
                 in_frontmatter = False
+                fm_done = True
             continue
+        if not fm_done:
+            break
+
+    fm_line_count = len(frontmatter_lines_list)
+    body_lines = lines[fm_line_count:]
 
+    sections = []
+    current_heading = None
+    current_level = 0
+    current_lines = []
+    current_start = fm_line_count + 1  # 1-based
+
+    for i, line in enumerate(body_lines):
+        lineno = fm_line_count + i + 1  # 1-based absolute
         heading_match = re.match(r'^(#{2,3})\s+(.+)', line)
         if heading_match:
             if current_lines:
                 sections.append({
                     "heading": current_heading,
                     "level": current_level,
-                    "content": "".join(current_lines)
+                    "content": "".join(current_lines),
+                    "start_line": current_start,
+                    "end_line": lineno - 1,
                 })
             current_heading = heading_match.group(2).strip()
             current_level = len(heading_match.group(1))
             current_lines = [line]
+            current_start = lineno
         else:
             current_lines.append(line)
 
@@ -110,84 +145,100 @@ def split_into_sections(content: str) -> dict:
         sections.append({
             "heading": current_heading,
             "level": current_level,
-            "content": "".join(current_lines)
+            "content": "".join(current_lines),
+            "start_line": current_start,
+            "end_line": fm_line_count + len(body_lines),
         })
 
     return {
-        "frontmatter": "".join(frontmatter_lines),
-        "sections": sections
+        "frontmatter": "".join(frontmatter_lines_list),
+        "frontmatter_lines": fm_line_count,
+        "sections": sections,
     }
 
 
-def get_changed_section_indices(diff: str, en_sections: list[dict]) -> set[int]:
+def get_changed_line_ranges(diff: str) -> list[tuple[int, int]]:
     """
-    Determine which section indices (0-based) changed by matching changed
-    lines from the diff against each section's content.
-    Language-agnostic: does not rely on heading text matching.
+    Parse unified diff hunk headers to extract changed line ranges in the NEW file.
+    Returns list of (start_line, end_line) — 1-based, inclusive.
+    Pure deletions (count=0) are excluded since they add no new lines.
     """
-    changed_lines: set[str] = set()
+    ranges = []
     for line in diff.splitlines():
-        if line.startswith('+++') or line.startswith('---'):
-            continue
-        if line.startswith('+') or line.startswith('-'):
-            stripped = line[1:].strip()
-            if stripped:
-                changed_lines.add(stripped)
+        m = re.match(r'^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@', line)
+        if m:
+            start = int(m.group(1))
+            count = int(m.group(2)) if m.group(2) is not None else 1
+            if count == 0:
+                continue
+            ranges.append((start, start + count - 1))
+    return ranges
+
+
+def get_changed_section_indices(diff: str, sections: list[dict]) -> set[int]:
+    """
+    Map changed line ranges (from diff hunk headers) onto section indices.
 
-    if not changed_lines:
+    A section is marked as changed if any of its lines overlap with a
+    changed range. This is fully language-agnostic and handles inserted,
+    deleted, or reordered sections correctly.
+    """
+    changed_ranges = get_changed_line_ranges(diff)
+    if not changed_ranges:
         return set()
 
-    changed_indices: set[int] = set()
-    for i, section in enumerate(en_sections):
-        section_lines = {l.strip() for l in section["content"].splitlines() if l.strip()}
-        if section_lines & changed_lines:
-            changed_indices.add(i)
+    changed_indices = set()
+    for i, section in enumerate(sections):
+        s_start = section["start_line"]
+        s_end = section["end_line"]
+        for r_start, r_end in changed_ranges:
+            if r_start <= s_end and r_end >= s_start:
+                changed_indices.add(i)
+                break
 
     return changed_indices
 
 
 def translate_content(
     client: OpenAI,
-    content: str,
+    en_content: str,
     target_language: str,
     target_language_name: str,
     preserve_terms: list[str],
-    is_full_file: bool = False,
-    existing_translation: Optional[str] = None
+    existing_translation: Optional[str] = None,
 ) -> str:
-    """Translate MDX content using DeepSeek API."""
+    """Translate a section of MDX content using DeepSeek API."""
     preserve_str = ", ".join(preserve_terms)
 
-    system_prompt = f"""You are a technical documentation translator. Translate the given MDX content into {target_language_name}.
+    system_prompt = f"""You are a technical documentation translator specializing in MDX format. Translate into {target_language_name}.
 
 Rules:
 - Preserve ALL MDX component tags exactly: <Card>, <Accordion>, <AccordionGroup>, <Note>, <Warning>, <Tip>, <Steps>, <Step>, <Tab>, <Tabs>, <Columns>, <video>, etc.
-- Preserve ALL code blocks (```...```) without translating the code inside
-- Preserve ALL link URLs (href values) — only translate visible link text if appropriate
-- Preserve image alt text as-is if it already exists in the target language; otherwise translate it
-- Preserve frontmatter keys but translate their string values (title, description, sidebarTitle)
+- Preserve ALL code blocks (```...```) — do NOT translate code inside them
+- Preserve ALL link URLs (href values) — only translate visible link text if natural
+- Preserve ALL image paths and alt text formatting — do not rewrite alt text unless translating a new file
+- Preserve frontmatter keys; translate only their string values (title, description, sidebarTitle)
 - Do NOT translate these technical terms: {preserve_str}
-- Do NOT translate image paths, file paths, or URLs
-- Translate naturally and accurately for {target_language_name} readers
-- Return ONLY the translated content, no explanations"""
+- Do NOT translate file paths, URLs, or image paths
+- Return ONLY the translated content with no explanations or preamble"""
 
     if existing_translation:
-        user_prompt = f"""Update this {target_language_name} translation to match the new English source.
-Only update the parts that changed — preserve existing translations where the English is unchanged.
+        user_prompt = f"""Update the {target_language_name} translation to reflect the new English source.
+Only change what has changed — preserve existing translations where English is unchanged.
 
-New English source:
-{content}
+=== NEW ENGLISH SOURCE ===
+{en_content}
 
-Current {target_language_name} translation (for reference):
+=== CURRENT {target_language_name.upper()} TRANSLATION (for reference) ===
 {existing_translation}"""
     else:
-        user_prompt = f"Translate this MDX documentation into {target_language_name}:\n\n{content}"
+        user_prompt = f"Translate the following MDX content into {target_language_name}:\n\n{en_content}"
 
     response = client.chat.completions.create(
         model="deepseek-chat",
         messages=[
             {"role": "system", "content": system_prompt},
-            {"role": "user", "content": user_prompt}
+            {"role": "user", "content": user_prompt},
         ],
         temperature=0.2,
     )
@@ -198,15 +249,14 @@ def translate_frontmatter(
     client: OpenAI,
     frontmatter: str,
     target_language_name: str,
-    existing_frontmatter: Optional[str] = None
+    existing_frontmatter: Optional[str] = None,
 ) -> str:
-    """Translate only the translatable frontmatter values."""
+    """Translate translatable frontmatter fields only."""
     if not frontmatter.strip():
         return frontmatter
 
-    prompt = f"""Translate the values of these YAML frontmatter fields into {target_language_name}.
-Only translate: title, description, sidebarTitle.
-Keep all other keys and values exactly as-is.
+    prompt = f"""Translate ONLY the values of these YAML frontmatter fields into {target_language_name}: title, description, sidebarTitle.
+Leave all other keys and values exactly as-is.
 Return only the frontmatter block including the --- delimiters.
 
 {frontmatter}"""
@@ -223,17 +273,17 @@ def translate_frontmatter(
 
 
 def process_file(
-    client: OpenAI,
+    client: Optional[OpenAI],
     en_filepath: str,
     lang: dict,
     before_sha: str,
     after_sha: str,
     config: dict,
-    dry_run: bool = False
+    dry_run: bool = False,
 ) -> Optional[str]:
     """
     Translate a single file for a single language.
-    Returns the lang_filepath if translation was written, None otherwise.
+    Returns the lang_filepath if a translation was written, None otherwise.
     """
     if en_filepath.startswith("snippets/"):
         snippets_dir = lang.get("snippets_dir", f"snippets/{lang['code']}")
@@ -260,80 +310,80 @@ def process_file(
     preserve_terms = config.get("preserve_terms", [])
 
     if is_new_file:
-        # Translate the whole file
         translated = translate_content(
             client, en_content,
             target_language=lang["code"],
             target_language_name=lang["name"],
             preserve_terms=preserve_terms,
-            is_full_file=True
         )
         lang_abs.parent.mkdir(parents=True, exist_ok=True)
         lang_abs.write_text(translated, encoding="utf-8")
-    else:
-        # Diff-based: only translate changed sections, match by index position
-        diff = get_file_diff(before_sha, after_sha, en_filepath)
+        return lang_filepath
+
+    # --- Diff-based update ---
+    diff = get_file_diff(before_sha, after_sha, en_filepath)
 
-        parsed_en = split_into_sections(en_content)
-        parsed_lang = split_into_sections(existing_content)
+    parsed_en = parse_sections(en_content)
+    parsed_lang = parse_sections(existing_content)
 
-        en_sections = parsed_en["sections"]
-        lang_sections = parsed_lang["sections"]
+    en_sections = parsed_en["sections"]
+    lang_sections = parsed_lang["sections"]
 
-        # Get changed section indices using content matching (language-agnostic)
-        changed_indices = get_changed_section_indices(diff, en_sections)
+    # Use diff hunk line numbers to find which English sections changed
+    changed_indices = get_changed_section_indices(diff, en_sections)
+
+    # Translate frontmatter if translatable fields changed
+    frontmatter_changed = any(
+        line.startswith(('+', '-'))
+        and any(k in line for k in ('title:', 'description:', 'sidebarTitle:'))
+        for line in diff.splitlines()
+        if not line.startswith('+++') and not line.startswith('---')
+    )
 
-        # Translate frontmatter only if translatable fields changed
-        frontmatter_changed = any(
-            line.startswith(('+', '-')) and
-            any(k in line for k in ('title:', 'description:', 'sidebarTitle:'))
-            for line in diff.splitlines()
-            if not line.startswith('+++') and not line.startswith('---')
+    new_frontmatter = parsed_lang["frontmatter"]
+    if frontmatter_changed or not parsed_lang["frontmatter"].strip():
+        print(f"    Translating frontmatter...")
+        new_frontmatter = translate_frontmatter(
+            client, parsed_en["frontmatter"],
+            target_language_name=lang["name"],
+            existing_frontmatter=parsed_lang["frontmatter"],
         )
 
-        new_frontmatter = parsed_lang["frontmatter"]
-        if frontmatter_changed or not parsed_lang["frontmatter"].strip():
-            print(f"    Translating frontmatter...")
-            new_frontmatter = translate_frontmatter(
-                client, parsed_en["frontmatter"],
+    # Build translated section list:
+    # - Changed sections → translate (pass existing lang section as reference)
+    # - Unchanged sections at same index → keep existing lang translation
+    # - New sections beyond lang file length → translate fresh
+    # - Deleted English sections → their lang counterparts are naturally dropped
+    new_sections = []
+    for i, en_section in enumerate(en_sections):
+        if i in changed_indices:
+            heading = en_section["heading"]
+            print(f"    Translating section [{i}]: {heading or '(intro)'}...")
+            existing_lang_section = lang_sections[i]["content"] if i < len(lang_sections) else None
+            translated = translate_content(
+                client, en_section["content"],
+                target_language=lang["code"],
+                target_language_name=lang["name"],
+                preserve_terms=preserve_terms,
+                existing_translation=existing_lang_section,
+            )
+            new_sections.append(translated)
+        elif i < len(lang_sections):
+            new_sections.append(lang_sections[i]["content"])
+        else:
+            heading = en_section["heading"]
+            print(f"    Translating new section [{i}]: {heading or '(intro)'}...")
+            translated = translate_content(
+                client, en_section["content"],
+                target_language=lang["code"],
                 target_language_name=lang["name"],
-                existing_frontmatter=parsed_lang["frontmatter"]
+                preserve_terms=preserve_terms,
             )
+            new_sections.append(translated)
 
-        # Match sections by index — language-agnostic
-        new_sections = []
-        for i, en_section in enumerate(en_sections):
-            if i in changed_indices:
-                heading = en_section["heading"]
-                print(f"    Translating section: {heading or '(intro)'}...")
-                existing_section_content = lang_sections[i]["content"] if i < len(lang_sections) else None
-                translated_section = translate_content(
-                    client, en_section["content"],
-                    target_language=lang["code"],
-                    target_language_name=lang["name"],
-                    preserve_terms=preserve_terms,
-                    existing_translation=existing_section_content
-                )
-                new_sections.append(translated_section)
-            elif i < len(lang_sections):
-                # Keep existing translation at same index position
-                new_sections.append(lang_sections[i]["content"])
-            else:
-                # New section added beyond existing translation length
-                heading = en_section["heading"]
-                print(f"    Translating new section: {heading or '(intro)'}...")
-                translated_section = translate_content(
-                    client, en_section["content"],
-                    target_language=lang["code"],
-                    target_language_name=lang["name"],
-                    preserve_terms=preserve_terms,
-                )
-                new_sections.append(translated_section)
-
-        # Join sections preserving their original whitespace, add trailing newline
-        joined = "".join(s.rstrip() + "\n" for s in new_sections)
-        result = new_frontmatter.rstrip() + "\n\n" + joined.rstrip() + "\n"
-        lang_abs.write_text(result, encoding="utf-8")
+    joined = "".join(s.rstrip() + "\n" for s in new_sections)
+    result = new_frontmatter.rstrip() + "\n\n" + joined.rstrip() + "\n"
+    lang_abs.write_text(result, encoding="utf-8")
 
     return lang_filepath
 
@@ -342,7 +392,7 @@ def main():
     parser = argparse.ArgumentParser(description="Sync translations for changed MDX files")
     parser.add_argument("--before", required=True, help="Before commit SHA")
     parser.add_argument("--after", required=True, help="After commit SHA")
-    parser.add_argument("--dry-run", action="store_true", help="Show what would be translated without calling API")
+    parser.add_argument("--dry-run", action="store_true", help="Preview without calling API or writing files")
     parser.add_argument("--output-summary", help="Write PR body summary to this file")
     args = parser.parse_args()
 
@@ -355,9 +405,7 @@ def main():
         print("Error: DEEPSEEK_API_KEY environment variable not set")
         sys.exit(1)
 
-    client = None
-    if not args.dry_run:
-        client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com")
+    client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com") if not args.dry_run else None
 
     changed_files = get_changed_files(args.before, args.after, exclude_dirs)
     if not changed_files:
@@ -373,20 +421,17 @@ def main():
     translated_files: dict[str, list[str]] = {}
 
     for lang in languages:
-        lang_dir = lang["dir"]
         needs_translation = []
-
         for en_file in changed_files:
             if en_file.startswith("snippets/"):
                 snippets_dir = lang.get("snippets_dir", f"snippets/{lang['code']}")
                 lang_file = en_file.replace("snippets/", f"{snippets_dir}/", 1)
             else:
-                lang_file = f"{lang_dir}/{en_file}"
+                lang_file = f"{lang['dir']}/{en_file}"
 
             if lang_file in all_changed:
                 print(f"[{lang['code']}] Already synced: {lang_file}")
                 continue
-
             needs_translation.append(en_file)
 
         if not needs_translation:
diff --git a/.gitignore b/.gitignore
index 53457f8f..e6c464f5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,4 +7,5 @@ node_modules
 docs.bak
 .claude/settings.json
 .env.local
+.env
 tmp/

From 327751fea64f9ed0daa787e527b65fb1f133b763 Mon Sep 17 00:00:00 2001
From: ComfyUI Wiki <contact@comfyui-wiki.com>
Date: Wed, 1 Apr 2026 12:18:30 +0800
Subject: [PATCH 5/5] feat: add robustness improvements to translation sync
 script

- Per-section error isolation with [FALLBACK] logging
- API retry with exponential backoff (3 attempts)
- MDX tag count validation post-translation
- Frontmatter integrity check (--- delimiters)
- File-level error isolation
- Empty API response guard
- Fallback to full-file translation when diff yields no changed sections
- Add zh-CN to exclude_dirs in translation config

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/scripts/translate-sync.py       | 270 ++++++++++++++++++++----
 .github/scripts/translation-config.json |   2 +-
 .github/workflows/translation-sync.yml  |  49 +++--
 3 files changed, 261 insertions(+), 60 deletions(-)

diff --git a/.github/scripts/translate-sync.py b/.github/scripts/translate-sync.py
index 9a9d9998..c1eb6bf0 100644
--- a/.github/scripts/translate-sync.py
+++ b/.github/scripts/translate-sync.py
@@ -14,6 +14,18 @@
   indices by comparing line numbers against each section's start/end lines.
   This is language-agnostic and correctly handles inserted, deleted, or
   reordered sections.
+
+Robustness:
+  - Per-section error isolation: if a section fails, keeps original translation
+    and logs [FALLBACK]. Other sections are unaffected.
+  - API retry with exponential backoff (3 attempts).
+  - MDX tag count validation: if translated output has mismatched MDX tags,
+    falls back to original translation.
+  - Frontmatter integrity check: validates --- delimiters after translation.
+  - File-level error isolation: one file failing doesn't stop others.
+  - Empty response guard: keeps original if API returns empty content.
+  - Fallback to full-file translation if diff parsing yields no changed sections
+    but the file is confirmed changed.
 """
 
 import argparse
@@ -22,6 +34,7 @@
 import re
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -35,6 +48,9 @@
 REPO_ROOT = SCRIPT_DIR.parent.parent
 CONFIG_PATH = SCRIPT_DIR / "translation-config.json"
 
+# MDX component tags to validate (opening tags)
+MDX_TAG_PATTERN = re.compile(r'<(Card|Accordion|AccordionGroup|Note|Warning|Tip|Steps|Step|Tab|Tabs|Columns|video|CardGroup|Frame|ResponseField|ParamField)\b')
+
 
 def load_config() -> dict:
     with open(CONFIG_PATH) as f:
@@ -199,6 +215,56 @@ def get_changed_section_indices(diff: str, sections: list[dict]) -> set[int]:
     return changed_indices
 
 
+def count_mdx_tags(content: str) -> dict[str, int]:
+    """Count occurrences of known MDX component tags."""
+    counts = {}
+    for m in MDX_TAG_PATTERN.finditer(content):
+        tag = m.group(1)
+        counts[tag] = counts.get(tag, 0) + 1
+    return counts
+
+
+def validate_mdx_tags(original: str, translated: str) -> bool:
+    """
+    Return True if translated content has the same MDX tag counts as original.
+    Allows translated to have 0 of a tag only if original also has 0.
+    """
+    orig_counts = count_mdx_tags(original)
+    trans_counts = count_mdx_tags(translated)
+    for tag, count in orig_counts.items():
+        if count > 0 and trans_counts.get(tag, 0) != count:
+            return False
+    return True
+
+
+def validate_frontmatter(text: str) -> bool:
+    """Return True if text starts and ends with --- delimiters."""
+    stripped = text.strip()
+    lines = stripped.splitlines()
+    if len(lines) < 2:
+        return False
+    return lines[0].strip() == "---" and lines[-1].strip() == "---"
+
+
+def call_api_with_retry(fn, max_retries: int = 3, initial_delay: float = 2.0):
+    """
+    Call fn() with exponential backoff on failure.
+    Raises the last exception if all retries fail.
+    """
+    delay = initial_delay
+    last_exc = None
+    for attempt in range(max_retries):
+        try:
+            return fn()
+        except Exception as e:
+            last_exc = e
+            if attempt < max_retries - 1:
+                print(f"    [RETRY {attempt + 1}/{max_retries}] API error: {e}. Retrying in {delay:.0f}s...")
+                time.sleep(delay)
+                delay *= 2
+    raise last_exc
+
+
 def translate_content(
     client: OpenAI,
     en_content: str,
@@ -234,15 +300,18 @@ def translate_content(
     else:
         user_prompt = f"Translate the following MDX content into {target_language_name}:\n\n{en_content}"
 
-    response = client.chat.completions.create(
-        model="deepseek-chat",
-        messages=[
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": user_prompt},
-        ],
-        temperature=0.2,
-    )
-    return response.choices[0].message.content.strip()
+    def _call():
+        response = client.chat.completions.create(
+            model="deepseek-chat",
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=0.2,
+        )
+        return response.choices[0].message.content.strip()
+
+    return call_api_with_retry(_call)
 
 
 def translate_frontmatter(
@@ -264,12 +333,102 @@ def translate_frontmatter(
     if existing_frontmatter:
         prompt += f"\n\nExisting {target_language_name} frontmatter for reference:\n{existing_frontmatter}"
 
-    response = client.chat.completions.create(
-        model="deepseek-chat",
-        messages=[{"role": "user", "content": prompt}],
-        temperature=0.1,
-    )
-    return response.choices[0].message.content.strip()
+    def _call():
+        response = client.chat.completions.create(
+            model="deepseek-chat",
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.1,
+        )
+        return response.choices[0].message.content.strip()
+
+    return call_api_with_retry(_call)
+
+
+def safe_translate_section(
+    client: OpenAI,
+    index: int,
+    en_section: dict,
+    existing_lang_section: Optional[str],
+    lang: dict,
+    preserve_terms: list[str],
+    fallback_log: list[str],
+) -> str:
+    """
+    Translate a single section with error isolation.
+    Returns the translated content, or falls back to existing_lang_section
+    (or en_section content as last resort) on any error.
+    """
+    heading = en_section["heading"] or "(intro)"
+    en_content = en_section["content"]
+
+    try:
+        translated = translate_content(
+            client, en_content,
+            target_language=lang["code"],
+            target_language_name=lang["name"],
+            preserve_terms=preserve_terms,
+            existing_translation=existing_lang_section,
+        )
+
+        # Guard: empty response
+        if not translated.strip():
+            msg = f"[FALLBACK] Section [{index}] '{heading}': empty API response, keeping original"
+            print(f"    {msg}")
+            fallback_log.append(msg)
+            return existing_lang_section if existing_lang_section else en_content
+
+        # Guard: MDX tag mismatch
+        if not validate_mdx_tags(en_content, translated):
+            msg = f"[FALLBACK] Section [{index}] '{heading}': MDX tag mismatch after translation, keeping original"
+            print(f"    {msg}")
+            fallback_log.append(msg)
+            return existing_lang_section if existing_lang_section else en_content
+
+        return translated
+
+    except Exception as e:
+        msg = f"[FALLBACK] Section [{index}] '{heading}': translation error ({e}), keeping original"
+        print(f"    {msg}")
+        fallback_log.append(msg)
+        return existing_lang_section if existing_lang_section else en_content
+
+
+def safe_translate_frontmatter(
+    client: OpenAI,
+    en_frontmatter: str,
+    lang: dict,
+    existing_frontmatter: str,
+    fallback_log: list[str],
+) -> str:
+    """
+    Translate frontmatter with integrity validation and fallback.
+    """
+    try:
+        translated = translate_frontmatter(
+            client, en_frontmatter,
+            target_language_name=lang["name"],
+            existing_frontmatter=existing_frontmatter,
+        )
+
+        if not translated.strip():
+            msg = "[FALLBACK] Frontmatter: empty response, keeping original"
+            print(f"    {msg}")
+            fallback_log.append(msg)
+            return existing_frontmatter
+
+        if not validate_frontmatter(translated):
+            msg = "[FALLBACK] Frontmatter: missing --- delimiters after translation, keeping original"
+            print(f"    {msg}")
+            fallback_log.append(msg)
+            return existing_frontmatter
+
+        return translated
+
+    except Exception as e:
+        msg = f"[FALLBACK] Frontmatter: error ({e}), keeping original"
+        print(f"    {msg}")
+        fallback_log.append(msg)
+        return existing_frontmatter
 
 
 def process_file(
@@ -280,10 +439,11 @@ def process_file(
     after_sha: str,
     config: dict,
     dry_run: bool = False,
-) -> Optional[str]:
+) -> tuple[Optional[str], list[str]]:
     """
     Translate a single file for a single language.
-    Returns the lang_filepath if a translation was written, None otherwise.
+    Returns (lang_filepath, fallback_log) if a translation was written,
+    (None, []) otherwise.
     """
     if en_filepath.startswith("snippets/"):
         snippets_dir = lang.get("snippets_dir", f"snippets/{lang['code']}")
@@ -296,7 +456,7 @@ def process_file(
 
     if not en_abs.exists():
         print(f"  [SKIP] English source not found: {en_filepath}")
-        return None
+        return None, []
 
     en_content = en_abs.read_text(encoding="utf-8")
     existing_content = lang_abs.read_text(encoding="utf-8") if lang_abs.exists() else None
@@ -305,20 +465,28 @@ def process_file(
     print(f"  → {'[NEW]' if is_new_file else '[UPDATE]'} {lang_filepath}")
 
     if dry_run:
-        return lang_filepath
+        return lang_filepath, []
 
     preserve_terms = config.get("preserve_terms", [])
+    fallback_log: list[str] = []
 
     if is_new_file:
-        translated = translate_content(
-            client, en_content,
-            target_language=lang["code"],
-            target_language_name=lang["name"],
-            preserve_terms=preserve_terms,
-        )
-        lang_abs.parent.mkdir(parents=True, exist_ok=True)
-        lang_abs.write_text(translated, encoding="utf-8")
-        return lang_filepath
+        try:
+            translated = translate_content(
+                client, en_content,
+                target_language=lang["code"],
+                target_language_name=lang["name"],
+                preserve_terms=preserve_terms,
+            )
+            if not translated.strip():
+                print(f"  [ERROR] Empty translation for new file {en_filepath}, skipping")
+                return None, []
+            lang_abs.parent.mkdir(parents=True, exist_ok=True)
+            lang_abs.write_text(translated, encoding="utf-8")
+            return lang_filepath, []
+        except Exception as e:
+            print(f"  [ERROR] Failed to translate new file {en_filepath}: {e}")
+            return None, []
 
     # --- Diff-based update ---
     diff = get_file_diff(before_sha, after_sha, en_filepath)
@@ -332,6 +500,12 @@ def process_file(
     # Use diff hunk line numbers to find which English sections changed
     changed_indices = get_changed_section_indices(diff, en_sections)
 
+    # Fallback: if diff parsing found no changed sections but file is confirmed changed,
+    # translate all sections (file-level change without section-level hunk info)
+    if not changed_indices and diff.strip():
+        print(f"    [WARN] No sections mapped from diff hunks; translating all sections as fallback")
+        changed_indices = set(range(len(en_sections)))
+
     # Translate frontmatter if translatable fields changed
     frontmatter_changed = any(
         line.startswith(('+', '-'))
@@ -343,10 +517,10 @@ def process_file(
     new_frontmatter = parsed_lang["frontmatter"]
     if frontmatter_changed or not parsed_lang["frontmatter"].strip():
         print(f"    Translating frontmatter...")
-        new_frontmatter = translate_frontmatter(
-            client, parsed_en["frontmatter"],
-            target_language_name=lang["name"],
+        new_frontmatter = safe_translate_frontmatter(
+            client, parsed_en["frontmatter"], lang,
             existing_frontmatter=parsed_lang["frontmatter"],
+            fallback_log=fallback_log,
         )
 
     # Build translated section list:
@@ -360,12 +534,9 @@ def process_file(
             heading = en_section["heading"]
             print(f"    Translating section [{i}]: {heading or '(intro)'}...")
             existing_lang_section = lang_sections[i]["content"] if i < len(lang_sections) else None
-            translated = translate_content(
-                client, en_section["content"],
-                target_language=lang["code"],
-                target_language_name=lang["name"],
-                preserve_terms=preserve_terms,
-                existing_translation=existing_lang_section,
+            translated = safe_translate_section(
+                client, i, en_section, existing_lang_section,
+                lang, preserve_terms, fallback_log,
             )
             new_sections.append(translated)
         elif i < len(lang_sections):
@@ -373,11 +544,9 @@ def process_file(
         else:
             heading = en_section["heading"]
             print(f"    Translating new section [{i}]: {heading or '(intro)'}...")
-            translated = translate_content(
-                client, en_section["content"],
-                target_language=lang["code"],
-                target_language_name=lang["name"],
-                preserve_terms=preserve_terms,
+            translated = safe_translate_section(
+                client, i, en_section, None,
+                lang, preserve_terms, fallback_log,
             )
             new_sections.append(translated)
 
@@ -385,7 +554,7 @@ def process_file(
     result = new_frontmatter.rstrip() + "\n\n" + joined.rstrip() + "\n"
     lang_abs.write_text(result, encoding="utf-8")
 
-    return lang_filepath
+    return lang_filepath, fallback_log
 
 
 def main():
@@ -419,6 +588,7 @@ def main():
         print(f"  {f}")
 
     translated_files: dict[str, list[str]] = {}
+    all_fallbacks: dict[str, list[str]] = {}
 
     for lang in languages:
         needs_translation = []
@@ -441,9 +611,14 @@ def main():
         print(f"\n[{lang['code']}] Files to translate: {len(needs_translation)}")
         translated = []
         for en_file in needs_translation:
-            result = process_file(client, en_file, lang, args.before, args.after, config, args.dry_run)
-            if result:
-                translated.append(result)
+            try:
+                result, fallbacks = process_file(client, en_file, lang, args.before, args.after, config, args.dry_run)
+                if result:
+                    translated.append(result)
+                    if fallbacks:
+                        all_fallbacks[result] = fallbacks
+            except Exception as e:
+                print(f"  [ERROR] Unexpected error processing {en_file} for {lang['code']}: {e}")
 
         if translated:
             translated_files[lang["name"]] = translated
@@ -457,6 +632,9 @@ def main():
         summary_lines.append(f"### {lang_name}")
         for f in files:
             summary_lines.append(f"- `{f}`")
+            if f in all_fallbacks:
+                for fb in all_fallbacks[f]:
+                    summary_lines.append(f"  - ⚠️ {fb}")
         summary_lines.append("")
 
     summary = "\n".join(summary_lines)
diff --git a/.github/scripts/translation-config.json b/.github/scripts/translation-config.json
index 9fc9d843..562efb7e 100644
--- a/.github/scripts/translation-config.json
+++ b/.github/scripts/translation-config.json
@@ -13,7 +13,7 @@
       "snippets_dir": "snippets/zh"
     }
   ],
-  "exclude_dirs": ["ja", "zh", "snippets/ja", "snippets/zh"],
+  "exclude_dirs": ["ja", "zh", "zh-CN", "snippets/ja", "snippets/zh"],
   "preserve_terms": [
     "ComfyUI", "LoRA", "VAE", "CLIP", "checkpoint", "ControlNet",
     "KSampler", "UNet", "API", "JSON", "MDX", "GitHub", "Hugging Face",
diff --git a/.github/workflows/translation-sync.yml b/.github/workflows/translation-sync.yml
index 02f5c4dd..3b72c28c 100644
--- a/.github/workflows/translation-sync.yml
+++ b/.github/workflows/translation-sync.yml
@@ -1,15 +1,13 @@
 name: Translation Sync
 
 on:
-  push:
+  # Trigger when a PR with 'needs-translation' label is merged into main
+  pull_request:
+    types: [closed]
     branches:
       - main
-    paths:
-      - '**/*.mdx'
-      - '!ja/**/*.mdx'
-      - '!zh/**/*.mdx'
-      - '!snippets/ja/**/*.mdx'
-      - '!snippets/zh/**/*.mdx'
+
+  # Manual trigger for backfilling or re-running
   workflow_dispatch:
     inputs:
       before_sha:
@@ -18,9 +16,18 @@ on:
       after_sha:
         description: 'After commit SHA (leave empty to use HEAD)'
         required: false
+      pr_number:
+        description: 'PR number (for reference in translation PR body)'
+        required: false
 
 jobs:
   sync-translations:
+    # Only run if: merged PR with 'needs-translation' label, OR manual dispatch
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true &&
+       contains(github.event.pull_request.labels.*.name, 'needs-translation'))
+
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -46,17 +53,23 @@ jobs:
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
             BEFORE="${{ github.event.inputs.before_sha }}"
             AFTER="${{ github.event.inputs.after_sha }}"
+            PR_NUMBER="${{ github.event.inputs.pr_number }}"
             if [ -z "$BEFORE" ]; then BEFORE=$(git rev-parse HEAD~1); fi
             if [ -z "$AFTER" ]; then AFTER=$(git rev-parse HEAD); fi
           else
-            BEFORE="${{ github.event.before }}"
-            AFTER="${{ github.event.after }}"
+            # PR merge: compare base SHA with merge commit SHA
+            BEFORE="${{ github.event.pull_request.base.sha }}"
+            AFTER="${{ github.event.pull_request.merge_commit_sha }}"
+            PR_NUMBER="${{ github.event.pull_request.number }}"
           fi
           echo "before=$BEFORE" >> $GITHUB_OUTPUT
           echo "after=$AFTER" >> $GITHUB_OUTPUT
           echo "short_sha=$(echo $AFTER | cut -c1-7)" >> $GITHUB_OUTPUT
+          echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT
+          echo "pr_title=${{ github.event.pull_request.title }}" >> $GITHUB_OUTPUT
 
       - name: Run translation sync
+        id: translate
         env:
           DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
         run: |
@@ -64,6 +77,7 @@ jobs:
             --before ${{ steps.commits.outputs.before }} \
             --after ${{ steps.commits.outputs.after }} \
             --output-summary /tmp/pr-summary.md
+          echo "exit_code=$?" >> $GITHUB_OUTPUT
 
       - name: Check for translation changes
         id: check_changes
@@ -95,20 +109,29 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          TRIGGER_SHA="${{ steps.commits.outputs.after }}"
           SHORT_SHA="${{ steps.commits.outputs.short_sha }}"
+          AFTER="${{ steps.commits.outputs.after }}"
+          PR_NUMBER="${{ steps.commits.outputs.pr_number }}"
           SUMMARY=$(cat /tmp/pr-summary.md 2>/dev/null || echo "See changed files for details.")
 
+          # Build reference line — link to original PR if available
+          if [ -n "$PR_NUMBER" ]; then
+            REF="Triggered by PR [#${PR_NUMBER}](https://github.com/${{ github.repository }}/pull/${PR_NUMBER}) (\`${SHORT_SHA}\`)"
+          else
+            REF="Triggered by [\`${SHORT_SHA}\`](https://github.com/${{ github.repository }}/commit/${AFTER})"
+          fi
+
           gh pr create \
-            --title "[i18n] Sync translations for ${SHORT_SHA}" \
+            --title "[i18n] Sync translations for #${PR_NUMBER:-$SHORT_SHA}" \
             --body "This PR was auto-generated by the translation sync workflow.
 
-          **Triggered by:** [\`${SHORT_SHA}\`](https://github.com/${{ github.repository }}/commit/${TRIGGER_SHA})
+          **${REF}**
 
           ${SUMMARY}
 
           ---
-          > Please review the translations before merging.
+          > ⚠️ Please review all translations carefully before merging.
+          > Sections marked \`[FALLBACK]\` in the commit log kept the original translation due to API or validation errors.
           > To add a new language, add an entry to \`.github/scripts/translation-config.json\`." \
             --base main \
             --head "${{ steps.create_branch.outputs.branch }}" \