Baoyu Translate

Translator

Three-mode translation skill: quick for direct translation, normal for analysis-informed translation, refined for full publication-quality workflow with review and polish.

User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

1. Prefer built-in user-input tools exposed by the current agent runtime — e.g., AskUserQuestion, request_user_input, clarify, ask_user, or any equivalent. 2. Fallback: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question. 3. Batching: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.

Concrete AskUserQuestion references below are examples — substitute the local equivalent in other runtimes.

Script Directory

Scripts in scripts/ subdirectory. {baseDir} = this SKILL.md's directory path. Resolve ${BUN_X} runtime: if bun installed → bun; if npx available → npx -y bun; else suggest installing bun. Replace {baseDir} and ${BUN_X} with actual values.

Preferences (EXTEND.md)

Check EXTEND.md in priority order — the first one found wins:

EXTEND.md supports: default target language, default mode, target audience, custom glossaries (inline or file path), translation style, chunk settings.

Schema: references/config/extend-schema.md.

First-Time Setup (BLOCKING)

CRITICAL: When EXTEND.md is not found, you MUST run the first-time setup before ANY translation. This is a BLOCKING operation.

Full reference: references/config/first-time-setup.md

Use AskUserQuestion with all questions (target language, mode, audience, style, save location) in ONE call. After user answers, create EXTEND.md at the chosen location, confirm "Preferences saved to [path]", then continue.

Defaults

All configurable values in one place. EXTEND.md overrides these; CLI flags override EXTEND.md.

Modes

Default mode: Normal (can be overridden in EXTEND.md default_mode setting).

Style presets — control the voice and tone of the translation (independent of audience):

Custom style descriptions are also accepted, e.g., --style "poetic and lyrical".

Auto-detection:

• "快翻", "quick", "直接翻译" → quick mode
• "精翻", "refined", "publication quality", "proofread" → refined mode
• Otherwise → default mode (normal)

Upgrade prompt: After normal mode completes, display:

Translation saved. To further review and polish, reply "继续润色" or "refine".

If user responds, continue with review → polish steps (same as refined mode Steps 4-6 in refined-workflow.md) on the existing output.

Audience presets:

Custom audience descriptions are also accepted, e.g., --audience "AI感兴趣的普通读者".

Workflow

Step 1: Load Preferences

1.1 Check EXTEND.md (see Preferences section above)

1.2 Load built-in glossary for the language pair if available:

• EN→ZH: references/glossary-en-zh.md

1.3 Merge glossaries: EXTEND.md glossary (inline) + EXTEND.md glossary_files (external files, paths relative to EXTEND.md location) + built-in glossary + --glossary file (CLI overrides all)

Step 2: Materialize Source & Create Output Directory

Materialize source (file as-is, inline text/URL → save to translate/{slug}.md), then create output directory: {source-dir}/{source-basename}-{target-lang}/. Detect source language if --from not specified.

Full details: references/workflow-mechanics.md

Output directory contents (all intermediate and final files go here):

Step 3: Assess Content Length

Quick mode does not chunk — translate directly regardless of length. Before translating, estimate word count. If content exceeds chunk threshold (default 4000 words), proactively warn: "This article is ~{N} words. Quick mode translates in one pass without chunking — for long content, --mode normal produces better results with terminology consistency." Then proceed if user doesn't switch.

For normal and refined modes:

3.1 Long Content Preparation (normal/refined modes, >= chunk threshold only)

Before translating chunks:

1. Extract terminology: Scan entire document for proper nouns, technical terms, recurring phrases 2. Build session glossary: Merge extracted terms with loaded glossaries, establish consistent translations 3. Split into chunks: Use ${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words <chunk_max_words>] [--output-dir <output-dir>]

• Parses markdown blocks (headings, paragraphs, lists, code blocks, tables, etc.)
• Splits at markdown block boundaries to preserve structure
• If a single block exceeds the threshold, falls back to line splitting, then word splitting

4. Assemble translation prompt:

