baoyu-translate

Files (11)

• SKILL.md
• extend-schema.md · references/config/
• first-time-setup.md · references/config/
• glossary-en-zh.md · references/
• refined-workflow.md · references/
• subagent-prompt-template.md · references/
• workflow-mechanics.md · references/
• bun.lock · scripts/
• chunk.ts · scripts/
• main.ts · scripts/
• package.json · scripts/

SKILL.md (first lines)

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

| 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)

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 |

- **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](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](references/config/extend-schema.md).

## Defaults

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

| Setting | Default | EXTEND.md key | CLI flag |
|---------|---------|---------------|----------|
| Target language | `zh-CN` | `target_language` | `--to` |
| Mode | `normal` | `default_mode` | `--mode` |
| Audience | `general` | `audience` | `--audience` |
| Style | `storytelling` | `style` | `--style` |
| Chunk threshold (words, triggers chunking) | `4000` | `chunk_threshold` | — |
| Chunk max words | `5000` | `chunk_max_words` | — |

## 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 |

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"`):

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

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

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

## 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](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](references/workflow-mechanics.md).

All intermediate and final files go in the output 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 |
| `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 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](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):

From guanyang/open-agent-hub, MIT.

More from guanyang/open-agent-hub