soia-pkm-translate-article-zh

Belongs to the "processing" stage of the SOIA personal knowledge management domain (soia-pkm-*): translate foreign-language articles from soia-pkm-clip-x / soia-pkm-clip-web and other archived outputs into the target language, landing them as standalone files without modifying the original.

Customer-readable description

What this skill can do

Three modes cover the full range of translation needs from "just get the gist" to "publication-level quality"; long articles are automatically chunked with terminology kept consistent across chunks; the output is always a new file alongside the original, never overwriting or polluting the original.

Customer wants	Skill will do	Customer can see
Quickly grasp the gist of a foreign-language article (quick)	Translate directly, no extra analysis	A literal-translation full text
A readable translation of an ordinary article (normal, default)	First analyze style/terminology/audience, then translate accordingly	A natural, fluent full translation
Important articles requiring publication-level quality (refined)	Analyze → translate → review (diagnosis only) → polish (apply corrections)	Diagnostic notes + final polished full text
Long articles (exceeding chunking threshold)	Use a mechanical script to chunk by headings/paragraphs, with the glossary running through all chunks	Number of chunks, glossary hit count, and ultimately still one merged complete translation
Translate English articles already archived in the vault	Inherit the original frontmatter, add `translated_from` and other fields	`<原文件名>-<目标语言>版.md`, in the same directory as the original file, with the original file remaining unchanged

How customers use it

