baoyu-translate by jimliu/baoyu-skills
npx skills add https://github.com/jimliu/baoyu-skills --skill baoyu-translate三模式翻译技能:快速 用于直接翻译,常规 用于基于分析的翻译,精炼 用于包含审阅和润色的完整出版质量工作流。
脚本位于 scripts/ 子目录。{baseDir} = 此 SKILL.md 文件的目录路径。解析 ${BUN_X} 运行时:如果已安装 bun → 使用 bun;如果 npx 可用 → 使用 npx -y bun;否则建议安装 bun。将 {baseDir} 和 ${BUN_X} 替换为实际值。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 脚本 | 用途 |
|---|---|
scripts/main.ts | CLI 入口点。默认操作将 Markdown 分割成块;也支持显式的 chunk 子命令 |
scripts/chunk.ts | Markdown 分块实现,供 main.ts 使用,并保持兼容性以便直接调用 |
检查 EXTEND.md 是否存在(优先级顺序):
# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-translate/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md" && echo "user"
# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-translate/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-translate/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md") { "user" }
| 路径 | 位置 |
|---|---|
.baoyu-skills/baoyu-translate/EXTEND.md | 项目目录 |
$HOME/.baoyu-skills/baoyu-translate/EXTEND.md | 用户主目录 |
| 结果 | 操作 |
| --- | --- |
| 找到 | 读取、解析、应用设置。在会话中首次使用时,简要提醒:"使用来自 [路径] 的偏好设置。您可以编辑 EXTEND.md 以自定义术语表、受众等。" |
| 未找到 | 必须 运行首次设置(见下文)—— 请勿静默使用默认值 |
EXTEND.md 支持:默认目标语言 | 默认模式 | 目标受众 | 自定义术语表(内联或文件路径) | 翻译风格 | 分块设置
关键:当未找到 EXTEND.md 时,在进行任何翻译之前,您必须运行首次设置。这是一个阻塞式操作。
使用 AskUserQuestion 在一次调用中询问所有问题(目标语言、模式、受众、风格、保存位置)。用户回答后,在所选位置创建 EXTEND.md,确认"偏好设置已保存至 [路径]",然后继续。
所有可配置值集中在此处。EXTEND.md 会覆盖这些值;CLI 标志会覆盖 EXTEND.md。
| 设置项 | 默认值 | EXTEND.md 键名 | CLI 标志 | 描述 |
|---|---|---|---|---|
| 目标语言 | zh-CN | target_language | --to | 翻译目标语言 |
| 模式 | normal | default_mode | --mode | 翻译模式 |
| 受众 | general | audience | --audience | 目标读者画像 |
| 风格 | storytelling | style | --style | 翻译风格偏好 |
| 分块阈值 | 4000 | chunk_threshold | — | 触发分块翻译的字数阈值 |
| 分块最大字数 | 5000 | chunk_max_words | — | 每块最大字数 |
| 模式 | 标志 | 步骤 | 使用时机 |
|---|---|---|---|
| 快速 | --mode quick | 翻译 | 短文本、非正式内容、快速任务 |
| 常规 | --mode normal (默认) | 分析 → 翻译 | 文章、博客帖子、一般内容 |
| 精炼 | --mode refined | 分析 → 翻译 → 审阅 → 润色 | 出版质量、重要文档 |
默认模式:常规(可在 EXTEND.md 的 default_mode 设置中覆盖)。
风格预设 — 控制翻译的语气和语调(独立于受众):
| 值 | 描述 | 效果 |
|---|---|---|
storytelling | 引人入胜的叙述流(默认) | 吸引读者,平滑过渡,生动的措辞 |
formal | 专业、结构化 | 中性语气,清晰的组织,无口语化表达 |
technical | 精确、文档风格 | 简洁,术语密集,极少修饰 |
literal | 接近原文结构 | 最小化结构调整,保留源语句模式 |
academic | 学术、严谨 | 正式语域,允许复杂从句,注意引用 |
business | 简洁、结果导向 | 行动导向,适合高管,注重要点 |
humorous | 保留并适配幽默 | 机智、俏皮,在目标语言中重现喜剧效果 |
conversational | 随意、口语化 | 友好、平易近人,如同向朋友解释 |
elegant | 文学、精炼散文 | 美学上精炼,有节奏感,精心雕琢的措辞 |
也接受自定义风格描述,例如 --style "poetic and lyrical"。
自动检测:
升级提示:常规模式完成后,显示:
翻译已保存。如需进一步审阅和润色,请回复"继续润色"或"refine"。
如果用户响应,则继续执行审阅 → 润色步骤(与精炼模式中的步骤 4-6 相同,见 refined-workflow.md)处理现有输出。
/translate [--mode quick|normal|refined] [--from <lang>] [--to <lang>] [--audience <audience>] [--style <style>] [--glossary <file>] <source>
<source>:文件路径、URL 或内联文本--from:源语言(如果省略则自动检测)--to:目标语言(来自 EXTEND.md 或默认 zh-CN)--audience:目标读者画像(来自 EXTEND.md 或默认 general)--style:翻译风格(来自 EXTEND.md 或默认 storytelling)--glossary:额外的术语表文件,与 EXTEND.md 术语表合并受众预设:
| 值 | 描述 | 效果 |
|---|---|---|
general | 普通读者(默认) | 平实的语言,对术语有更多译者注 |
technical | 开发者/工程师 | 对常见技术术语的注释较少 |
academic | 研究人员/学者 | 正式语域,精确的术语 |
business | 商务专业人士 | 商务友好的语气,解释技术概念 |
也接受自定义受众描述,例如 --audience "AI感兴趣的普通读者"。
1.1 检查 EXTEND.md(见上文的偏好设置部分)
1.2 如果可用,加载语言对的预置术语表:
1.3 合并术语表:EXTEND.md glossary(内联)+ EXTEND.md glossary_files(外部文件,路径相对于 EXTEND.md 位置)+ 预置术语表 + --glossary 文件(CLI 覆盖所有)
物化源文件(文件原样,内联文本/URL → 保存到 translate/{slug}.md),然后创建输出目录:{source-dir}/{source-basename}-{target-lang}/。如果未指定 --from,则检测源语言。
输出目录内容(所有中间文件和最终文件都放在这里):
| 文件 | 模式 | 描述 |
|---|---|---|
translation.md | 全部 | 最终翻译(始终使用此名称) |
01-analysis.md | 常规, 精炼 | 内容分析(领域、语气、术语) |
02-prompt.md | 常规, 精炼 | 组装的翻译提示 |
03-draft.md | 精炼 | 审阅前的初始草稿 |
04-critique.md | 精炼 | 批判性审阅发现(仅诊断) |
05-revision.md | 精炼 | 基于审阅的修订翻译 |
chunks/ | 分块 | 源文件块 + 翻译块 |
快速模式不分块 — 无论长度如何都直接翻译。在翻译前,估算字数。如果内容超过分块阈值(默认 4000 字),主动警告:"本文约 {N} 字。快速模式将一次性翻译而不分块 — 对于长内容,--mode normal 能通过术语一致性产生更好的结果。" 如果用户不切换模式,则继续。
对于常规和精炼模式:
| 内容 | 操作 |
|---|---|
| < 分块阈值 | 作为单个单元翻译 |
= 分块阈值 | 分块翻译(见步骤 3.1)
3.1 长内容准备(仅限常规/精炼模式,>= 分块阈值)
在翻译分块之前:
${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words <chunk_max_words>] [--output-dir <output-dir>]
* 解析 Markdown 块(标题、段落、列表、代码块、表格等)
* 在 Markdown 块边界处分割以保持结构
* 如果单个块超过阈值,则回退到按行分割,然后按词分割01-analysis.md(如果存在)并使用 references/subagent-prompt-template.md 的第一部分组装共享上下文 — 内联解析后的风格预设(来自 --style 标志、EXTEND.md style 设置或默认的 storytelling)、内容背景、合并的术语表以及理解难点
* 保存为输出目录中的 02-prompt.md(仅共享上下文,无任务指令)02-prompt.md 获取共享上下文,翻译其分块,保存到 chunks/chunk-NN-draft.md
* 术语一致性由共享的 02-prompt.md(术语表 + 分析中的理解难点)保证
* 如果没有分块(内容低于阈值):为整个源文件生成一个子代理
* 如果 Agent 工具不可用,则使用 02-prompt.md 内联顺序翻译分块chunks/frontmatter.md,则将其前置。保存为 03-draft.md(精炼模式)或 translation.md(常规模式)chunks/ 中分块草稿合并后,将控制权交还给主代理进行批判性审阅、修订和润色(步骤 4)。
翻译原则(适用于所有模式):
url→sourceUrl、title→sourceTitle、description→sourceDescription、author→sourceAuthor、date→sourceDate,以及任何类似的来源元数据字段 — 通过添加 source 前缀(camelCase)。(2) 翻译文本字段(标题、描述等)的值,并将它们作为新的顶级字段添加。(3) 其他字段(标签、类别、自定义字段)保持不变,在适当的地方翻译它们的值译文(English original,通俗解释)。根据目标受众调整注释深度:普通读者比技术读者需要更多注释。对于短文本(< 5 句),进一步减少注释 — 仅注释目标受众不太可能知道的非通用术语;跳过在上下文中广为人知或自明的术语。仅在确实需要的地方添加注释;不要过度注释明显的术语。直接翻译 → 保存到 translation.md。没有分析文件,但仍应用上述所有翻译原则 — 特别是:根据含义解释比喻性语言(而非逐字翻译),保留情感内涵,并为自然的目标语言流重组句子。
01-analysis.md(领域、语气、受众、术语、读者理解难点、比喻性语言及隐喻映射)02-prompt.md(翻译指令,内联了风格预设、内容背景、术语表和理解难点)02-prompt.md) → translation.md完成后,提示用户:"翻译已保存。如需进一步审阅和润色,请回复 继续润色 或 refine。"
如果用户继续,则进行批判性审阅 → 修订 → 润色(与下文精炼模式的步骤 4-6 相同),保存 03-draft.md(重命名当前的 translation.md)、04-critique.md、05-revision.md 和更新后的 translation.md。
用于出版质量的完整工作流。每个步骤的详细指南请参阅 references/refined-workflow.md。
子代理(如果在步骤 3.1 中使用)仅处理初始草稿。所有后续步骤(批判性审阅、修订、润色)都由主代理处理,主代理可自行决定是否委托给子代理。
步骤和保存的文件(均在输出目录中):
01-analysis.md(领域、语气、术语、读者理解难点、比喻性语言及隐喻映射)02-prompt.md(翻译指令,内联了上下文)03-draft.md(带译者注的初始翻译;如果分块则来自子代理)04-critique.md(仅诊断:准确性、欧化语言、策略执行、表达问题)05-revision.md(应用所有审阅发现以生成修订后的翻译)translation.md(最终的出版质量翻译)每个步骤读取前一步骤的文件并在此基础上构建。
最终翻译始终位于输出目录中的 translation.md。
最终翻译写入后,进行轻量级的图片语言检查:
提醒格式(使用文章中已有的任何图片语法 — 标准 Markdown 或 wikilink):
Possible image localization needed:
- : likely still contains source-language text while the article is now in target language
- : likely text-heavy framework graphic, check whether labels need translation
显示摘要:
**Translation complete** ({mode} mode)
Source: {source-path}
Languages: {from} → {to}
Output dir: {output-dir}/
Final: {output-dir}/translation.md
Glossary terms applied: {count}
如果发现不匹配的图片语言候选,在摘要后附加简短说明,告知用户某些嵌入的图片可能仍需要图片文本本地化,然后是候选列表。
通过 EXTEND.md 进行自定义配置。有关路径和支持的选项,请参阅偏好设置部分。
每周安装量
6.2K
代码库
GitHub 星标
10.8K
首次出现
Mar 6, 2026
安全审计
安装于
opencode6.0K
codex6.0K
gemini-cli6.0K
cursor6.0K
kimi-cli6.0K
github-copilot6.0K
Three-mode translation skill: quick for direct translation, normal for analysis-informed translation, refined for full publication-quality workflow with review and polish.
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 |
Check EXTEND.md existence (priority order):
# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-translate/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md" && echo "user"
# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-translate/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-translate/EXTEND.md") { "xdg" }
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 (inline or file path) | Translation style | Chunk settings
Schema: references/config/extend-schema.md
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.
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 |
| 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 |
Custom style descriptions are also accepted, e.g., --style "poetic and lyrical".
Auto-detection :
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.
/translate [--mode quick|normal|refined] [--from <lang>] [--to <lang>] [--audience <audience>] [--style <style>] [--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)--style: Translation style (from EXTEND.md or default storytelling)--glossary: Additional glossary file to merge with EXTEND.md glossaryAudience 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感兴趣的普通读者".
1.1 Check EXTEND.md (see Preferences section above)
1.2 Load built-in glossary for the language pair if available:
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)
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 |
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't switch.
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:
${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words <chunk_max_words>] [--output-dir <output-dir>]
01-analysis.md (if exists) and assembles shared context using Part 1 of references/subagent-prompt-template.md — inlining the resolved style preset (from --style flag, EXTEND.md style setting, or default storytelling), content background, merged glossary, and comprehension challengesAfter chunked draft is merged , return control to main agent for critical review, revision, and polish (Step 4).
Translation principles (apply to all modes):
url→sourceUrl, →, →, →, →, and any similar origin-metadata fields — by adding a prefix (camelCase). (2) Translate the values of text fields (title, description, etc.) and add them as new top-level fields. (3) Keep other fields (tags, categories, custom fields) as-is, translating their values where appropriateTranslate directly → save to translation.md. No analysis file, but still apply all translation principles above — especially: interpret figurative language by meaning (not word-for-word), preserve emotional connotations, and restructure sentences for natural target-language flow.
01-analysis.md (domain, tone, audience, terminology, reader comprehension challenges, figurative language & metaphor mapping)02-prompt.md (translation instructions with inlined style preset, content background, glossary, and comprehension challenges)02-prompt.md) → translation.mdAfter completion, prompt user: "Translation saved. To further review and polish, reply 继续润色 or refine."
If user continues, proceed with critical review → revision → polish (same as refined mode Steps 4-6 below), saving 03-draft.md (rename current translation.md), 04-critique.md, 05-revision.md, and updated translation.md.
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 (critical review, revision, polish) are handled by the main agent, which may delegate to subagents at its discretion.
Steps and saved files (all in output directory):
01-analysis.md (domain, tone, terminology, reader comprehension challenges, figurative language & metaphor mapping)02-prompt.md (translation instructions with inlined context)03-draft.md (initial translation with translator's notes; from subagent if chunked)04-critique.md (diagnosis only: accuracy, Europeanized language, strategy execution, expression issues)05-revision.md (apply all critique findings to produce revised translation)translation.md (final publication-quality translation)Each step reads the previous step's file and builds on it.
Final translation is always at translation.md in the output directory.
After the final translation is written, do a lightweight image-language pass:
Reminder format (use whatever image syntax the article already uses — standard markdown or wikilink):
Possible image localization needed:
- : likely still contains source-language text while the article is now in target language
- : likely text-heavy framework graphic, check whether labels need translation
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}
If mismatched image-language candidates were found, append a short note after the summary telling the user that some embedded images may still need image-text localization, followed by the candidate list.
Custom configurations via EXTEND.md. See Preferences section for paths and supported options.
Weekly Installs
6.2K
Repository
GitHub Stars
10.8K
First Seen
Mar 6, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
opencode6.0K
codex6.0K
gemini-cli6.0K
cursor6.0K
kimi-cli6.0K
github-copilot6.0K
97,600 周安装
| 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 |
| 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 |
| Critical review findings (diagnosis only) |
05-revision.md | Refined | Revised translation based on critique |
chunks/ | Chunked | Source chunks + translated chunks |
02-prompt.md in the output directory (shared context only, no task instructions)02-prompt.md for shared context, translates its chunk, saves to chunks/chunk-NN-draft.md02-prompt.md (glossary + comprehension challenges from analysis)02-prompt.mdchunks/frontmatter.md exists, prepend it. Save as 03-draft.md (refined) or translation.md (normal)chunks/titlesourceTitledescriptionsourceDescriptionauthorsourceAuthordatesourceDatesource译文(English original,通俗解释). Calibrate annotation depth to the target audience: general readers need more notes than technical readers. For short texts (< 5 sentences), further reduce annotations — only annotate non-common terms that the target audience is unlikely to know; skip terms that are widely recognized or self-explanatory in context. Only add notes where genuinely needed; do not over-annotate obvious terms.