Belongs to the SOIA personal knowledge management domain (
soia-pkm-*) "processing" stage: translating foreign-language articles in archived outputs such assoia-pkm-clip-x/soia-pkm-clip-webinto 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 next to the original, never overwriting or polluting the original.
| Client wants | Skill will do | Client can see |
|---|---|---|
| Quickly grasp the gist of a foreign-language article (quick) | Translate directly, without extra analysis | A literal full-text translation |
| A readable translation of an ordinary article (normal, default) | First analyze style/terminology/audience, then translate accordingly | A natural, fluent full-text translation |
| Publication-grade quality for important articles (refined) | Analyze → translate → review (diagnose only) → polish (apply corrections) | Diagnostic notes + final polished full-text translation |
| 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-webforeign-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
<文件>to<目标语言>, 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 runscripts/chunk_markdown.pymechanical 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 multi-section template of "summary + original text + Chinese translation + my thoughts". Feeding the whole piece to the chunking script counts the existing Chinese translation as words too—inflating the word count (measured 4431 vs. the real to-be-translated 1517)—and longer articles get mistakenly judged for chunking, with boundaries potentially spanning the two semantic regions "original text" and "existing translation". For such files: first extract only the
## 原文section (up to the next##heading) into a temporary file before feeding it to the script; whether chunking is triggered should be based on theto-be-translated sectionword count, not the whole document. - Translation alwayslands on disk first, reports after: the output
<原文件名>-<目标语言>版.mdlands in the same directory as the original file, frontmatter inherits from the original and appendstranslated_fromand other fields, and the original file is never overwritten. - 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
Install this skill (single skill):
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-translate -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.pycannot run, and it degrades to no chunking, translating the whole document within context (quality will drop for long texts, and the client should be warned) |
| PyYAML | Optional enhancement | pip install pyyaml |
If missing, scripts/resolve_config.py can still locate the config.yml path, but cannot parse it structurally; the Agent instead reads 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; vault context is only referenced when vault frontmatter and placement conventions are involved |
soia-pkm-clip-x / soia-pkm-clip-web |
Upstream source, not a hard dependency | No installation needed unless the client needs to archive first and then translate | 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-open-skills/soia-pkm/soia-pkm-translate/config.yml
SOIA_PKM_TRANSLATE_CONFIG_FILE=<custom-config-path>
- See config.example.yml:
target_language/mode/audience/style/chunk_threshold/chunk_max_words/glossaryfor examples (inline glossary) are all plaintext preferences and contain no secrets. - If the client does not need custom preferences,
config.ymlcan be left uncreated, and this skill will use built-in defaults (zh-CN/normal/general/storytelling/ 4000 / 5000)。 - Priority: CLI parameters (the target language/mode/audience/glossary explicitly specified by the client this time) > process environment variables > private
config.yml> this skill's built-in defaults. - No API key, cookie, session, or account credential needs to be or should be read—this skill only processes text files provided by the client.
Logging and Completion Receipt
Every execution must let the client see the entire 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 grasp the gist first | "Quick translate", "quick", "just translate it directly" |
| normal(default) | Analysis (style/terminology/audience) → translation | General articles, blogs, everyday archiving | Default value when mode is not specified |
| refined | Analyze → Translate → Review (diagnosis 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 entire text directly, prioritizing speed; when long texts go through quick, remind the client that "quick mode does not handle terminology consistency, and normal is recommended for long texts".
- After normal completes, 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 for 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 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; sections exceeding the limit are further split by paragraph/line boundaries; code blocks are always kept intact and will never be cut in the middle.
--jsonoutputs a chunk list (index / words / heading for each chunk); when physical files are needed, add--output-dir <临时目录>, which will write under<目录>/chunks/under writechunk-NN.md(andfrontmatter.md, if the original text has frontmatter).- 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 the 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 — 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 (prioritizing 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-webEnglish 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 an overwrite-type risky action and must be confirmed first).
- frontmatter rule: 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 retained as-is and are not forced to sync to the translated headings.
Delivery order
Forward testing
Before handling a new format or long text for the first time, first use a small-scale or fixture input to verify chunk boundaries, frontmatter retention, terminology consistency, non-overwriting output, and handling of empty-body failures; a command returning 0 does not mean the translation quality has been verified.
Write to disk first, report afterward: output files must first be written to disk and pass content verification (the file actually exists, the frontmatter fields are complete, and the body is nonempty), and only then send a completion receipt to the client. It is not allowed to first describe it as "completed" and then fill in the files 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.
- The text in the images themselves (covers, screenshots, charts) is not within the translation scope of this skill; after completing the translation, do a lightweight reminder as usual: list images that may still be in the source language and require the client to decide whether localization is needed, and do not handle the images without authorization.
- The glossary and conversation 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.ymlofglossary。
Completion receipt
After executionmustoutput to the user (do not silently finish):
- 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(s); explicitly 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 is an image language mismatch reminder, list it as well.