Markdown Translation Change Review

Purpose

Determine whether a changed Chinese Markdown document should trigger a translation update.

This example follows a conservative documentation flow:

1. A new Chinese source document requires translation.
2. An existing Chinese document with no matching English file does not automatically trigger translation.
3. Changes limited to frontmatter, whitespace, or standalone channel tags do not trigger translation.
4. Other content changes require translation.

Repository Writing Rules

When reviewing Ark_doc Markdown changes, also apply the repository's current writing rules:

• Full SDK / API / cURL examples are maintained in code/ for Chinese docs and code_en/ for English docs.
• Source Markdown should reference managed examples with {{ code:id }}. The id is the code filename without extension.
• Chinese and English counterparts should use the same code id when they represent the same example.
• If a Chinese Markdown change adds or changes a {{ code:id }} reference, check whether the corresponding English document should reference the same id from code_en/.
• If a Chinese code example under code/ changes in a way that affects user-visible behavior, comments, prompts, parameters, or API usage, treat it as substantive and recommend checking or updating the corresponding code_en/ example.
• Changes limited to code Frontmatter metadata do not by themselves require translation, unless title_en, description_en, or user-visible English guidance is incorrect.
• Do not suggest adding large inline SDK / API / cURL examples to Markdown when a managed {{ code:id }} example should be used.
• For authoring details, refer to maintainer_guides/code_sample_authoring_guide.md.

Required Input

Collect:

• The baseline Chinese Markdown file, if the document already existed.
• The updated Chinese Markdown file.
• The matching English Markdown file, if it exists.
• The repository's actual channel-tag syntax, if it differs from the bundled example.
• Any changed code/ or code_en/ files referenced by changed Markdown, when available.

Workflow

1. Determine whether the updated source file is new.

2. Determine whether a matching English document exists.

3. Run the bundled script:

   python3 scripts/check_translation_trigger.py \
     --baseline /path/to/baseline.md \
     --updated /path/to/updated.md \
     --english /path/to/docs_en/file.md
   

   Copy

4. Read the JSON result.

5. If translation_required is true, summarize the substantive changed lines and recommend translation.

6. If it is false, state the reason and do not modify translation files unless the user asks.

7. If the change only updates {{ code:id }} references, classify whether the referenced example change is substantive:

   • Same code id, same user-visible behavior: usually no translation update.
   • New or renamed code id, changed prompt/comments/API parameters, or changed example scenario: recommend English-side review.
   • Formatting-only changes, code Frontmatter-only changes, or whitespace-only changes: usually no translation update.

Important Limits

• The bundled script is a lightweight example, not a full semantic Markdown parser.
• Customize CHANNEL_TAG_PATTERN in the script to match the repository's channel labels.
• Do not delete or overwrite source, baseline, or English files.
• Do not automatically invoke translation; only report the decision unless the user explicitly asks to translate.

Output Format

Return:

Decision: translation required / not required
Reason: <machine-readable reason>
Evidence: <short summary of substantive changes>
Next action: <translate / no action / request review>