baoyu-translate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

脚本存放于

scripts/

子目录中。

${SKILL_DIR}

= 本 SKILL.md 文件的目录路径。解析

${BUN_X}

运行时：若已安装

bun

则使用

bun

；若可用

npx

则使用

npx -y bun

；否则提示用户安装 bun。请将

${SKILL_DIR}

和

${BUN_X}

替换为实际值。

脚本	用途
`scripts/chunk.ts`	基于AST块（章节、标题、段落）拆分markdown内容，若块过大则按行/词数兜底拆分

Preferences (EXTEND.md)

偏好配置（EXTEND.md）

Check EXTEND.md existence (priority order):

bash

undefined

按以下优先级检查 EXTEND.md 是否存在：

bash

undefined

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

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 |

**EXTEND.md Supports**: Default target language | Default mode | Target audience | Custom glossaries | Translation style | Chunk settings

Schema: [references/config/extend-schema.md](references/config/extend-schema.md)

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


| 路径 | 位置 |
|------|----------|
| `.baoyu-skills/baoyu-translate/EXTEND.md` | 项目目录 |
| `$HOME/.baoyu-skills/baoyu-translate/EXTEND.md` | 用户根目录 |

| 结果 | 操作 |
|--------|--------|
| 找到文件 | 读取、解析并应用配置。会话内首次使用时简要提示：「正在使用来自 [path] 的配置，你可以编辑 EXTEND.md 自定义术语表、目标受众等设置。」 |
| 未找到文件 | **必须** 运行首次设置流程（见下文）—— 禁止静默使用默认配置 |

**EXTEND.md 支持配置项**：默认目标语言 | 默认模式 | 目标受众 | 自定义术语表 | 翻译风格 | 分块设置

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

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.

关键提示：当未找到 EXTEND.md 时，你必须在执行任何翻译前运行首次设置流程，这是阻塞操作。

完整参考：references/config/first-time-setup.md

调用

AskUserQuestion

一次性询问所有配置问题（目标语言、模式、受众、风格、保存位置），用户回答后在指定位置创建 EXTEND.md，确认提示「配置已保存至 [path]」后继续后续流程。

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

所有可配置值统一管理，优先级为：CLI 参数 > EXTEND.md 配置 > 默认值。

