npx skills add https://github.com/beaverslab/beaver-skill --skill beaver-markdown-i18n高效的令牌翻译流程。脚本负责解析、缓存、掩码和验证——您只需翻译标记的片段。
SKILL_DIR — 将其设置为此技能根目录的绝对路径(包含此 SKILL.md 的文件夹)。以下所有
node命令均使用$SKILL_DIR/scripts/。
ERROR 或任何 WARN 时,不得 将文件标记为完成,除非用户明确确认接受。ERROR 或 WARN, 停止,显示验证输出,并在执行 之前等待用户确认。Token-efficient translation pipeline. Scripts handle parsing, caching, masking, and validation — you only translate the marked segments.
SKILL_DIR — set this to the absolute path of this skill's root directory (the folder containing this SKILL.md). All
nodecommands below use$SKILL_DIR/scripts/.
ERROR or any WARN unless the user explicitly confirms acceptance.ERROR or WARN, MUST stop, show the validation output, and wait for user confirmation before .广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
plan set ... done此技能有一个正确的执行顺序。请严格遵守。
普通文件流程
prepareafterTranslateERROR:停止并手动修复WARN:停止并获取明确的用户确认afterTranslate --allow-warnings分块文件流程
preparecheckpoint <chunk-file>mergeafterTranslateERROR:停止并手动修复WARN:停止并获取明确的用户确认afterTranslate --allow-warnings不得 更改此顺序。不得 跳过 afterTranslate。不得 在不遵守上述停止规则的情况下继续处理 ERROR 或 WARN。
所有场景——单个文件、批量、增量同步——都使用相同的流程。
此步骤始终最先进行。
运行准备命令以生成目标文件的骨架:
# 单个文件
node $SKILL_DIR/scripts/translate-cli.js prepare <source.md> <target.md> --lang <locale>
# 目录(批量 / 同步)
node $SKILL_DIR/scripts/translate-cli.js prepare <source_dir/> <target_dir/> --lang <locale>
# 从现有翻译中填充翻译记忆库(一次性迁移)
node $SKILL_DIR/scripts/translate-cli.js seed <source_dir/> <target_dir/> --lang <locale>
准备步骤内部执行的操作(您不需要执行这些操作):
.i18n/no-translate.yaml、.i18n/translation-consistency.yaml 和术语表.i18n/<lang>.tm.jsonl)%%Pn%% 占位符%%CB_<hash>%% 占位符——基于内容的哈希 ID,因此它们能经受分块重新排序<!-- i18n:todo --> 标记未翻译的片段.i18n/chunks/ 中的分块,在片段边界处分割.i18n/task-meta.json查看控制台输出——它显示了待翻译的片段、缓存数量以及生成的任何分块。
此步骤始终在 prepare 之后、apply 之前进行。
打开骨架文件(对于大型文档,则打开分块文件)。对于每个 <!-- i18n:todo --> 部分,将标记之间的内容翻译为目标语言。
规则:
<!-- i18n:todo --> 和 <!-- /i18n:todo --> 标记之间的文本%%Pn%% 和 %%CB_<hash>%% 占位符完全不变——不要修改、删除或重新格式化它们apply.js 会自动移除它们示例——翻译前:
<!-- i18n:todo -->
See [configuration]%%P2%% for %%P1%% flag details.
<!-- /i18n:todo -->
示例——翻译后:
<!-- i18n:todo -->
参阅[配置]%%P2%%了解 %%P1%% 标志详情。
<!-- /i18n:todo -->
警告——占位符:
%%Pn%%和%%CB_<hash>%%将由应用脚本恢复为原始内容(行内代码、URL、代码块)。如果您删除或修改它们,最终文档将被破坏。如有疑问,请保持原样。
大型文件(分块): 如果准备步骤在 .i18n/chunks/ 中生成了分块,请按顺序(chunk-001, chunk-002, …)一次翻译一个分块文件。
关键规则——每轮次/请求仅处理一个分块:
checkpoint,然后移动到下一个分块此规则是强制性的。分块翻译设计为严格顺序执行,而非批量处理。
仅读取当前分块,翻译其所有 <!-- i18n:todo --> 部分,保存,然后在移动到下一个分块之前将该分块检查点保存到翻译记忆库:
node $SKILL_DIR/scripts/translate-cli.js checkpoint <chunk-file>
所有分块翻译完成后,将它们合并回来:
node $SKILL_DIR/scripts/translate-cli.js merge <target>
在所有分块都已翻译并检查点保存之前,不得运行 merge。不得对分块文件运行 apply。
如果同一目标的分块文件已存在,默认情况下 prepare 现在会拒绝覆盖它们。这是为了保护进行中的分块翻译。仅当您确实想要丢弃旧的分块状态并从源重新生成时,才使用 --overwrite-chunks。
此步骤始终在翻译完成后进行。对于分块文件,仅在 merge 之后进行。
运行组合命令:
node $SKILL_DIR/scripts/translate-cli.js afterTranslate <source> <target> [--lang <locale>]
afterTranslate 内部执行的操作:
applyqualityplan set ... doneERROR,停止WARN,停止,除非您在获得明确的用户确认后重新运行并加上 --allow-warnings当 afterTranslate 调用 apply 时,apply 内部执行的操作:
<!-- i18n:todo --> 标记%%Pn%% → 原始行内代码/URL,%%CB_<hash>%% → 原始代码块prepare 仅重用翻译记忆库。如果您翻译了一个骨架,然后在 apply(或 seed)之前再次运行 prepare,目标文件可能会再次从源文本重新生成。
如果 afterTranslate 因 ERROR 停止: 手动修复目标文件,然后重新运行 afterTranslate。如果 afterTranslate 因 WARN 停止: 首先获取明确的用户确认,然后使用 --allow-warnings 重新运行。
CLI 仍保留用于调试或逐步使用的手动接口:
node $SKILL_DIR/scripts/translate-cli.js apply <source> <target> [--lang <locale>]
node $SKILL_DIR/scripts/quality-cli.js <source> <target> --target-locale <locale>
node $SKILL_DIR/scripts/plan-cli.js set <file_pattern> done
仅当您有意需要单独检查每个步骤时,才使用手动命令。
独立质量检查(不更改状态):
node $SKILL_DIR/scripts/quality-cli.js <source> <target> --target-locale <locale>
这将运行所有检查,包括术语一致性、未翻译内容检测、章节遗漏、外部/相对链接保留以及 Frontmatter 值翻译。完整检查列表请参见 references/quality-checklist.md。
三个 CLI 工具。均以 node $SKILL_DIR/scripts/<cli>.js 方式调用。
T="node $SKILL_DIR/scripts/translate-cli.js"
# 核心流程
$T prepare <source> <target> --lang <locale> # 步骤 1:生成骨架
$T checkpoint <chunk-file> [--lang <locale>] # 将一个已翻译分块持久化到翻译记忆库
$T afterTranslate <source> <target> [--lang <locale>] # 步骤 3:应用 + 质量检查 + 计划标记完成
$T merge <target> [--project-dir .] # 在应用前合并分块
$T seed <source> <target> --lang <locale> # 从现有翻译对填充翻译记忆库
# 手动接口
$T apply <source> <target> [--lang <locale>] # 仅手动应用
# 翻译记忆库管理
$T tm stats [--lang <locale>] # 显示翻译记忆库条目计数
$T tm search <query> --lang <locale> [--limit N] # 按源/翻译文本搜索
$T tm get <cache_key> --lang <locale> # 获取单个条目
$T tm add --lang <locale> --source <text> --translated <text> # 添加条目
$T tm update <cache_key> --lang <locale> --translated <text> # 更新翻译
$T tm delete <cache_key> --lang <locale> # 删除单个条目
$T tm delete --file <rel_path> --lang <locale> [--dry-run] # 删除文件的所有条目
$T tm delete --match <query> --lang <locale> [--dry-run] # 按文本匹配批量删除
$T tm export --lang <locale> [--format jsonl|json] # 导出翻译记忆库
$T tm compact --lang <locale> # 去重并压缩翻译记忆库文件
Q="node $SKILL_DIR/scripts/quality-cli.js"
$Q <source> <target> --target-locale <locale> # 单文件检查
$Q --dir <source_dir> <target_dir> --target-locale <locale> # 目录检查
$Q <source> <target> --check structure,codeBlocks # 仅运行特定检查
$Q <source> <target> --skip terminology # 跳过特定检查
$Q <source> <target> --json # JSON 输出
检查 ID:structure, codeBlocks, variables, links, terminology, untranslated, sections, frontmatterTranslated
P="node $SKILL_DIR/scripts/plan-cli.js"
$P init <source_dir> --lang <locale> # 初始化计划 + 运行目录
$P status # 显示整体进度
$P list --status pending --sort lines [--limit N] # 过滤/列出文件
$P set <file_pattern> done [--notes "..."] # 更新单个文件状态
$P set --batch --from pending --to in_progress [--match "gateway/*"] # 批量更新
$P add <file> [--status pending] # 添加文件到计划
$P add --match "gateway/*.md" # 按通配符添加文件
$P scan [<target_dir>] [--lang <locale>] # 重新扫描目标完成度
$P sync --mode git --from <commit> --to HEAD # 检测源文件更改(git)
$P sync --mode hash # 检测源文件更改(哈希)
$P clean [--all] [--keep-plan] [--dry-run] # 清理临时文件
.i18n/no-translate.yaml应保持源语言的术语、标题和章节:
# 其值应被翻译的 Frontmatter 键
# 默认值:[title, summary, description, read_when]
frontmatter_translate_keys:
- title
- summary
- description
- read_when
headings:
- text: "API Reference"
reason: "行业标准术语"
terms:
- text: "Gateway"
reason: "产品名称"
sections:
- title: "Changelog"
reason: "历史记录"
.i18n/translation-consistency.yaml强制性的术语翻译:
translations:
install:
en: Install
zh: 安装
ja: インストール
ko: 설치
位置:.i18n/<lang>.tm.jsonl
片段级缓存。在后续运行中,prepare.js 会跳过源文本哈希与翻译记忆库条目匹配的片段,并预填充缓存的翻译——只有更改过或新的片段会获得 <!-- i18n:todo --> 标记。
要从现有翻译中填充翻译记忆库:
node $SKILL_DIR/scripts/translate-cli.js seed <source_dir> <target_dir> --lang <locale>
用于管理翻译计划的统一 CLI。
node $SKILL_DIR/scripts/plan-cli.js <command> [options]
PLAN="node $SKILL_DIR/scripts/plan-cli.js"
# 1. 初始化:创建运行目录,检测更改,扫描目标
$PLAN init <source_dir> --lang zh
# 2. 检查进度
$PLAN status
# 3. 列出待翻译文件(按大小排序)
$PLAN list --status pending --sort lines
# 4. 翻译文件后,验证它,如果存在任何警告则获取用户确认,然后将其标记为完成
$PLAN set <file_pattern> done
# 5. 批量完成后重新扫描目标
$PLAN scan
# 6. 计划完成后清理临时文件
$PLAN clean
| 命令 | 用途 |
|---|---|
init | 创建运行目录,同步源更改,扫描目标 |
scan | 扫描目标文件,计算翻译完成度 |
sync | 检测源文件更改(git diff 或哈希模式) |
add | 将文件添加到计划(单个、通配符或文件列表) |
status | 显示带有完成度指标的整体进度 |
list | 按状态、大小、名称过滤/排序文件 |
set | 更新文件状态(单个或批量) |
clean | 移除临时文件(运行目录) |
# Git 模式(默认):比较两个提交
$PLAN sync --mode git --from abc1234 --to HEAD
# 哈希模式:比较文件哈希与计划记录
$PLAN sync --mode hash
每次 init 都会创建 .i18n/runs/<timestamp>/ 用于存放临时文件(task-meta、分块、清单)。clean 会移除当前的运行目录。
每周安装次数
1
仓库
首次出现
1 天前
安全审计
安装于
amp1
cline1
openclaw1
opencode1
cursor1
kimi-cli1
plan set ... doneThis skill has one correct execution order. Follow it strictly.
Normal file flow
prepareafterTranslateERROR: stop and fix manuallyWARN: stop and get explicit user confirmationafterTranslate --allow-warnings only after explicit user confirmationChunked file flow
preparecheckpoint <chunk-file>mergeafterTranslateERROR: stop and fix manuallyWARN: stop and get explicit user confirmationafterTranslate --allow-warnings only after explicit user confirmationMUST NOT change this order. MUST NOT skip afterTranslate. MUST NOT continue past ERROR or WARN without following the stop rules above.
All scenarios — single file, batch, incremental sync — use the same pipeline.
This step always comes first.
Run the prepare command to generate a skeleton target file:
# Single file
node $SKILL_DIR/scripts/translate-cli.js prepare <source.md> <target.md> --lang <locale>
# Directory (batch / sync)
node $SKILL_DIR/scripts/translate-cli.js prepare <source_dir/> <target_dir/> --lang <locale>
# Seed TM from existing translations (one-time migration)
node $SKILL_DIR/scripts/translate-cli.js seed <source_dir/> <target_dir/> --lang <locale>
What prepare does internally (you do NOT need to do these):
.i18n/no-translate.yaml, .i18n/translation-consistency.yaml, and glossary.i18n/<lang>.tm.jsonl)%%Pn%% placeholders%%CB_<hash>%% placeholders — hash-based IDs derived from content, so they survive chunk reordering<!-- i18n:todo --> markers.i18n/chunks/, splitting at segment boundaries.i18n/task-meta.jsonReview the console output — it shows segments to translate, cached count, and any chunks generated.
This step always happens after prepare and before apply.
Open the skeleton file (or chunk files for large documents). For each <!-- i18n:todo --> section, translate the content between the markers to the target language.
Rules:
<!-- i18n:todo --> and <!-- /i18n:todo --> markers%%Pn%% and %%CB_<hash>%% placeholders exactly as-is — do NOT modify, delete, or reformat themapply.js strips them automaticallyExample — before:
<!-- i18n:todo -->
See [configuration]%%P2%% for %%P1%% flag details.
<!-- /i18n:todo -->
Example — after:
<!-- i18n:todo -->
参阅[配置]%%P2%%了解 %%P1%% 标志详情。
<!-- /i18n:todo -->
WARNING — Placeholders:
%%Pn%%and%%CB_<hash>%%are restored to original content (inline code, URLs, code blocks) by the apply script. If you delete or modify them, the final document will be broken. When in doubt, leave them in place.
Large files (chunked): If prepare generated chunks in .i18n/chunks/, translate one chunk file at a time in order (chunk-001, chunk-002, …).
CRITICAL RULE — exactly one chunk per turn/request:
checkpoint, then move to the next chunkThis rule is mandatory. Chunk translation is designed to be strictly sequential, not batched.
Read only the current chunk, translate all its <!-- i18n:todo --> sections, save, then checkpoint that chunk into TM before moving to the next one:
node $SKILL_DIR/scripts/translate-cli.js checkpoint <chunk-file>
After all chunks are translated, merge them back:
node $SKILL_DIR/scripts/translate-cli.js merge <target>
MUST NOT run merge before all chunks have been translated and checkpointed. MUST NOT run apply on chunk files.
If chunk files for the same target already exist, prepare now refuses to overwrite them by default. This is intentional to protect in-progress chunk translations. Use --overwrite-chunks only when you really want to discard the old chunk state and regenerate from source.
This step always happens after translation is complete. For chunked files, it happens only after merge.
Run the combined command:
node $SKILL_DIR/scripts/translate-cli.js afterTranslate <source> <target> [--lang <locale>]
What afterTranslate does internally:
applyqualityplan set ... doneERROR, stopsWARN, stops unless you rerun with explicit user confirmation and --allow-warningsWhat apply does internally when called by afterTranslate:
<!-- i18n:todo --> markers%%Pn%% → original inline code/URLs, %%CB_<hash>%% → original code blocksprepare only reuses Translation Memory. If you translate a skeleton and then run prepare again before apply (or seed), the target file can be regenerated from source text again.
If afterTranslate stops onERROR: fix the target file manually, then re-run afterTranslate. If afterTranslate stops onWARN: get explicit user confirmation first, then re-run with --allow-warnings.
The CLI still keeps the manual interfaces for debugging or step-by-step use:
node $SKILL_DIR/scripts/translate-cli.js apply <source> <target> [--lang <locale>]
node $SKILL_DIR/scripts/quality-cli.js <source> <target> --target-locale <locale>
node $SKILL_DIR/scripts/plan-cli.js set <file_pattern> done
Use the manual commands only when you intentionally need to inspect each step separately.
Standalone quality check (without changing status):
node $SKILL_DIR/scripts/quality-cli.js <source> <target> --target-locale <locale>
This runs all checks including terminology compliance, untranslated content detection, section omission, external/relative link preservation, and frontmatter value translation. See references/quality-checklist.md for the full check list.
Three CLI tools. All invoked as node $SKILL_DIR/scripts/<cli>.js.
T="node $SKILL_DIR/scripts/translate-cli.js"
# Core pipeline
$T prepare <source> <target> --lang <locale> # Step 1: generate skeleton
$T checkpoint <chunk-file> [--lang <locale>] # Persist one translated chunk into TM
$T afterTranslate <source> <target> [--lang <locale>] # Step 3: apply + quality + plan set done
$T merge <target> [--project-dir .] # Merge chunks before apply
$T seed <source> <target> --lang <locale> # Seed TM from existing pairs
# Manual interfaces
$T apply <source> <target> [--lang <locale>] # Manual apply only
# Translation Memory management
$T tm stats [--lang <locale>] # Show TM entry counts
$T tm search <query> --lang <locale> [--limit N] # Search by source/translated text
$T tm get <cache_key> --lang <locale> # Get single entry
$T tm add --lang <locale> --source <text> --translated <text> # Add entry
$T tm update <cache_key> --lang <locale> --translated <text> # Update translation
$T tm delete <cache_key> --lang <locale> # Delete single entry
$T tm delete --file <rel_path> --lang <locale> [--dry-run] # Delete all entries for a file
$T tm delete --match <query> --lang <locale> [--dry-run] # Batch delete by text match
$T tm export --lang <locale> [--format jsonl|json] # Export TM
$T tm compact --lang <locale> # Deduplicate & compact TM file
Q="node $SKILL_DIR/scripts/quality-cli.js"
$Q <source> <target> --target-locale <locale> # Single file check
$Q --dir <source_dir> <target_dir> --target-locale <locale> # Directory check
$Q <source> <target> --check structure,codeBlocks # Run specific checks only
$Q <source> <target> --skip terminology # Skip specific checks
$Q <source> <target> --json # JSON output
Check IDs: structure, codeBlocks, variables, links, terminology, untranslated, sections, frontmatterTranslated
P="node $SKILL_DIR/scripts/plan-cli.js"
$P init <source_dir> --lang <locale> # Initialize plan + run dir
$P status # Show overall progress
$P list --status pending --sort lines [--limit N] # Filter/list files
$P set <file_pattern> done [--notes "..."] # Update single file status
$P set --batch --from pending --to in_progress [--match "gateway/*"] # Batch update
$P add <file> [--status pending] # Add file to plan
$P add --match "gateway/*.md" # Add files by glob
$P scan [<target_dir>] [--lang <locale>] # Re-scan target completeness
$P sync --mode git --from <commit> --to HEAD # Detect source changes (git)
$P sync --mode hash # Detect source changes (hash)
$P clean [--all] [--keep-plan] [--dry-run] # Clean temp files
.i18n/no-translate.yamlTerms, headings, and sections to keep in the source language:
# Frontmatter keys whose values should be translated
# Default: [title, summary, description, read_when]
frontmatter_translate_keys:
- title
- summary
- description
- read_when
headings:
- text: "API Reference"
reason: "Industry standard term"
terms:
- text: "Gateway"
reason: "Product name"
sections:
- title: "Changelog"
reason: "Historical record"
.i18n/translation-consistency.yamlMandatory term translations:
translations:
install:
en: Install
zh: 安装
ja: インストール
ko: 설치
Location: .i18n/<lang>.tm.jsonl
Segment-level cache. On subsequent runs, prepare.js skips segments whose source text hash matches a TM entry and pre-fills the cached translation — only changed or new segments get <!-- i18n:todo --> markers.
To seed TM from existing translations:
node $SKILL_DIR/scripts/translate-cli.js seed <source_dir> <target_dir> --lang <locale>
Unified CLI for managing translation plans.
node $SKILL_DIR/scripts/plan-cli.js <command> [options]
PLAN="node $SKILL_DIR/scripts/plan-cli.js"
# 1. Initialize: create run dir, detect changes, scan targets
$PLAN init <source_dir> --lang zh
# 2. Check progress
$PLAN status
# 3. List files to translate (sorted by size)
$PLAN list --status pending --sort lines
# 4. After translating a file, validate it, get user confirmation if any warning exists, then mark it done
$PLAN set <file_pattern> done
# 5. Re-scan targets after batch completion
$PLAN scan
# 6. Clean up temp files when plan is complete
$PLAN clean
| Command | Purpose |
|---|---|
init | Create run dir, sync source changes, scan targets |
scan | Scan target files, compute translation completeness |
sync | Detect source file changes (git diff or hash mode) |
add | Add files to the plan (single, glob, or file list) |
status | Show overall progress with completeness metrics |
list | Filter/sort files by status, size, name |
set | Update file status (single or batch) |
clean | Remove temp files (run directories) |
# Git mode (default): compare two commits
$PLAN sync --mode git --from abc1234 --to HEAD
# Hash mode: compare file hashes against plan records
$PLAN sync --mode hash
Each init creates .i18n/runs/<timestamp>/ for temporary files (task-meta, chunks, manifest). clean removes the current run directory.
Weekly Installs
1
Repository
First Seen
1 day ago
Security Audits
Installed on
amp1
cline1
openclaw1
opencode1
cursor1
kimi-cli1
GitHub Actions 官方文档查询助手 - 精准解答 CI/CD 工作流问题
30,000 周安装