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.
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.
| 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
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):
| 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'