配置项	默认值	EXTEND.md 键名	CLI 参数	说明
目标语言	`zh-CN`	`target_language`	`--to`	翻译目标语言
模式	`normal`	`default_mode`	`--mode`	翻译模式
受众	`general`	`audience`	`--audience`	目标读者画像
风格	`storytelling`	`style`	—	翻译风格偏好
分块阈值	`4000`	`chunk_threshold`	—	触发分块翻译的词数阈值
单块最大词数	`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

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.

模式	参数	流程	适用场景
快速	`--mode quick`	直接翻译	短文本、非正式内容、快速翻译任务
标准	`--mode normal` （默认）	分析 → 翻译	文章、博客、通用内容
精翻	`--mode refined`	分析 → 翻译 → 校对 → 润色	出版级内容、重要文档

默认模式：标准模式（可通过 EXTEND.md 的

default_mode

配置覆盖）

自动模式检测：

输入「快翻」、「quick」、「直接翻译」→ 快速模式
输入「精翻」、「refined」、「publication quality」、「proofread」→ 精翻模式
其他情况 → 默认模式（标准）

升级提示：标准模式翻译完成后，显示：

翻译已保存。如需进一步校对润色，回复「继续润色」或「refine」。

若用户确认升级，基于现有输出继续执行校对→润色流程（和精翻模式的第3-4步一致）。

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感兴趣的普通读者"

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

```
<source>
```
：文件路径、URL 或 inline 文本
```
--from
```
：源语言（省略则自动检测）
```
--to
```
：目标语言（读取 EXTEND.md 配置，默认
```
zh-CN
```
）
```
--audience
```
：目标读者画像（读取 EXTEND.md 配置，默认
```
general
```
）
```
--glossary
```
：额外术语表文件，会和 EXTEND.md 中的术语表合并

受众预设：

值	说明	效果
`general`	普通读者（默认）	使用平实语言，对专业术语添加更多译者注
`technical`	开发者/工程师	对通用技术术语减少注释
`academic`	研究人员/学者	使用正式语体，术语翻译精准
`business`	商务人士	使用商务友好语气，对技术概念做必要解释

也支持自定义受众描述，例如

--audience "AI感兴趣的普通读者"

。

Workflow

工作流程

Step 1: Load Preferences

步骤1：加载配置

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)

1.1 检查 EXTEND.md（见上文偏好配置部分）

1.2 加载对应语言对的内置术语表（若存在）：

英→中：references/glossary-en-zh.md

1.3 合并术语表：EXTEND.md 术语表 + 内置术语表 +

--glossary

指定文件（CLI 参数优先级最高）

Step 2: Materialize Source & Create Output Directory

步骤2：实体化源文件 & 创建输出目录

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.

如果输入不是文件，先将其保存为文件，然后在源文件同级目录创建输出子目录。

2.1 实体化源文件

输入类型	操作
文件	直接使用（无需复制）
Inline 文本	保存至 `translate/{slug}.md`
URL	抓取内容，保存至 `translate/{slug}.md`

{slug}

：从内容主题衍生的2-4个单词的 kebab-case 格式短名。

2.2 创建输出目录

{source-dir}/{source-basename}-{target-lang}/

示例：

```
posts/article.md
```
→
```
posts/article-zh/
```

translate/ai-future.md

→

translate/ai-future-zh/

冲突处理：如果输出目录已存在，将原有目录重命名为

{name}.backup-YYYYMMDD-HHMMSS/

后再创建新目录，禁止覆盖已有结果。

2.3 输出目录内容

所有中间文件和最终文件都存放在该目录下：

文件	适用模式	说明
`translation.md`	所有模式	最终翻译文件（固定文件名）
`01-analysis.md`	标准、精翻模式	内容分析结果（领域、语气、术语）
`02-prompt.md`	标准、精翻模式	组装后的翻译提示词（供子Agent或内联翻译使用）
`03-draft.md`	精翻模式	校对前的初始草稿
`04-review.md`	精翻模式	校对后的修改版本
`chunks/`	分块翻译场景	源文件分块 + 翻译后的分块
`chunks/chunk-01.md`	分块翻译场景	源文件分块
`chunks/chunk-01-draft.md`	分块翻译场景	翻译后的分块

若未指定

--from

则自动检测源语言。

Step 3: Assess Content Length

步骤3：评估内容长度

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

快速模式不做分块，无论内容长度直接翻译；如果内容超过模型上下文限制，建议用户切换到标准或精翻模式。

标准和精翻模式的分块规则：

内容长度	操作
< 分块阈值	整段翻译
≥ 分块阈值	分块翻译（见步骤3.1）

3.1 长内容预处理（仅标准/精翻模式、内容≥分块阈值时执行）

分块翻译前执行以下操作：

提取术语：扫描全文档识别专有名词、技术术语、高频短语
构建会话术语表：将提取的术语和已加载的术语表合并，确定统一翻译规则
拆分内容块：执行
```
${BUN_X} ${SKILL_DIR}/scripts/chunk.ts <file> [--max-words <chunk_max_words>]
```
- 解析 markdown AST（标题、段落、列表、代码块、表格等）
- 优先在markdown块边界拆分，保留内容结构
- 若单个块超过阈值，则依次按行、按词兜底拆分
组装翻译提示词：
- 主Agent读取
```
01-analysis.md
```
  （若存在），使用 references/subagent-prompt-template.md 第一部分组装共享上下文，内联内容背景、合并后的术语表、理解难点
- 保存为输出目录下的
```
02-prompt.md
```
  （仅共享上下文，不含任务指令）
通过子Agent生成草稿（若Agent工具可用）：
- 为每个分块并行生成一个子Agent（使用模板第二部分）
- 每个子Agent读取
```
02-prompt.md
```
  获取共享上下文，翻译对应分块，保存为
```
chunks/chunk-NN-draft.md
```
- 共享的
```
02-prompt.md
```
  （术语表+分析得到的理解难点）保障术语一致性
- 若内容未超过阈值无需分块：生成一个子Agent处理整份源文件
- 若Agent工具不可用：基于
```
02-prompt.md
```
  按顺序内联翻译所有分块
合并内容：所有子Agent完成翻译后，按顺序合并翻译后的分块，若存在前置元数据则保留 → 保存为
```
03-draft.md
```
（精翻模式）或
```
translation.md
```
（标准模式）
所有中间文件（源分块+翻译分块）都保留在
```
chunks/
```
目录下

分块草稿合并完成后，控制权交还给主Agent执行校对和润色（步骤4）。

Step 4: Translate & Refine

步骤4：翻译 & 润色

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.

翻译原则（所有模式均适用）：

准确性优先：事实、数据、逻辑必须和原文完全一致
表达自然：使用目标语言的惯用语序，长句拆分为短句
术语统一：使用标准译法，首次出现时在括号内标注原文术语
格式保留：保留所有markdown格式（标题、粗体、斜体、图片、链接、代码块）
尊重原文：保留原文结构和含义，不新增、删除内容或发表主观评论
译者注：对于目标读者可能不理解的术语、概念、文化梗（因专业术语、文化差异、领域知识壁垒导致），在术语后紧跟括号添加简洁解释，解释需用平实语言说明含义，而非仅给出英文原文。格式：
```
译文（English original，通俗解释）
```
。注释深度根据目标受众调整：普通读者比技术读者需要更多注释，仅在必要时添加注释，避免对显而易见的术语过度标注。

Quick Mode

快速模式

Translate directly → save to

translation.md

直接翻译 → 保存为

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

内容分析 → 保存为
```
01-analysis.md
```
（领域、语气、受众、术语、读者理解难点）
组装提示词 → 保存为
```
02-prompt.md
```
（带上下文的翻译指令）
执行翻译（遵循
```
02-prompt.md
```
要求）→ 保存为
```
translation.md
```

完成后提示用户：「翻译已保存。如需进一步校对润色，回复 继续润色 或 refine。」

若用户确认升级，继续执行校对→润色流程（和下文精翻模式的3-4步一致），将当前

translation.md

重命名为

03-draft.md

，依次生成

04-review.md

和更新后的

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.

出版级质量的完整工作流，每步的详细规范见 references/refined-workflow.md。

（步骤3.1中使用的）子Agent仅负责生成初始草稿，后续所有步骤由主Agent处理，主Agent可根据需要自行委派子Agent执行任务。

步骤和对应保存的文件（均存于输出目录）：

内容分析 → 保存为
```
01-analysis.md
```
（领域、语气、术语、读者理解难点）
组装提示词 → 保存为
```
02-prompt.md
```
（带上下文的翻译指令）
生成草稿 → 保存为
```
03-draft.md
```
（带译者注的初始翻译，分块场景下由子Agent生成）
内容校对 → 保存为
```
04-review.md
```
（修正准确性、通顺度、术语问题）
内容润色 → 保存为
```
translation.md
```
（最终出版级翻译）

每一步读取上一步的输出文件，基于其继续处理。

Step 5: Output

步骤5：输出结果

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}

最终翻译文件固定为输出目录下的

translation.md

。

显示摘要信息：

**翻译完成**（{mode} 模式）

源文件：{source-path}
语言：{from} → {to}
输出目录：{output-dir}/
最终文件：{output-dir}/translation.md
应用术语数：{count}

Extension Support

扩展支持

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

通过 EXTEND.md 实现自定义配置，路径和支持的配置项见偏好配置部分。