baoyu-translate

Translator

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

{baseDir} = this SKILL.md's directory. ${BUN_X} = bun if installed; else npx -y bun if npx available; else suggest installing bun. Replace {baseDir} and ${BUN_X} with actual values.

Preferences (EXTEND.md)

First one found wins:

• Found → read and apply. On first use in a session, remind briefly: "Using preferences from [path]. You can edit EXTEND.md to customize glossary, audience, etc."
• Not found → BLOCKING first-time setup before any translation; never silently use defaults. Ask all questions in references/config/first-time-setup.md (target language, mode, audience, style, save location) in ONE call, write EXTEND.md at the chosen location, confirm "Preferences saved to [path]", then continue.

Supports: target language, mode, audience, glossaries (inline or file path), style, chunk settings. Schema: references/config/extend-schema.md.

Defaults

EXTEND.md overrides defaults; CLI flags override EXTEND.md.

Modes

Auto-detection: "快翻", "quick", "直接翻译" → quick; "精翻", "refined", "publication quality", "proofread" → refined; otherwise the default mode.

Style presets (voice and tone, independent of audience; custom descriptions accepted, e.g. --style "poetic and lyrical"):

Audience presets (custom descriptions accepted, e.g. --audience "AI感兴趣的普通读者"):

Workflow

Step 1: Load Preferences

1. Check EXTEND.md (see Preferences)
2. Load the built-in glossary for the language pair if available — EN→ZH: references/glossary-en-zh.md
3. Merge glossaries: EXTEND.md glossary (inline) + glossary_files (paths relative to EXTEND.md) + built-in + --glossary file (CLI overrides all)

Step 2: Materialize Source & Create Output Directory

Materialize the source (file as-is; inline text/URL → translate/{slug}.md), then create {source-dir}/{source-basename}-{target-lang}/. Detect source language if --from is not given. Details and conflict handling: references/workflow-mechanics.md.

All intermediate and final files go in the output directory:

Step 3: Assess Content Length

Quick mode never chunks. If content exceeds the chunk threshold, 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." Proceed if the user doesn't switch.

Normal/refined: below threshold → translate as a single unit; at or above → chunked translation (3.1).

3.1 Long Content Preparation (normal/refined, ≥ threshold)

1. Extract terminology across the whole document (proper nouns, technical terms, recurring phrases)
2. Build session glossary: merge extracted terms with loaded glossaries, fix consistent translations
3. Split: ${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words <chunk_max_words>] [--output-dir <output-dir>] — splits at markdown block boundaries (headings, paragraphs, lists, code blocks, tables, etc.); an oversized single block falls back to line, then word splitting
4. Assemble prompt: read 01-analysis.md (if it exists) and build shared context with Part 1 of references/subagent-prompt-template.md, inlining target style, content background, merged glossary, and translation challenges. Save as 02-prompt.md (shared context only, no task instructions)
5. Draft via subagents (if an Agent tool is available):
   • One subagent per chunk, all in parallel (Part 2 of the template). Each reads 02-prompt.md, gets its position (chunk N of M + brief context of where it sits in the argument), and saves chunks/chunk-NN-draft.md
   • Consistency comes from the shared 02-prompt.md (glossary, figurative language mapping, comprehension challenges, source voice, translation challenges)
   • No chunks (under threshold): one subagent for the whole source file
   • No Agent tool: translate chunks sequentially inline using 02-prompt.md
6. Merge chunks in order after all subagents finish; prepend chunks/frontmatter.md if it exists. Save as 03-draft.md (refined) or translation.md (normal)
7. Keep all intermediate files in chunks/

After merging, the main agent takes over for review, revision, and polish (Step 4).

Step 4: Translate & Refine

Translation principles (all modes):

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

Quick: translate directly → translation.md.

Normal:

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

Then tell the user: "Translation saved. To further review and polish, reply 继续润色 or refine." If they do, run refined Steps 4-6 on the existing output: rename current translation.md to 03-draft.md, then write 04-critique.md, 05-revision.md, and an updated translation.md.

Refined — per-step guidelines in references/refined-workflow.md. Each step reads the previous step's file:

1. Analyze → 01-analysis.md
2. Assemble prompt → 02-prompt.md (instructions with inlined context)
3. Draft → 03-draft.md (with translator's notes; from subagents 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)
6. Polish → translation.md (publication quality)

Subagents (Step 3.1) only produce the initial draft. Review, revision, and polish belong to the main agent, which may delegate to subagents at its discretion.

Step 5: Output

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

Then run a lightweight image-language pass: collect image references, identify likely text-heavy ones (covers, screenshots, diagrams, charts, frameworks, infographics), and list any whose main text language likely differs from the translated article. List only — do not localize images unless the user asks. Use the article's own image syntax (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

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 candidates were found, append after the summary a short note that some embedded images may still need image-text localization, followed by the list.

Extension Support

Custom configurations via EXTEND.md — see Preferences above.