Provide the file path to translate (typically a foreign-language article soia-pkm-clip-x / soia-pkm-clip-web archived in the vault), or paste the text directly; optionally specify target language / mode / audience (if not specified, use the config default or this skill's built-in default:zh-CN / normal / general）。
Before executing a translation on a file for the first time, the Agent must first report "will translate <文件> to <目标语言>, mode <quick/normal/refined>", and wait for customer confirmation, unless the customer has already explicitly said "just translate" or "no confirmation needed". If any one of target language/mode/audience comes from a config default rather than the customer's explicit specification this time, it counts as a "recommended input" and likewise requires this confirmation step.
The Agent determines or uses the customer-specified mode (quick / normal / refined), executing according to the three modes .
Long articles (exceeding chunk_threshold, default 4000 words) first run scripts/chunk_markdown.py mechanical chunking, with the glossary kept consistent across all chunks; short articles are translated in full directly in the current context. See details in references/chunk-workflow.md。
clip archive bilingual template caution (practical lesson 2026-07-10): clip-x/clip-web archived notes are a multi-section template of "summary + original + Chinese translation + my thoughts"; feeding the whole thing to the chunking script will count the existing Chinese translation toward the word count too—inflating the word count (measured 4431 vs. actual 1517 to be translated), and longer articles will be mistakenly judged as needing chunking with boundaries possibly spanning both the "original" and "existing translation" semantic regions. For such files: first extract only the ## 原文 section (up to the next ## up to the title) to a temporary file before feeding it to the script; whether chunking is triggered issegment to be translatedbased on word count, not on the whole document.
Translation alwayslands on disk first, reports after: the output <原文件名>-<目标语言>版.md lands in the same directory as the original file; the frontmatter inherits from the original and appends translated_from and other fields, and never overwrites the original file.
The final reply must give the client a complete receipt: mode, number of chunks, glossary hit count, output file path, remaining risks.

Dependencies and Installation

Installation (recommended: install the entire domain plugin, installing all skills in this repo at once):

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

When you only want this one skill, you can use the npx route. Note that the skill will land in the shared true source ~/.agents/skills; if the plugin is also installed, the same skill will appear as two indexes and each will drift, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-translate-article-zh -y

Dependency	Type	Installation / Configuration	What to do when missing
Python 3（stdlib）	Hard dependency	Built into the system or `brew install python3`	Without Python 3, `scripts/chunk_markdown.py`cannot run, degrading to no chunking and translating the whole document within the context (long-document quality will drop, and the client needs to be reminded)
PyYAML	Optional enhancement	`pip install pyyaml`	When missing, `scripts/resolve_config.py` can still locate the `config.yml` path, but cannot parse it structurally; the Agent switches to reading the file's text content directly
Obsidian vault (any structure)	Method reference, not a hard dependency	No separate installation required	This skill can translate any Markdown/plain text file and does not require the file to be inside a vault; only when vault frontmatter and filing conventions are involved does it reference the vault context
`soia-pkm-clip-x` / `soia-pkm-clip-web`	Upstream source, not a hard dependency	No installation required, unless the client needs to archive before translating	It is just a common input source; this skill does not call or modify any files of these two skills

Configuration conventions:

~/.config/soia-skills/soia-pkm-translate-article-zh/config.yml
SOIA_PKM_TRANSLATE_ARTICLE_ZH_CONFIG_FILE=<custom-config-path>

For examples, see config.example.yml：target_language / mode / audience / style / chunk_threshold / chunk_max_words / glossary(inline glossary) are all plaintext preferences and contain no secrets.
If the client does not need custom preferences, config.ymldoes not need to be created; this skill will use the built-in defaults (zh-CN / normal / general / storytelling / 4000 / 5000）。
Priority: CLI parameters (the target language/mode/audience/terminology explicitly stated by the client this time) > process environment variables > private config.yml > this skill's built-in defaults.
It does not need to and should not read any API key, cookie, session, or account credentials—this skill only processes text files provided by the client.

WorkBuddy is loaded as a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。

Logging and Completion Receipt

Every execution must let the client see the entire process of determination, confirmation, chunking, and output. Minimum receipt format:

完成：<一句话说明本次翻译了什么文件、到什么语言、什么模式>。

日志摘要：
- 确认记录：<本次是否走了首次确认、客户确认内容；用户已明说跳过则写"客户已要求跳过确认">
- 模式：<quick / normal / refined，以及判定依据>
- 分块：<是否触发分块；触发则写块数与每块词数；未触发写"未触发分块，整篇在单次上下文内翻译">
- 术语表：<config 术语表命中次数 + 本次从原文抽取的会话术语数量；无术语表则写"未配置术语表，仅按上下文保持一致">
- 审校（仅 refined）：<跨块术语/人名/风格漂移检查结果；quick/normal 写"不适用">

文件变化：
- 新建：<绝对路径，`<原文件名>-<目标语言>版.md`>
- 未改动：<原文件路径，确认未被覆盖>

问题与下一步：
- <图片语言不匹配提醒 / 需要客户核对的译名或术语 / normal 模式可回复"继续润色"升级为 refined；没有则写"无，可直接使用产出">

Three Modes

Mode	Steps	Applicable scenarios	Trigger words
quick	Direct translation	Short texts, informal content, wanting to first understand the gist	"quick translate", "quick", "just translate it directly"
normal(default)	Analysis (style/terminology/audience) → translation	General articles, blogs, daily archiving	Default when no mode is specified
refined	Analyze → Translate → Review (diagnosis only) → Polish (apply corrections)	Publication-grade quality, important documents, content to be published externally	"refined translation," "refined," "proofread translation," "polished translation"

quick mode does not chunk—regardless of length, it translates the whole text directly, prioritizing speed; when a long text goes through quick, remind the client "quick mode does not handle terminology consistency; for long texts, normal is recommended."
After normal is complete, if the client replies "continue polishing," start directly from the refined review step without re-analyzing or re-translating.
For the detailed checklist of review/polishing in refined mode, see references/refined-review-checklist.md。

Mechanical chunking of long texts

scripts/chunk_markdown.py is a pure Python stdlib script that does only mechanical work—splitting chunks by heading level and paragraph boundaries, without making any translation judgments:

python3 scripts/chunk_markdown.py --file <path.md> --json
python3 scripts/chunk_markdown.py --file <path.md> --threshold 4000 --max-words 5000 --json
python3 scripts/chunk_markdown.py --selftest

Default threshold 4000 wordstriggers chunking; when not triggered, the entire text is returned as a single chunk and translated directly in the current context.
After triggering, the per-chunk limit is 5000 words, grouped by heading, and over-limit subsections are further split by paragraph/line boundaries; code blocks are always kept intact and will never be cut in the middle.
--json outputs a chunk list (each chunk's index / words / heading); when physical files are needed, add --output-dir <临时目录>, which will write to <目录>/chunks/ under chunk-NN.md(and frontmatter.md, if the source text has frontmatter).
The translation itself is always done in the LLM context of the Agent invoking this skill; the script does not call any translation API.
For the complete workflow (term extraction, session glossary, chunk-by-chunk translation, merging, intermediate file cleanup), see references/chunk-workflow.md。

Terminology consistency

The glossaryin config (source text → fixed translation) is the first layer of terminology basis for this skill; when translating long texts in chunks, first read through the entire text to extract proper nouns and recurring terms, and merge them with the config glossary into this session'ssession glossary, which runs through the translation of all chunks, rather than deciding the translation separately for each chunk.
The review step in refined mode specifically checks cross-chunk terminology, personal names, and style drift—these are the places where chunked translation is most prone to problems; for the checklist, see references/refined-review-checklist.md。
quick mode does not merge glossaries (pursuing speed); normal mode does terminology merging but does not do dedicated cross-chunk review (unless the client later requests "continue polishing" to upgrade to refined).

Connecting with the vault

Typical scenario: translating soia-pkm-clip-x / soia-pkm-clip-web English articles already archived in the vault, but this skill does not require the input file to be inside the vault; any Markdown/plain text file can be translated.
Output filename:<原文件名>-<目标语言版>.md, placed in the original file'ssame directory. Mapping from target language to filename suffix:zh-CN/zh/zh-Hans → 中文版；en → 英文版；ja → 日文版；ko → 韩文版; for other languages use <目标语言代码>版(e.g., fr版）。
Never overwrite the original file—the output is always a new file; if a translated file with the same name already exists, first inform the client and wait for confirmation on whether to overwrite the old translation (this is a risk action of the overwrite type and must be confirmed first).
frontmatter rules: fully preserve all frontmatter fields of the original file, and append at the end:

translated_from: <原文件名或相对路径>
translated_language: <目标语言代码，如 zh-CN>
translated_at: <YYYY-MM-DD>

Do not rename or delete existing fields; if the body already has a level-one heading (H1) and the original frontmatter has title，title Fields are kept as-is and are not forced to sync with the translated headings.

Delivery order

Forward testing

Before handling a new format or a long document for the first time, first use a small-scope or fixture input to verify chunk boundaries, frontmatter preservation, terminology consistency, non-overwriting output, and empty-body failure handling; a command returning 0 does not mean the translation quality has been verified.

Write to disk first, report afterward: the output file must first be written to disk and pass content checks (the file actually exists, the frontmatter fields are complete, and the body is non-empty), and only then may a completion receipt be sent to the client. It is not allowed to first describe it as "completed" and then fill in the file afterward.

Boundaries and limitations

This skill does not call any external translation API or network service; the chunking script is purely local mechanical processing, and translation is performed by the Agent invoking this skill within its own context.
This skill does not handle credentials such as accounts, cookies, or sessions—it only handles file paths or text content provided by the client.
Text within images themselves (covers, screenshots, charts) is outside the scope of this skill's translation; after completing the translation, do a lightweight reminder as usual: list images that may still be in the source language and that the client needs to decide whether to localize, without handling the images on your own.
The glossary and session context only guarantee consistency "within the same translation task" and do not automatically accumulate memory across files or tasks; a glossary that needs long-term maintenance should be written by the client into config.yml of glossary。

Completion receipt

The receipt includes:

What was done — a one-sentence summary of the files translated in this task, the target language, the mode, and whether chunking was triggered.
File changes — the full path of the newly created translated file; clearly state that the original file was not modified.
Next steps — in normal mode, remind the client that they can reply "continue polishing" to upgrade to refined; in refined mode, remind the client to check the questionable translated names/terms marked in the review checklist; if there are reminders about image language mismatches, list them as well.