Translator

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

Script Directory

Scripts in

scripts/

subdirectory.

${SKILL_DIR}

= 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

${SKILL_DIR}

and

${BUN_X}

with actual values.

Script	Purpose
`scripts/chunk.ts`	Split markdown into chunks by AST blocks (sections, headings, paragraphs), with line/word fallback for oversized blocks

Preferences (EXTEND.md)

Check EXTEND.md existence (priority order):

bash

# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-translate/EXTEND.md && echo "project"
test -f "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md" && echo "user"

powershell

# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-translate/EXTEND.md) { "project" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md") { "user" }

Path	Location
`.baoyu-skills/baoyu-translate/EXTEND.md`	Project directory
`$HOME/.baoyu-skills/baoyu-translate/EXTEND.md`	User home

Result	Action
Found	Read, parse, apply settings. 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

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`	—	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).

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 3-4) on the existing output.

Usage

/translate [--mode quick|normal|refined] [--from <lang>] [--to <lang>] [--audience <audience>] [--glossary <file>] <source>

```
<source>
```
: File path, URL, or inline text
```
--from
```
: Source language (auto-detect if omitted)
```
--to
```
: Target language (from EXTEND.md or default
```
zh-CN
```
)
```
--audience
```
: Target reader profile (from EXTEND.md or default
```
general
```
)
```
--glossary
```
: Additional glossary file to merge with EXTEND.md glossary

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 + built-in glossary +

--glossary

file (CLI overrides all)

Step 2: Materialize Source & Create Output Directory

If the input is not a file, save it as one first. Then create an output subdirectory next to the source file.

2.1 Materialize source

Input Type	Action
File	Use as-is (no copy needed)
Inline text	Save to `translate/{slug}.md`
URL	Fetch content, save to `translate/{slug}.md`

{slug}

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

2.2 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.

2.3 Output directory contents

All intermediate and final files go into this directory:

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 (used by subagent or inline)
`03-draft.md`	Refined	Initial draft before review
`04-review.md`	Refined	Reviewed version with fixes
`chunks/`	Chunked	Source chunks + translated chunks
`chunks/chunk-01.md`	Chunked	Source chunk
`chunks/chunk-01-draft.md`	Chunked	Translated chunk

Detect source language if

--from

not specified.

Step 3: Assess Content Length

Quick mode does not chunk — translate directly regardless of length. If content exceeds model context limits, suggest the user switch to normal or refined mode.

For normal and refined modes:

Content	Action
< chunk threshold	Translate as single unit
>= chunk threshold	Chunk translation (see Step 3.1)

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

Before translating chunks:

Extract terminology: Scan entire document for proper nouns, technical terms, recurring phrases
Build session glossary: Merge extracted terms with loaded glossaries, establish consistent translations
Split into chunks: Use
```
${BUN_X} ${SKILL_DIR}/scripts/chunk.ts <file> [--max-words <chunk_max_words>]
```
- Parses markdown AST (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
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 content background, merged glossary, and comprehension challenges
- Save as
```
02-prompt.md
```
  in the output directory (shared context only, no task instructions)
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, translates its chunk, saves to
```
chunks/chunk-NN-draft.md
```
- Terminology consistency is guaranteed by the shared
```
02-prompt.md
```
  (glossary + comprehension 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
```
Merge: Once all subagents complete, combine translated chunks in order, prepend frontmatter if present → save as
```
03-draft.md
```
(refined) or
```
translation.md
```
(normal)
All intermediate files (source chunks + translated chunks) are preserved in
```
chunks/
```

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

Step 4: Translate & Refine

Translation principles (apply to all modes):

Accuracy first: Facts, data, and logic must match the original exactly
Natural flow: Use idiomatic target language word order; break long sentences into shorter ones
Terminology: Use standard translations; annotate with original term in parentheses on first occurrence
Preserve format: Keep all markdown formatting (headings, bold, italic, images, links, code blocks)
Respect original: Maintain original structure and meaning; do not add, remove, or editorialize
Translator's notes: For terms, concepts, or cultural references that target readers may not understand — due to jargon, cultural gaps, or domain-specific knowledge — add a concise explanatory note in parentheses immediately after the term. The note should explain what it means in plain language, not just provide the English original. Format:
```
译文（English original，通俗解释）
```
. Calibrate annotation depth to the target audience: general readers need more notes than technical readers. Only add notes where genuinely needed; do not over-annotate obvious terms.

Quick Mode

Translate directly → save to

translation.md

Normal Mode

Analyze →
```
01-analysis.md
```
(domain, tone, audience, terminology, reader comprehension challenges)
Assemble prompt →
```
02-prompt.md
```
(translation instructions with inlined context)
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 review → polish (same as refined mode Steps 3-4 below), saving

03-draft.md

(rename current

translation.md

04-review.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 are handled by the main agent, which may delegate to subagents at its discretion.

Steps and saved files (all in output directory):

Analyze →
```
01-analysis.md
```
(domain, tone, terminology, reader comprehension challenges)
Assemble prompt →
```
02-prompt.md
```
(translation instructions with inlined context)
Draft →
```
03-draft.md
```
(initial translation with translator's notes; from subagent if chunked)
Review →
```
04-review.md
```
(accuracy, naturalness, terminology fixes)
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.

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}

Extension Support

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

baoyu-translate

NPX Install

Tags

SKILL.md Content