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 node commands below use $SKILL_DIR/scripts/.
Non-negotiable Rules
MUST use scripts only for prepare/checkpoint/merge/apply/quality/TM operations.
MUST NOT use any script, command, tool, or automation to batch-translate file contents or chunk contents.
MUST translate manually in-place: one target file at a time, or one chunk at a time.
MUST NOT read/translate multiple chunks in the same turn/request.
MUST run validation before marking anything done.
MUST NOT mark a file as done without validation results.
MUST NOT mark a file as done when validation reports any ERROR or any WARN unless the user explicitly confirms acceptance.
If validation reports any ERROR or WARN, MUST stop, show the validation output, and wait for user confirmation before .
What prepare does internally (you do NOT need to do these):
Loads .i18n/no-translate.yaml, .i18n/translation-consistency.yaml, and glossary
Loads Translation Memory (.i18n/<lang>.tm.jsonl)
Parses source markdown into segments via AST
Fills in cached translations from TM
Masks inline code, URLs, variables as %%Pn%% placeholders
Masks fenced code blocks as %%CB_<hash>%% placeholders — hash-based IDs derived from content, so they survive chunk reordering
Marks untranslated segments with <!-- i18n:todo --> markers
Large files (>3000 chars): auto-splits into chunks in .i18n/chunks/, splitting at segment boundaries
Writes skeleton + task metadata to .i18n/task-meta.json
Review the console output — it shows segments to translate, cached count, and any chunks generated.
Step 2: Translate [MUST]
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:
Translate ONLY the text between <!-- i18n:todo --> and <!-- /i18n:todo --> markers
Keep %%Pn%% and %%CB_<hash>%% placeholders exactly as-is — do NOT modify, delete, or reformat them
Do NOT touch segments without markers (they are cached translations)
You do NOT need to remove the markers — apply.js strips them automatically
MUST NOT use any script/tool to batch-generate translations for files or chunks
Example — before:
<!-- i18n:todo -->
See [configuration]%%P2%% for %%P1%% flag details.
<!-- /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:
Read only one chunk file
Translate only that chunk
Save it, run checkpoint, then move to the next chunk
Do NOT open, read, paste, diff, or translate multiple chunk files in the same turn/request
If multiple chunks are loaded together, context contamination is likely and the output becomes unreliable
This 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:
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.
Step 3: After Translate [MUST]
This step always happens after translation is complete. For chunked files, it happens only after merge.
prepare 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.
Manual Interfaces
The CLI still keeps the manual interfaces for debugging or step-by-step use:
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.
CLI Quick Reference
Three CLI tools. All invoked as node $SKILL_DIR/scripts/<cli>.js.
translate-cli.js — Translation Pipeline
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
quality-cli.js — Quality Checks
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
translations:
install:
en: Install
zh: 安装
ja: インストール
ko: 설치
Translation Memory
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.
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