• Main agent reads 01-analysis.md (if exists) and assembles shared context using Part 1 of references/subagent-prompt-template.md — inlining: target style, content background, merged glossary, and translation challenges
• Save as 02-prompt.md in the output directory (shared context only, no task instructions)

5. Draft translation via subagents (if Agent tool available):

• Spawn one subagent per chunk, all in parallel (Part 2 of the template)
• Each subagent reads 02-prompt.md for shared context, receives chunk position info (chunk N of M + brief context of where it sits in the argument), translates its chunk, saves to chunks/chunk-NN-draft.md
• Consistency is guaranteed by the shared 02-prompt.md (glossary, figurative language mapping, comprehension challenges, source voice, and translation challenges from analysis)
• If no chunks (content under threshold): spawn one subagent for the entire source file
• If Agent tool is unavailable, translate chunks sequentially inline using 02-prompt.md

6. Merge: Once all subagents complete, combine translated chunks in order. If chunks/frontmatter.md exists, prepend it. Save as 03-draft.md (refined) or translation.md (normal) 7. All intermediate files (source chunks + translated chunks) are preserved in chunks/

After chunked draft is merged, return control to main agent for critical review, revision, and polish (Step 4).

Step 4: Translate & Refine

Translation principles (apply to all modes):

• Rewrite, not translate: Rewrite content into natural, engaging target language as if a skilled native writer composed it from scratch. Quality test: "Does this read like it was originally written in the target language?"
• Accuracy first: Facts, data, and logic must match the original exactly
• Natural flow: Use idiomatic target language word order. Break long source sentences into shorter, natural ones. Interpret metaphors and idioms by intended meaning, not word-for-word
• Terminology: Use standard translations consistently. First occurrence of specialized terms: annotate with original in parentheses
• Preserve format: Keep all markdown formatting (headings, bold, italic, images, links, code blocks)
• Proactive interpretation: For jargon or concepts the target audience may lack context for, add concise explanations in bold parentheses （**解释**）. Keep annotations few — only where genuinely needed for comprehension
• Frontmatter: If source has YAML frontmatter, rename source-metadata fields with source prefix (camelCase: url→sourceUrl, title→sourceTitle, etc.), add translated values as new top-level fields (skip title if body has H1), keep other fields as-is

Quick Mode

Translate directly → save to translation.md. Apply all translation principles above.

Normal Mode

1. Analyze → 01-analysis.md (domain, tone, terminology, translation challenges) 2. Assemble prompt → 02-prompt.md (translation instructions with context, glossary, challenges) 3. Translate (following 02-prompt.md) → translation.md

After completion, prompt user: "Translation saved. To further review and polish, reply 继续润色 or refine."

If user continues, proceed with critical review → revision → polish (same as refined mode Steps 4-6 below), saving 03-draft.md (rename current translation.md), 04-critique.md, 05-revision.md, and updated translation.md.

Refined Mode

Full workflow for publication quality. See references/refined-workflow.md for detailed guidelines per step.

The subagent (if used in Step 3.1) only handles the initial draft. All subsequent steps (critical review, revision, polish) are handled by the main agent, which may delegate to subagents at its discretion.

