mirror of
https://github.com/JimLiu/baoyu-skills.git
synced 2026-07-30 21:59:47 +08:00
feat(baoyu-translate): add three-mode translation skill with glossary support
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jim Liu 宝玉
@@ -0,0 +1,73 @@
|
||||
# EXTEND.md Schema for baoyu-translate
|
||||
|
||||
## Format
|
||||
|
||||
EXTEND.md uses YAML format:
|
||||
|
||||
```yaml
|
||||
# Default target language (ISO code or common name)
|
||||
target_language: zh-CN
|
||||
|
||||
# Default translation mode
|
||||
default_mode: normal # quick | normal | refined
|
||||
|
||||
# Target audience (affects annotation depth and register)
|
||||
audience: general # general | technical | academic | business | or custom string
|
||||
|
||||
# Translation style preference
|
||||
style: storytelling # storytelling | formal | technical | literal
|
||||
|
||||
# Word count threshold to trigger chunked translation
|
||||
chunk_threshold: 4000
|
||||
|
||||
# Max words per chunk
|
||||
chunk_max_words: 5000
|
||||
|
||||
# Custom glossary (merged with built-in glossary)
|
||||
# CLI --glossary flag overrides these
|
||||
glossary:
|
||||
- from: "Reinforcement Learning"
|
||||
to: "强化学习"
|
||||
- from: "Transformer"
|
||||
to: "Transformer"
|
||||
note: "Keep English"
|
||||
|
||||
# Language-pair specific glossaries
|
||||
glossaries:
|
||||
en-zh:
|
||||
- from: "AI Agent"
|
||||
to: "AI 智能体"
|
||||
ja-zh:
|
||||
- from: "人工知能"
|
||||
to: "人工智能"
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `target_language` | string | `zh-CN` | Default target language code |
|
||||
| `default_mode` | string | `normal` | Default translation mode (`quick` / `normal` / `refined`) |
|
||||
| `audience` | string | `general` | Target reader profile (`general` / `technical` / `academic` / `business` / custom) |
|
||||
| `style` | string | `storytelling` | Translation style preference |
|
||||
| `chunk_threshold` | number | `4000` | Word count threshold to trigger chunked translation |
|
||||
| `chunk_max_words` | number | `5000` | Max words per chunk |
|
||||
| `glossary` | array | `[]` | Universal glossary entries |
|
||||
| `glossaries` | object | `{}` | Language-pair specific glossary entries |
|
||||
|
||||
## Glossary Entry
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `from` | yes | Source term |
|
||||
| `to` | yes | Target translation |
|
||||
| `note` | no | Usage note (e.g., "Keep English", "Only in tech context") |
|
||||
|
||||
## Priority
|
||||
|
||||
1. CLI `--glossary` file entries
|
||||
2. EXTEND.md `glossaries[pair]` entries
|
||||
3. EXTEND.md `glossary` entries
|
||||
4. Built-in glossary (e.g., `references/glossary-en-zh.md`)
|
||||
|
||||
Later entries override earlier ones for the same source term.
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
name: first-time-setup
|
||||
description: First-time setup flow for baoyu-translate preferences
|
||||
---
|
||||
|
||||
# First-Time Setup
|
||||
|
||||
## Overview
|
||||
|
||||
When no EXTEND.md is found, guide user through preference setup.
|
||||
|
||||
**BLOCKING OPERATION**: This setup MUST complete before ANY translation. Do NOT:
|
||||
- Start translating content
|
||||
- Ask about files or output paths
|
||||
- Proceed to any workflow steps
|
||||
|
||||
ONLY ask the questions in this setup flow, save EXTEND.md, then continue.
|
||||
|
||||
## Setup Flow
|
||||
|
||||
```
|
||||
No EXTEND.md found
|
||||
|
|
||||
v
|
||||
+---------------------+
|
||||
| AskUserQuestion |
|
||||
| (all questions) |
|
||||
+---------------------+
|
||||
|
|
||||
v
|
||||
+---------------------+
|
||||
| Create EXTEND.md |
|
||||
+---------------------+
|
||||
|
|
||||
v
|
||||
Continue translation
|
||||
```
|
||||
|
||||
## Questions
|
||||
|
||||
**Language**: Use user's input language or saved language preference.
|
||||
|
||||
Use AskUserQuestion with ALL questions in ONE call:
|
||||
|
||||
### Question 1: Target Language
|
||||
|
||||
```yaml
|
||||
header: "Target Language"
|
||||
question: "Default target language?"
|
||||
options:
|
||||
- label: "简体中文 zh-CN (Recommended)"
|
||||
description: "Translate to Simplified Chinese"
|
||||
- label: "繁體中文 zh-TW"
|
||||
description: "Translate to Traditional Chinese"
|
||||
- label: "English en"
|
||||
description: "Translate to English"
|
||||
- label: "日本語 ja"
|
||||
description: "Translate to Japanese"
|
||||
```
|
||||
|
||||
Note: User may type a custom language code.
|
||||
|
||||
### Question 2: Translation Mode
|
||||
|
||||
```yaml
|
||||
header: "Mode"
|
||||
question: "Default translation mode?"
|
||||
options:
|
||||
- label: "Normal (Recommended)"
|
||||
description: "Analyze content first, then translate"
|
||||
- label: "Quick"
|
||||
description: "Direct translation, no analysis"
|
||||
- label: "Refined"
|
||||
description: "Full workflow: analyze → translate → review → polish"
|
||||
```
|
||||
|
||||
### Question 3: Target Audience
|
||||
|
||||
```yaml
|
||||
header: "Audience"
|
||||
question: "Default target audience?"
|
||||
options:
|
||||
- label: "General readers (Recommended)"
|
||||
description: "Plain language, more translator's notes for jargon"
|
||||
- label: "Technical"
|
||||
description: "Developers/engineers, less annotation on tech terms"
|
||||
- label: "Academic"
|
||||
description: "Formal register, precise terminology"
|
||||
- label: "Business"
|
||||
description: "Business-friendly tone, explain tech concepts"
|
||||
```
|
||||
|
||||
Note: User may type a custom audience description.
|
||||
|
||||
### Question 4: Translation Style
|
||||
|
||||
```yaml
|
||||
header: "Style"
|
||||
question: "Translation style?"
|
||||
options:
|
||||
- label: "Storytelling (Recommended)"
|
||||
description: "Engaging, narrative-like flow"
|
||||
- label: "Formal"
|
||||
description: "Professional, structured"
|
||||
- label: "Technical"
|
||||
description: "Precise, documentation-style"
|
||||
- label: "Literal"
|
||||
description: "Close to original structure"
|
||||
```
|
||||
|
||||
### Question 5: Save Location
|
||||
|
||||
```yaml
|
||||
header: "Save"
|
||||
question: "Where to save preferences?"
|
||||
options:
|
||||
- label: "User (Recommended)"
|
||||
description: "$HOME/.baoyu-skills/ (all projects)"
|
||||
- label: "Project"
|
||||
description: ".baoyu-skills/ (this project only)"
|
||||
```
|
||||
|
||||
## Save Locations
|
||||
|
||||
| Choice | Path | Scope |
|
||||
|--------|------|-------|
|
||||
| User | `$HOME/.baoyu-skills/baoyu-translate/EXTEND.md` | All projects |
|
||||
| Project | `.baoyu-skills/baoyu-translate/EXTEND.md` | Current project |
|
||||
|
||||
## After Setup
|
||||
|
||||
1. Create directory if needed
|
||||
2. Write EXTEND.md with selected values
|
||||
3. Confirm: "Preferences saved to [path]"
|
||||
4. Mention: "You can add custom glossary terms to EXTEND.md anytime. See the `glossary` section in the file for the format."
|
||||
5. Continue with translation using saved preferences
|
||||
|
||||
## EXTEND.md Template
|
||||
|
||||
```yaml
|
||||
target_language: [zh-CN/zh-TW/en/ja/...]
|
||||
default_mode: [quick/normal/refined]
|
||||
audience: [general/technical/academic/business/custom]
|
||||
style: [storytelling/formal/technical/literal]
|
||||
|
||||
# Custom glossary (optional) — add your own term translations here
|
||||
# glossary:
|
||||
# - from: "Term"
|
||||
# to: "翻译"
|
||||
# - from: "Another Term"
|
||||
# to: "另一个翻译"
|
||||
# note: "Usage context"
|
||||
```
|
||||
|
||||
## Modifying Preferences Later
|
||||
|
||||
Users can edit EXTEND.md directly or delete it to trigger setup again.
|
||||
@@ -0,0 +1,21 @@
|
||||
# English → Chinese Glossary
|
||||
|
||||
Terms where standard translation is non-obvious or easily mistranslated. Common terms with straightforward translations (e.g., Machine Learning → 机器学习) are omitted — the model already knows these.
|
||||
|
||||
| English | Chinese | Notes |
|
||||
|---------|---------|-------|
|
||||
| AI Agent | AI 智能体 | |
|
||||
| Vibe Coding | 凭感觉编程 | |
|
||||
| the Bitter Lesson | 苦涩的教训 | Rich Sutton's essay |
|
||||
| Context Engineering | 上下文工程 | |
|
||||
| AI Wrapper | AI 套壳 | |
|
||||
| RLHF | 基于人类反馈的强化学习 | |
|
||||
| Hallucination | 幻觉 | AI-specific meaning |
|
||||
| Alignment | 对齐 | AI safety context |
|
||||
| Guardrails | 护栏 | AI safety context |
|
||||
| Agentic | 智能体化的 | |
|
||||
| Grounding | 基础化/落地 | Context-dependent |
|
||||
| Embedding | 嵌入/向量化 | Context-dependent |
|
||||
| Moat | 护城河 | Business context |
|
||||
| Flywheel | 飞轮效应 | |
|
||||
| Boilerplate | 样板代码 | |
|
||||
@@ -0,0 +1,186 @@
|
||||
# Translation Workflow Details
|
||||
|
||||
This file provides detailed guidelines for each workflow step. Steps are shared across modes:
|
||||
|
||||
- **Quick**: Translate only (no steps from this file)
|
||||
- **Normal**: Step 1 (Analysis) → Translate
|
||||
- **Refined**: Step 1 (Analysis) → Step 2 (Draft) → Step 3 (Review) → Step 4 (Polish)
|
||||
- **Normal → Upgrade**: After normal mode, user can continue with Step 3 → Step 4
|
||||
|
||||
All intermediate results are saved as files in the output directory.
|
||||
|
||||
## Step 1: Content Analysis
|
||||
|
||||
Before translating, deeply analyze the source material. Save analysis to `01-analysis.md` in the output directory. Focus on dimensions that directly inform translation quality.
|
||||
|
||||
### 1.1 Quick Summary
|
||||
|
||||
3-5 sentences capturing:
|
||||
- What is this content about?
|
||||
- What is the core argument?
|
||||
- What is the most valuable point?
|
||||
|
||||
### 1.2 Core Content
|
||||
|
||||
- **Core argument**: One sentence summary
|
||||
- **Key concepts**: What key concepts does the author use? How are they defined?
|
||||
- **Structure**: How is the argument developed? How do sections connect?
|
||||
- **Evidence**: What specific examples, data, or authoritative citations are used?
|
||||
|
||||
### 1.3 Background Context
|
||||
|
||||
- **Author**: Who is the author? What is their background and stance?
|
||||
- **Writing context**: What phenomenon, trend, or debate is this responding to?
|
||||
- **Purpose**: What problem is the author trying to solve? Who are they trying to influence?
|
||||
- **Implicit assumptions**: What unstated premises underlie the argument?
|
||||
|
||||
### 1.4 Terminology Extraction
|
||||
|
||||
- List all technical terms, proper nouns, brand names, acronyms
|
||||
- Cross-reference with loaded glossaries
|
||||
- For terms not in glossary, research standard translations
|
||||
- Record decisions in a working terminology table
|
||||
|
||||
### 1.5 Tone & Style
|
||||
|
||||
- Is the original formal or conversational?
|
||||
- Does it use humor, metaphor, or cultural references?
|
||||
- What register is appropriate for the translation given the target audience?
|
||||
|
||||
### 1.6 Reader Comprehension Challenges
|
||||
|
||||
Identify points where target readers may struggle, calibrated to the target audience:
|
||||
|
||||
- **Domain jargon**: Technical terms that lack widely-known translations or are meaningless when translated literally
|
||||
- **Cultural references**: Idioms, historical events, pop culture, social norms specific to the source culture
|
||||
- **Implicit knowledge**: Background context the original author assumes but target readers may lack
|
||||
- **Wordplay & metaphors**: Figurative language that doesn't carry over across languages
|
||||
- **Named concepts**: Theories, effects, or phenomena with coined names (e.g., "comb-over effect", "Dunning-Kruger effect")
|
||||
- **Cognitive gaps**: Counterintuitive claims or expectations vs. reality that need framing for target readers
|
||||
|
||||
For each identified challenge, note:
|
||||
1. The original term/passage
|
||||
2. Why it may confuse target readers
|
||||
3. A concise plain-language explanation to use as a translator's note
|
||||
|
||||
### 1.7 Translation Challenges
|
||||
|
||||
- Structural challenges (wordplay, ambiguity, puns that don't translate)
|
||||
- Passages where literal translation would lose meaning
|
||||
- Content where the author's voice or humor requires creative adaptation
|
||||
|
||||
**Save `01-analysis.md`** with:
|
||||
```
|
||||
## Quick Summary
|
||||
[3-5 sentences]
|
||||
|
||||
## Core Content
|
||||
Core argument: [one sentence]
|
||||
Key concepts: [list]
|
||||
Structure: [outline]
|
||||
|
||||
## Background Context
|
||||
Author: [who, background, stance]
|
||||
Writing context: [what this responds to]
|
||||
Purpose: [goal and target audience]
|
||||
Implicit assumptions: [unstated premises]
|
||||
|
||||
## Terminology
|
||||
[term → translation, ...]
|
||||
|
||||
## Tone & Style
|
||||
[assessment]
|
||||
|
||||
## Comprehension Challenges
|
||||
- [term/passage] → [why confusing] → [proposed note]
|
||||
- ...
|
||||
|
||||
## Translation Challenges
|
||||
[structural issues, creative adaptation needs]
|
||||
```
|
||||
|
||||
## Step 2: Assemble Translation Prompt
|
||||
|
||||
Main agent reads `01-analysis.md` and assembles a complete translation prompt using [references/subagent-prompt-template.md](subagent-prompt-template.md). Inline content background, merged glossary, and comprehension challenges into the prompt. Save to `02-prompt.md`.
|
||||
|
||||
This prompt is used by the subagent (chunked) or by the main agent itself (non-chunked).
|
||||
|
||||
## Step 3: Initial Draft
|
||||
|
||||
Save to `03-draft.md` in the output directory.
|
||||
|
||||
For chunked content, the subagent produces this draft (merged from chunk translations). For non-chunked content, the main agent produces it directly.
|
||||
|
||||
Translate the full content following `02-prompt.md`:
|
||||
|
||||
- Use the terminology decisions from Step 1 consistently
|
||||
- Match the identified tone and register
|
||||
- Break complex sentences into natural target-language patterns
|
||||
- Preserve all formatting and structure
|
||||
- First occurrence of technical terms: translated term (original in parentheses)
|
||||
- Add translator's notes for comprehension challenges identified in Step 1: use parentheses with a plain-language explanation, e.g., `译文（English original，通俗解释）`
|
||||
- Only annotate where genuinely needed — do not over-explain obvious terms
|
||||
|
||||
## Step 4: Review
|
||||
|
||||
The main agent reviews the draft. Save reviewed version to `04-review.md`.
|
||||
|
||||
Systematically review against these criteria:
|
||||
|
||||
### Accuracy Check
|
||||
- Compare each paragraph against the original
|
||||
- Verify all facts, numbers, dates, and proper nouns
|
||||
- Ensure no content was accidentally added, removed, or altered
|
||||
- Check that technical terms match glossary consistently throughout
|
||||
|
||||
### Naturalness Check
|
||||
- Read the translation as if it were original content (not a translation)
|
||||
- Flag sentences that sound like "translationese" — awkward word order, calques, unnatural phrasing
|
||||
- Check paragraph transitions and logical flow
|
||||
- Verify sentence length feels natural for target language
|
||||
|
||||
### Terminology Consistency
|
||||
- Verify each glossary term is translated the same way throughout
|
||||
- Check proper nouns are handled consistently (transliterated vs. kept in original)
|
||||
- Verify annotations appear on first occurrence only
|
||||
|
||||
### Cultural Adaptation & Translator's Notes
|
||||
- Are cultural references explained where needed?
|
||||
- Do metaphors and idioms work in the target language?
|
||||
- Are any references potentially confusing or offensive in the target culture?
|
||||
- Check translator's notes: are they accurate, concise, and genuinely helpful?
|
||||
- Identify any missed comprehension challenges that should have notes
|
||||
- Remove over-annotations on terms that are obvious to the target audience
|
||||
|
||||
## Step 5: Polish
|
||||
|
||||
Save final version to `translation.md`.
|
||||
|
||||
Final pass addressing all issues from the review:
|
||||
|
||||
- Fix all accuracy issues found in review
|
||||
- Rewrite unnatural sentences for fluency
|
||||
- Improve transitions between paragraphs
|
||||
- Ensure the translation reads as engaging, native-quality content
|
||||
- Verify formatting is preserved correctly
|
||||
- For storytelling-style content: ensure the narrative flow draws readers in
|
||||
- Final consistency check on terminology
|
||||
|
||||
## Subagent Responsibility
|
||||
|
||||
Each subagent (one per chunk) is responsible **only** for producing the initial draft of its chunk (Step 3). The main agent assembles the shared prompt (Step 2), spawns all subagents in parallel, then takes over for review (Step 4) and polish (Step 5). The main agent may delegate review or polish to subagents at its own discretion.
|
||||
|
||||
## Chunked Refined Translation
|
||||
|
||||
When content exceeds the chunk threshold (see Defaults in SKILL.md) and uses refined mode:
|
||||
|
||||
1. Main agent runs analysis (Step 1) on the **entire** document first → `01-analysis.md`
|
||||
2. Main agent assembles translation prompt → `02-prompt.md`
|
||||
3. Split into chunks → `chunks/`
|
||||
4. Spawn one subagent per chunk in parallel (each reads `02-prompt.md` for shared context) → merge all results into `03-draft.md`
|
||||
5. Main agent reviews the merged draft → `04-review.md`
|
||||
6. Main agent polishes → `translation.md`
|
||||
7. Final cross-chunk consistency check:
|
||||
- Check terminology consistency across chunk boundaries
|
||||
- Verify narrative flow between chunks
|
||||
- Fix any transition issues at chunk boundaries
|
||||
@@ -0,0 +1,71 @@
|
||||
# Subagent Translation Prompt Template
|
||||
|
||||
Two parts:
|
||||
1. **`02-prompt.md`** — Shared context (saved to output directory). Contains background, glossary, challenges, and principles. No task-specific instructions.
|
||||
2. **Subagent spawn prompt** — Task instructions passed when spawning each subagent. One subagent per chunk (or per source file if non-chunked).
|
||||
|
||||
The main agent reads `01-analysis.md` (if exists), inlines all relevant context into `02-prompt.md`, then spawns subagents in parallel with task instructions referencing that file.
|
||||
|
||||
Replace `{placeholders}` with actual values. Omit sections marked "if analysis exists" for quick mode.
|
||||
|
||||
---
|
||||
|
||||
## Part 1: `02-prompt.md` (shared context, saved as file)
|
||||
|
||||
```markdown
|
||||
You are a professional translator. Your task is to translate markdown content from {source_lang} to {target_lang}.
|
||||
|
||||
## Target Audience
|
||||
|
||||
{audience description}
|
||||
|
||||
## Content Background
|
||||
|
||||
{Inlined from 01-analysis.md if analysis exists: quick summary, core argument, author background, writing context, tone assessment.}
|
||||
|
||||
## Glossary
|
||||
|
||||
Apply these term translations consistently throughout. First occurrence of each term: include the original in parentheses after the translation.
|
||||
|
||||
{Merged glossary — combine built-in glossary + EXTEND.md glossary + terms extracted in analysis. One per line: English → Translation}
|
||||
|
||||
## Comprehension Challenges
|
||||
|
||||
The following terms or references may confuse target readers. Add translator's notes in parentheses where they appear: `译文（English original，通俗解释）`
|
||||
|
||||
{Inlined from 01-analysis.md comprehension challenges section if analysis exists. Each entry: term → explanation to use as note.}
|
||||
|
||||
## Translation Principles
|
||||
|
||||
- **Accuracy first**: Facts, data, and logic must match the original exactly
|
||||
- **Natural flow**: Use idiomatic {target_lang} word order; break long sentences into shorter ones
|
||||
- **Terminology**: Use glossary translations consistently; 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 or cultural references listed in Comprehension Challenges above, add a concise explanatory note in parentheses. Only annotate where genuinely needed for the target audience.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Subagent spawn prompt (passed as Agent tool prompt)
|
||||
|
||||
### Chunked mode (one subagent per chunk, all spawned in parallel)
|
||||
|
||||
```
|
||||
Read the translation instructions from: {output_dir}/02-prompt.md
|
||||
|
||||
Translate this chunk:
|
||||
1. Read `{output_dir}/chunks/chunk-{NN}.md`
|
||||
2. Translate following the instructions in 02-prompt.md
|
||||
3. Save translation to `{output_dir}/chunks/chunk-{NN}-draft.md`
|
||||
```
|
||||
|
||||
### Non-chunked mode
|
||||
|
||||
```
|
||||
Read the translation instructions from: {output_dir}/02-prompt.md
|
||||
|
||||
Translate the source file and save the result:
|
||||
1. Read `{source_file_path}`
|
||||
2. Save translation to `{output_path}`
|
||||
```
|
||||
Reference in New Issue
Block a user