soia-pkm-translate-article-zh

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

Client-readable description

What this skill can do

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

What the client wants	What the skill does	What the client can see
Quickly understand the gist of a foreign-language article (quick)	Translate directly, without extra analysis	A direct-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
Publication-grade quality for important articles (refined)	Analyze → translate → review (diagnose only) → polish (apply corrections)	Diagnostic notes + final polished full text
Long texts (exceeding the chunking threshold)	Use a mechanical script to split by headings/paragraphs, with the glossary running through all chunks	Number of chunks, glossary hit count, and ultimately still a single 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 the client uses it

Provide the path of the file to translate (typically soia-pkm-clip-x / soia-pkm-clip-web foreign-language articles archived in the vault), or paste the text directly; also mention the target language / mode / audience (if not specified, use the config default or this skill's built-in default:zh-CN / normal / general）。
Before translating a given file for the first time, the Agent must first report "will translate <文件> into <目标语言>, mode <quick/normal/refined>", and wait for client confirmation, unless the client has already explicitly said "just translate" or "no confirmation needed". If any one of the target language/mode/audience comes from a config default rather than being explicitly specified by the client this time, it counts as a "recommended input" and likewise requires this confirmation step.
The Agent determines or uses the client-specified mode (quick / normal / refined), and executes according to the three modes .
For long texts (exceeding chunk_threshold, default 4000 words), first run scripts/chunk_markdown.py mechanical chunking, with the glossary running through all chunks to stay consistent; short texts are translated in full directly in the current context. For details, see references/chunk-workflow.md。
clip archive bilingual template notes (practical lessons 2026-07-10)：clip-x/clip-web archived notes use a "summary + original text + Chinese translation + my thoughts" multi-section template. Feeding the whole thing to the chunking script counts the existing Chinese translation as words too—inflated word count (measured 4431 vs actual to-translate 1517)—and longer articles get misjudged as needing chunking, with boundaries possibly spanning the two semantic regions of "original text" and "existing translation." For such files: first extract only the ## 原文 section (up to the next ## heading) into a temporary file before feeding the script; whether chunking is triggered should be based on theto-translate sectionword count, not the whole document.
Translation alwayswrites to 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, chunk count, glossary hit count, output file path, remaining risks.

Dependencies and installation

Install this skill (single skill):

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

Dependency	Type	Install / configure	What to do if missing
Python 3（stdlib）	Hard dependency	Built into the system or `brew install python3`	Without Python 3, `scripts/chunk_markdown.py`cannot run; it degrades to no chunking and translating the whole document in context (long-text 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 needed	This skill can translate any Markdown/plain text file and does not require the file to be inside a vault; only when dealing with vault frontmatter and placement conventions does it reference vault context
`soia-pkm-clip-x` / `soia-pkm-clip-web`	Upstream source, not a hard dependency	No installation needed, unless the client needs to archive before translating	It is only a common input source; this skill does not call or modify any files of these two skills

Configuration conventions:

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

See sample 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 built-in defaults (zh-CN / normal / general / storytelling / 4000 / 5000）。
Priority: CLI arguments (the target language/mode/audience/terminology explicitly specified 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.

Logs and completion receipt

Every execution must let the client see the whole process of judgment, 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 get the gist	"quick translate" "quick" "just translate it"
normal(default)	Analyze (style/terminology/audience) → translate	General articles, blogs, everyday archiving	Default value when no mode is specified
refined	Analyze → Translate → Review (diagnose only) → Polish (apply corrections)	Publication-grade quality, important documents, content to be released 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 that "quick mode does not handle terminology consistency, and normal is recommended for long texts".
After normal is complete, if the client replies "continue polishing", start directly from the review step of refined, without re-analyzing or re-translating.
For the detailed checklist of the review/polish steps 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 only does 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 whole 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 sections exceeding the limit are further split by paragraph/line boundaries; code blocks are always kept whole and will never be cut in the middle.
--json outputs a chunk list (index / words / heading for each chunk); when physical files are needed, add --output-dir <临时目录>, which will write under <目录>/chunks/ the files chunk-NN.md(and frontmatter.md, if the source text has frontmatter).
The translation itself is always completed in the LLM context of the Agent invoking this skill; the script does not call any translation API.
For the complete workflow (terminology 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 a long text 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 for each chunk separately.
The review step of refined mode specifically checks cross-chunk terminology, personal names, and style drift—this is 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 perform dedicated cross-chunk review (unless the client later requests "continue polishing" to upgrade to refined).

Integration with vault

Typical scenario: translating soia-pkm-clip-x / soia-pkm-clip-web an English article 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 same directory as the original filesame 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, inform the client first and wait for confirmation on whether to overwrite the old translation (this is an overwrite-type risky action 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-1 heading (H1) and the original frontmatter has title，title Fields are kept as-is and are not forcibly synchronized to 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 completed 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 light 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

After executionmustoutput to the user (do not do it silently):

What was done — a one-sentence summary of the files translated this time, 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.