Docs & Knowledge · JimLiu/baoyu-skills
baoyu-translate
This skill should be used when the user asks to "translate", "翻译", "精翻", "translate article", "translate to Chinese", "translate to English", "改成中文", "改成英文", "convert to Chinese", "localize", "本地化", "refined translation", "精细翻译", "proofread translation", "快速翻译", "快翻", "这篇文章翻译一下", or provides a URL/file with translation intent. Supports three modes (quick/normal/refined) with custom glossary support.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The three modes (quick / normal / refined) are not script arguments, but prompt orchestration pipelines: quick translates directly, normal analyzes first before translating, and refined executes 'analysis → translation → review → revision → polishing' while saving intermediate artifacts to disk step by step.
skills/baoyu-translate/SKILL.md
| Refined | `--mode refined` | Analyze → Translate → Review → Polish | Publication-quality, important documents |
What happens here: The script solely handles chunking, while translation quality is driven by the steps defined in SKILL.md and reference files (refined-workflow.md); artifacts from each step remain in the output directory, making every step auditable.
Long document chunking is purely local markdown block-level splitting: chunk.ts uses markdown-it to parse block boundaries and splits by word count (default 5000), falling back to line or word-level splitting for excessively long blocks.
skills/baoyu-translate/scripts/chunk.ts
const maxWords = options.maxWords ?? 5000
Splitting at markdown block boundaries prevents breaking headers, lists, tables, or code blocks; CJK characters are counted independently to avoid underestimating Chinese word counts.
Cross-chunk terminology consistency relies on a 'shared context file' rather than model memory: the main agent writes tone, background, merged glossaries, and translation challenges into 02-prompt.md, which each chunk's subagent reads.
skills/baoyu-translate/SKILL.md
Consistency is guaranteed by the shared `02-prompt.md`
This is why it can execute parallel translations without terminology drift: the context is maintained in a file rather than in conversational context.
Terminology sources are merged across four tiers with clear precedence: EXTEND.md inline → EXTEND.md external glossary file → built-in EN→ZH table → CLI --glossary (highest).
skills/baoyu-translate/SKILL.md
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)
The built-in table references/glossary-en-zh.md provides out-of-the-box consistency for technical and product terms.
A subagent is launched for each chunk to translate in parallel, and subagents can fall back to sequential inline translation if the host lacks tool capabilities.
skills/baoyu-translate/SKILL.md
Spawn one subagent **per chunk**, all in parallel
The subagent prompt template is located at references/subagent-prompt-template.md: it reads {output_dir}/02-prompt.md as shared context and writes the translation to chunks/chunk-{NN}-draft.md.
First-time use involves a blocking setup: if EXTEND.md cannot be found, it prompts for user preferences and writes them down before proceeding, forbidding silent runs with default values.
skills/baoyu-translate/references/config/first-time-setup.md
**BLOCKING OPERATION**: This setup MUST complete before ANY translation.
Prevents silent errors like 'the default target language is not what you wanted'; simultaneously persists preferences to EXTEND.md across one of three scopes: project / XDG / home directory.
For URL inputs, the script itself does not connect to the network: SKILL.md merely requires the agent to 'materialize the source' by scraping web content and saving it as local markdown, while the script processes only local files throughout.
skills/baoyu-translate/references/workflow-mechanics.md
| URL | Fetch content, save to `translate/{slug}.md` |
What happens here: Network operations are delegated to the host agent, keeping the skill's bundled scripts entirely free of network exposure (chunk.ts only imports fs/path/markdown-it).
The output directory follows a fixed convention and renames backups on conflict instead of overwriting: `{source-dir}/{source-basename}-{target-lang}/`, renaming any existing directory first.
skills/baoyu-translate/references/workflow-mechanics.md
Create a subdirectory next to the source file: `{source-dir}/{source-basename}-{target-lang}/`
Combined with fixed file names (translation.md / 01-analysis.md … 05-revision.md), this ensures multiple translation runs do not overwrite each other and remain comparable.
2Core Capabilities
01Three translation modes (quick direct / normal analyze-then-translate / refined publication-grade review and polish)
029 tone styles + 4 audience presets (supports custom text descriptions)
03Custom glossaries (four-tier merge: inline / external file / built-in EN→ZH / CLI)
04Automatic chunking for long texts + parallel translation with one subagent per chunk (shared prompt ensures consistency)
05Configurable chunking threshold and chunk size (EXTEND.md chunk_threshold / chunk_max_words)
06Refined translation archiving: 01-analysis / 02-prompt / 03-draft / 04-critique / 05-revision / translation.md
07Explicit translation principles: rewrite rather than translate literally, maintain term consistency, preserve markdown structure, add explanatory parenthetical notes when needed
08Post-delivery image language inspection (flags images that might still contain source text, alerts without modifying images)
09Preference persistence via EXTEND.md (project / XDG / home directory tiers, blocking setup on first run)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| package | markdown-it 14.1.1（唯一运行时依赖） |
| package | markdown-it 运行时 import |
| cli | bun（脚本 shebang 运行时） |
| cli | npx -y bun（无 bun 时的回退运行时） |
| network | homepage 元数据 URL（静态 frontmatter，任何步骤都不抓取） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Execute local script or command: ${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words N] [--output-dir D] (
- 网络端点: Declare external network access: Skill's bundled scripts have zero network calls: chunk.ts only imports fs / path / markdown-it, package.json contains no ht
- 本地工作目录: File read/write and artifact output: {source-dir}/{source-basename}-{target-lang}/ output directory (if existing, renamed first to {name}.backup-Y
Audit Notes: Grading target = this skill directory: contains bundled scripts/main.ts + chunk.ts (purely local chunking via markdown-it), sole dependency is markdown-it@14.1.1, behaves by reading one local file and writing chunks/ and output directories; entire directory has zero network endpoints, credential/env variable reads, or sub-process spawning → Blue (not Green: bundles scripts and actively writes to disk; not Yellow: the skill itself does not access any external endpoints, completely detached from rendering or translation backends). URL fetching happens on the host agent side (SKILL.md only requests materializing the source), which per standard criteria does not impact the tier rating, though it is documented in risks.
5Second-Pass Verification
- [ok] 脚本零网络、零凭证 — chunk.ts 仅 import fs/path/markdown-it，main.ts 仅 import node:process + ./chunk.js；grep http/fetch/curl/process.env/API_KEY 在两个脚本内零命中。
- [ok] 切块逻辑与 SKILL.md 描述一致 — chunk.ts 用 markdown-it 解析、在块边界切分、超长块退化处理，默认 maxWords 5000，与 SKILL.md『Splits at markdown block boundaries to preserve structure』一致；frontmatter 被单独抽出为 chunks/frontmatter.md。
- [ok] 依赖面 = markdown-it 单包 — package.json 仅声明 markdown-it 14.1.1，bun.lock 中的其余条目均为其传递依赖（argparse/entities/linkify-it/mdurl/punycode.js/uc.micro），无 postinstall、无网络行为。
- [ok] subagent 分工与模板内容 — subagent-prompt-template.md 明确 shared context → 02-prompt.md、每块产出 chunks/chunk-{NN}-draft.md；spawn 动作由 agent 执行，脚本不 spawn 任何进程。
- [ok] URL 输入的网络归属 — workflow-mechanics.md 把 URL 处理写成 agent 的『Fetch content』动作；本 skill 目录内无抓取代码，故网络面不落在 skill 自身。
- [ok] EXTEND.md 路径不一致（轻微） — SKILL.md 列三条路径（含 XDG），references/config/extend-schema.md 只列项目与家目录两条；属文档不一致，不影响判级，已在 traits/risks 采信 SKILL.md 的三档说法。
- [ok] 元数据与 pin — 本地 HEAD = 1567581c26ec29f4216c6e6835415bf30343b0e3；GitHub API MIT / 25926 stars / pushed_at 2026-09-10T15:13:43Z；仓库根 LICENSE 为 MIT。
6Verdict & Scenarios
Best for: Ideal for individuals and teams requiring publication-grade Chinese/English long-form texts: technical blogs, tutorials, research reports, book chapters; also suitable for teams with standardized glossaries (locking terms via EXTEND.md), long texts needing parallel acceleration (chunking + subagents), and workflows that demand retaining intermediate artifacts for audit and review.
Not for: Not suitable for one-sentence short translations (overhead outside quick mode is unjustified); environments lacking Agent/subagent capabilities that cannot tolerate waiting for sequential processing; scenarios expecting the skill to automatically fetch arbitrary web content (scraping is the host's responsibility); or workflows publishing unvetted translations of untrusted web content without human review.
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload baoyu-translate.tar.gz
sha256:
Option B · Copy Guide for Agent38c8846f411e3248…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 1567581c26.