Steps and saved files (all in output directory): 1. Analyze → 01-analysis.md (domain, tone, terminology, translation challenges) 2. Assemble prompt → 02-prompt.md (translation instructions with inlined context) 3. Draft → 03-draft.md (initial translation with translator's notes; from subagent if chunked) 4. Critical review → 04-critique.md (diagnosis only: accuracy, Europeanized language, strategy execution, expression issues) 5. Revision → 05-revision.md (apply all critique findings to produce revised translation) 6. Polish → translation.md (final publication-quality translation)

Each step reads the previous step's file and builds on it.

Step 5: Output

Final translation is always at translation.md in the output directory.

After the final translation is written, do a lightweight image-language pass:

1. Collect image references from the translated article 2. Identify likely text-heavy images such as covers, screenshots, diagrams, charts, frameworks, and infographics 3. If any image likely contains a main text language that does not match the translated article language, proactively remind the user 4. The reminder must be a list only. Do not automatically localize those images unless the user asks

Reminder format (use whatever image syntax the article already uses — standard markdown or wikilink):

Possible image localization needed:
- ![example cover](attachments/example-cover.png): likely still contains source-language text while the article is now in target language
- ![example diagram](attachments/example-diagram.png): likely text-heavy framework graphic, check whether labels need translation

Display summary:

**Translation complete** ({mode} mode)

Source: {source-path}
Languages: {from} → {to}
Output dir: {output-dir}/
Final: {output-dir}/translation.md
Glossary terms applied: {count}

If mismatched image-language candidates were found, append a short note after the summary telling the user that some embedded images may still need image-text localization, followed by the candidate list.

Extension Support

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.

EXTEND.md Schema for baoyu-translate

Format

EXTEND.md uses YAML format:

# Default target language (ISO code or common name)
target_language: zh-CN

# Default translation mode
default_mode: normal  # quick | normal | refined

# Target audience (affects annotation depth and register)
audience: general  # general | technical | academic | business | or custom string

# Translation style preference
style: storytelling  # storytelling | formal | technical | literal | academic | business | humorous | conversational | elegant | or custom string

# Word count threshold to trigger chunked translation
chunk_threshold: 4000

# Max words per chunk
chunk_max_words: 5000

# Custom glossary (merged with built-in glossary)
# CLI --glossary flag overrides these
# Supports inline entries and/or file paths
glossary:
  - from: "Reinforcement Learning"
    to: "强化学习"
  - from: "Transformer"
    to: "Transformer"
    note: "Keep English"

# Load glossary from external file(s)
# Supports absolute path or relative to EXTEND.md location
# File format: markdown table with | from | to | note | columns,
# or YAML list of {from, to, note} entries
glossary_files:
  - ./my-glossary.md
  - /path/to/shared-glossary.yaml

# Language-pair specific glossaries
glossaries:
  en-zh:
    - from: "AI Agent"
      to: "AI 智能体"
  ja-zh:
    - from: "人工知能"
      to: "人工智能"

Fields

Glossary Entry

Glossary File Format

External glossary files (glossary_files) support two formats:

Markdown table (.md):

| from | to | note |
|------|----|------|
| Reinforcement Learning | 强化学习 | |
| Transformer | Transformer | Keep English |

YAML list (.yaml / .yml):

- from: "Reinforcement Learning"
  to: "强化学习"
- from: "Transformer"
  to: "Transformer"
  note: "Keep English"

Paths can be absolute or relative to the EXTEND.md file location.

Priority

1. CLI --glossary file entries 2. EXTEND.md glossaries[pair] entries 3. EXTEND.md glossary entries (inline) 4. EXTEND.md glossary_files entries (in listed order, later files override earlier) 5. Built-in glossary (e.g., references/glossary-en-zh.md)

Later entries override earlier ones for the same source term.

First-Time Setup

Overview

When no EXTEND.md is found, guide user through preference setup.

BLOCKING OPERATION: This setup MUST complete before ANY translation. Do NOT:

• Start translating content
• Ask about files or output paths
• Proceed to any workflow steps

ONLY ask the questions in this setup flow, save EXTEND.md, then continue.

Setup Flow

No EXTEND.md found
        |
        v
+---------------------+
| AskUserQuestion     |
| (all questions)     |
+---------------------+
        |
        v
+---------------------+
| Create EXTEND.md    |
+---------------------+
        |
        v
    Continue translation

Questions

Language: Use user's input language or saved language preference.

Use AskUserQuestion with ALL questions in ONE call:

Question 1: Target Language

header: "Target Language"
question: "Default target language?"
options:
  - label: "简体中文 zh-CN (Recommended)"
    description: "Translate to Simplified Chinese"
  - label: "繁體中文 zh-TW"
    description: "Translate to Traditional Chinese"
  - label: "English en"
    description: "Translate to English"
  - label: "日本語 ja"
    description: "Translate to Japanese"

Note: User may type a custom language code.

Question 2: Translation Mode

header: "Mode"
question: "Default translation mode?"
options:
  - label: "Normal (Recommended)"
    description: "Analyze content first, then translate"
  - label: "Quick"
    description: "Direct translation, no analysis"
  - label: "Refined"
    description: "Full workflow: analyze → translate → review → polish"

Question 3: Target Audience

header: "Audience"
question: "Default target audience?"
options:
  - label: "General readers (Recommended)"
    description: "Plain language, more translator's notes for jargon"
  - label: "Technical"
    description: "Developers/engineers, less annotation on tech terms"
  - label: "Academic"
    description: "Formal register, precise terminology"
  - label: "Business"
    description: "Business-friendly tone, explain tech concepts"

Note: User may type a custom audience description.

Question 4: Translation Style

header: "Style"
question: "Translation style?"
options:
  - label: "Storytelling (Recommended)"
    description: "Engaging narrative flow, smooth transitions"
  - label: "Formal"
    description: "Professional, structured, neutral tone"
  - label: "Technical"
    description: "Precise, documentation-style, concise"
  - label: "Literal"
    description: "Close to original structure"
  - label: "Academic"
    description: "Scholarly, rigorous, formal register"
  - label: "Business"
    description: "Concise, results-focused, action-oriented"
  - label: "Humorous"
    description: "Preserves humor, witty, playful"
  - label: "Conversational"
    description: "Casual, friendly, spoken-like"
  - label: "Elegant"
    description: "Literary, polished, aesthetically refined"

Note: User may type a custom style description.

Question 5: Save Location

header: "Save"
question: "Where to save preferences?"
options:
  - label: "User (Recommended)"
    description: "$HOME/.baoyu-skills/ (all projects)"
  - label: "Project"
    description: ".baoyu-skills/ (this project only)"

Save Locations

After Setup

1. Create directory if needed 2. Write EXTEND.md with selected values 3. Confirm: "Preferences saved to [path]" 4. Mention: "You can add custom glossary terms to EXTEND.md anytime. See the glossary section in the file for the format." 5. Continue with translation using saved preferences

EXTEND.md Template

target_language: [zh-CN/zh-TW/en/ja/...]
default_mode: [quick/normal/refined]
audience: [general/technical/academic/business/custom]
style: [storytelling/formal/technical/literal/academic/business/humorous/conversational/elegant]

# Custom glossary (optional) — add your own term translations here
# glossary:
#   - from: "Term"
#     to: "翻译"
#   - from: "Another Term"
#     to: "另一个翻译"
#     note: "Usage context"

Modifying Preferences Later

Users can edit EXTEND.md directly or delete it to trigger setup again.

English → Chinese Glossary

Terms where standard translation is non-obvious or easily mistranslated. Common terms with straightforward translations (e.g., Machine Learning → 机器学习) are omitted — the model already knows these.

Translation Workflow Details

This file provides detailed guidelines for each workflow step. Steps are shared across modes:

• Quick: Translate only (no steps from this file)
• Normal: Step 1 (Analysis) → Translate
• Refined: Step 1 (Analysis) → Step 2 (Draft) → Step 3 (Review) → Step 4 (Revision) → Step 5 (Polish)
• Normal → Upgrade: After normal mode, user can continue with Step 3 → Step 4 → Step 5

All intermediate results are saved as files in the output directory.

Step 1: Content Analysis

Before translating, analyze the source material. Save analysis to 01-analysis.md in the output directory.

1.1 Content Summary

• What is this content about? What is the core argument?
• Author background, stance, and writing context
• Purpose and intended audience of the original

1.2 Terminology

• List technical terms, proper nouns, brand names, acronyms
• Cross-reference with loaded glossaries
• For terms not in glossary, determine standard translations
• Record in a terminology table

1.3 Tone & Style

• Formal or conversational? Humor, metaphor, cultural references?
• What register is appropriate for the translation given the target audience?

1.4 Translation Challenges

Identify what may cause difficulty in translation:

• Comprehension gaps: Terms or references that target readers may not understand — note what explanation is needed
• Figurative language: Metaphors, idioms, expressions that don't translate literally — note intended meaning and target-language approach (interpret / substitute / retain)
• Structural challenges: Long complex sentences, wordplay, puns, or humor that needs creative adaptation

Save `01-analysis.md` with:

## Content Summary
[Core argument, author, context, purpose]

## Terminology
[term → translation, ...]

## Tone & Style
[assessment]

## Translation Challenges
- [term/passage] → [challenge type] → [suggested approach]
- ...

Step 2: Assemble Translation Prompt

Main agent reads 01-analysis.md and assembles a complete translation prompt using references/subagent-prompt-template.md. Inline the following from analysis:

• Target style: Resolved style preset + source voice assessment from §1.3
• Content background: Summary from §1.1
• Glossary: Merged glossary with analysis-extracted terms from §1.2
• Translation challenges: All challenges from §1.4

Save to 02-prompt.md. This prompt is used by the subagent (chunked) or by the main agent itself (non-chunked).

Step 3: Initial Draft

Save to 03-draft.md in the output directory.

For chunked content, the subagent produces this draft (merged from chunk translations). For non-chunked content, the main agent produces it directly.

Translate the full content following 02-prompt.md. Apply all Translation principles from SKILL.md.

Step 4: Critical Review

The main agent critically reviews the draft against the source. Save review findings to 04-critique.md. This step produces diagnosis only — no rewriting yet.

4.1 Accuracy

• Compare each paragraph against the original
• Verify facts, numbers, dates, proper nouns
• Flag content accidentally added, removed, or altered
• Check terminology consistency with glossary

4.2 Native Voice

• Flag sentences that read as "translated" rather than "written" — unnatural word order, calques, stiff phrasing
• For CJK targets: check for unnecessary connectives (因此/然而/此外), passive voice abuse (被/由/受到), noun pile-ups, over-nominalization
• Flag metaphors translated literally that sound unnatural in the target language
• Check emotional connotations are preserved, not flattened
• Note where sentence restructuring would improve readability

4.3 Notes & Adaptation

• Are translator's notes accurate, concise, and genuinely helpful?
• Flag missed comprehension challenges that need notes, and over-annotations on obvious terms
• Were translation strategies from 02-prompt.md followed?
• Do cultural references work in the target language?

Save `04-critique.md` with:

## Accuracy
- [issue]: [location] — [description]

## Native Voice
- [issue]: [example] → [suggested fix]

## Notes & Adaptation
- [add/remove/revise]: [term/passage] — [reason]

## Summary
[Overall assessment: X critical issues, Y improvements]

Step 5: Revision

Apply all findings from 04-critique.md to produce a revised translation. Save to 05-revision.md.

Read 03-draft.md and 04-critique.md, fix all accuracy issues, rewrite unnatural expressions, adjust notes, and improve flow.

Step 6: Polish

Save final version to translation.md.

Final pass on 05-revision.md for publication quality:

• Read the entire translation as a standalone piece — does it flow as native content?
• Smooth remaining rough transitions
• Ensure consistent narrative voice and style throughout
• Final terminology consistency check
• Verify formatting is preserved correctly

Subagent Responsibility

Each subagent (one per chunk) is responsible only for producing the initial draft of its chunk (Step 3). The main agent assembles the shared prompt (Step 2), spawns all subagents in parallel, then takes over for critical review (Step 4), revision (Step 5), and polish (Step 6).

Chunked Refined Translation

When content exceeds the chunk threshold and uses refined mode:

1. Main agent runs analysis (Step 1) on the entire document first → 01-analysis.md 2. Main agent assembles translation prompt → 02-prompt.md 3. Split into chunks → chunks/ 4. Spawn one subagent per chunk in parallel (each reads 02-prompt.md for shared context) → merge all results into 03-draft.md 5. Main agent critically reviews the merged draft → 04-critique.md 6. Main agent revises based on critique → 05-revision.md 7. Main agent polishes → translation.md 8. Final cross-chunk consistency check: terminology, narrative flow, transitions at chunk boundaries

Subagent Translation Prompt Template

Two parts: 1. `02-prompt.md` — Shared context (saved to output directory). Contains background, glossary, challenges, and principles. No task-specific instructions. 2. Subagent spawn prompt — Task instructions passed when spawning each subagent. One subagent per chunk (or per source file if non-chunked).

The main agent reads 01-analysis.md (if exists), inlines all relevant context into 02-prompt.md, then spawns subagents in parallel with task instructions referencing that file.

Replace {placeholders} with actual values. Omit sections marked "if analysis exists" for quick mode.

---

Part 1: 02-prompt.md (shared context, saved as file)

You are a professional translator. Your task is to translate markdown content from {source_lang} to {target_lang}.

## Target Audience & Style

**Audience**: {audience description}

**Target style**: {style description — e.g., "storytelling: engaging narrative flow, smooth transitions, vivid phrasing" or custom style from user}

**Source voice** (from analysis, if exists): {Brief description of the original author's voice — formal/conversational, humor, register, sentence rhythm.}

## Content Background

{Inlined from 01-analysis.md if analysis exists: content summary, core argument, author background, context.}

## Glossary

Apply these term translations consistently. First occurrence: include original in parentheses.

{Merged glossary — one per line: English → Translation}

## Translation Challenges

{Inlined from 01-analysis.md §1.4 if analysis exists. Comprehension gaps, figurative language, structural challenges with suggested approaches:}

- **{term/passage}**: {challenge type} → {suggested approach}

## Translation Principles

Rewrite the content into natural, engaging {target_lang} — not merely translate it. Every sentence should read as if a skilled native writer composed it from scratch.

- **Accuracy first**: Facts, data, and logic must match the original exactly
- **Natural flow**: Use idiomatic {target_lang} word order. Break long source sentences into shorter, natural ones. Interpret metaphors and idioms by intended meaning, not word-for-word
- **Terminology**: Use glossary translations consistently. Annotate with original in parentheses on first occurrence of specialized terms
- **Preserve format**: Keep all markdown formatting (headings, bold, italic, images, links, code blocks)
- **Proactive interpretation**: For jargon or concepts the target audience may lack context for, add concise explanations in **bold parentheses** `（**解释**）`. Keep annotations few — only where genuinely needed

---

Part 2: Subagent spawn prompt (passed as Agent tool prompt)

Chunked mode (one subagent per chunk, all spawned in parallel)

Read the translation instructions from: {output_dir}/02-prompt.md

You are translating chunk {NN} of {total_chunks}.
Context: {brief description of what this chunk covers and where it sits in the overall argument}

Translate this chunk:
1. Read `{output_dir}/chunks/chunk-{NN}.md`
2. Translate following the instructions in 02-prompt.md
3. Save translation to `{output_dir}/chunks/chunk-{NN}-draft.md`

Non-chunked mode

Read the translation instructions from: {output_dir}/02-prompt.md

Translate the source file and save the result:
1. Read `{source_file_path}`
2. Save translation to `{output_path}`

Workflow Mechanics

Details for source materialization, output directory creation, and conflict resolution.

Materialize Source

{slug}: 2-4 word kebab-case slug derived from content topic.

Create Output Directory

Create a subdirectory next to the source file: {source-dir}/{source-basename}-{target-lang}/

Examples:

• posts/article.md → posts/article-zh/
• translate/ai-future.md → translate/ai-future-zh/

Conflict Resolution

If the output directory already exists, rename the existing one to {name}.backup-YYYYMMDD-HHMMSS/ before creating the new one. Never overwrite existing results.