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):
- Prefer built-in user-input tools exposed by the current agent runtime — e.g.,
AskUserQuestion,request_user_input,clarify,ask_user, or any equivalent. - 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.
- 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.
| Script | Purpose | |--------|---------| | scripts/main.ts | CLI entry point. Default action splits markdown into chunks; also supports explicit chunk subcommand | | scripts/chunk.ts | Markdown chunking implementation used by main.ts and kept compatible for direct invocation |
Preferences (EXTEND.md)
Check EXTEND.md in priority order — the first one found wins:
| Priority | Path | Scope | |----------|------|-------| | 1 | .baoyu-skills/baoyu-translate/EXTEND.md | Project | | 2 | ${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md | XDG | | 3 | $HOME/.baoyu-skills/baoyu-translate/EXTEND.md | User home |
| Result | Action | |--------|--------| | Found | Read, parse, apply. On first use in session, briefly remind: "Using preferences from [path]. You can edit EXTEND.md to customize glossary, audience, etc." | | Not found | MUST run first-time setup (see below) — do NOT silently use defaults |
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](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](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.
| Setting | Default | EXTEND.md key | CLI flag | Description | |---------|---------|---------------|----------|-------------| | Target language | zh-CN | target_language | --to | Translation target language | | Mode | normal | default_mode | --mode | Translation mode | | Audience | general | audience | --audience | Target reader profile | | Style | storytelling | style | --style | Translation style preference | | Chunk threshold | 4000 | chunk_threshold | — | Word count to trigger chunked translation | | Chunk max words | 5000 | chunk_max_words | — | Max words per chunk |
Modes
| Mode | Flag | Steps | When to Use | |------|------|-------|-------------| | Quick | --mode quick | Translate | Short texts, informal content, quick tasks | | Normal | --mode normal (default) | Analyze → Translate | Articles, blog posts, general content | | Refined | --mode refined | Analyze → Translate → Review → Polish | Publication-quality, important documents |
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):
| Value | Description | Effect | |-------|-------------|--------| | storytelling | Engaging narrative flow (default) | Draws readers in, smooth transitions, vivid phrasing | | formal | Professional, structured | Neutral tone, clear organization, no colloquialisms | | technical | Precise, documentation-style | Concise, terminology-heavy, minimal embellishment | | literal | Close to original structure | Minimal restructuring, preserves source sentence patterns | | academic | Scholarly, rigorous | Formal register, complex clauses OK, citation-aware | | business | Concise, results-focused | Action-oriented, executive-friendly, bullet-point mindset | | humorous | Preserves and adapts humor | Witty, playful, recreates comedic effect in target language | | conversational | Casual, spoken-like | Friendly, approachable, as if explaining to a friend | | elegant | Literary, polished prose | Aesthetically refined, rhythmic, carefully crafted word choices |
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:
| Value | Description | Effect | |-------|-------------|--------| | general | General readers (default) | Plain language, more translator's notes for jargon | | technical | Developers / engineers | Less annotation on common tech terms | | academic | Researchers / scholars | Formal register, precise terminology | | business | Business professionals | Business-friendly tone, explain tech concepts |
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](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](references/workflow-mechanics.md)
Output directory contents (all intermediate and final files go here):
| File | Mode | Description | |------|------|-------------| | translation.md | All | Final translation (always this name) | | 01-analysis.md | Normal, Refined | Content analysis (domain, tone, terminology) | | 02-prompt.md | Normal, Refined | Assembled translation prompt | | 03-draft.md | Refined | Initial draft before review | | 04-critique.md | Refined | Critical review findings (diagnosis only) | | 05-revision.md | Refined | Revised translation based on critique | | chunks/ | Chunked | Source chunks + translated chunks |
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'