| name | blog-post-translation |
| description | 为 yuanlehome/blog 中的英文或中英混杂技术文章提供可复用的“翻译 + Markdown/MDX 修复 + 内容清理 + 渲染稳定性修复”流程， 确保技术含义不变、Astro/MDX 渲染稳定、仓库质量门禁可通过。 Use this when users ask to translate imported English posts, clean mixed-language Markdown/MDX articles, fix article rendering issues, or prepare blog content for CI.
|
| license | ISC (repo LICENSE) + project conventions in this file |
Blog Post Translation Skill
本 Skill 面向 yuanlehome/blog 仓库内的文章翻译与修复任务，尤其适用于导入后的英文文章、机器翻译残留稿、以及中英混杂的 Markdown/MDX 内容。
核心目标只有一个：在不改变技术事实、结论和代码含义的前提下，把文章处理成自然中文、结构正确、渲染稳定、可通过仓库质量检查的内容。
Canonical references
执行前优先以这些文件为准：
.github/workflows/copilot-fix-posts.yml.skills/blog-dev-standards/SKILL.mddocs/architecture.mddocs/ci-workflow.mdscripts/README.mdREADME.md
若这些文件与通用经验冲突，以仓库文件为准。
Use when
- 用户要求把英文技术文章翻译成中文
- 用户要求修复导入文章中的中英混杂、漏翻、翻译腔
- 用户要求清理 Markdown/MDX 结构问题，使文章能在 Astro 中稳定渲染
- 用户要求批量修文、补标题层级、修锚点、清理引用或清理非正文垃圾
Required inputs
开始前必须确认以下至少一项：
- 明确的文章路径，例如
src/content/blog/...md 或 src/content/blog/...mdx
- 或者用户直接粘贴了待翻译内容
如果任务是改仓库文件，默认只允许改用户明确指定的文章文件；除非任务本身明确要求，否则不要顺手修改脚本、组件、样式或其他内容文件。
Non-negotiable constraints
1. 技术含义绝不能变
- 不引入新观点、新结论、新来源
- 不改动代码、命令、日志、API 名称、类名、函数名、变量名、路径、配置字段、版本号、benchmark 数字、URL 的含义
- 只在必要时修正文中对这些硬实体的明显笔误
2. 必须逐行完整处理
- 不能只翻译摘要或部分章节
- 禁止输出“略”“保持不变”“见上文”“只改关键段落”这类省略式结果
- 必须像审计一样从头到尾检查标题、段落、列表、代码块、锚点、公式和引用
3. 最小必要改动
- 能局部修就不整段重写
- 能保留原结构就不重排
- 重排标题或段落时，必须有明确的结构或渲染原因
4. 最终质量门禁不能退让
涉及仓库文件时，目标是让这些命令可通过：
npm run checknpm run testnpm run test:e2enpm run lint
Default workflow
Step 0. 确认边界
- 确认目标文件存在且为
.md 或 .mdx
- 若路径不存在、不可写、或文件类型不符，立即停止并明确报告“路径 + 原因 + 停止动作”
- 若用户给了多篇文章，按文件逐一处理，不要混淆范围
Step 1. 建立原文事实
- 先通读全文，判断文章类型：教程、工具介绍、论文翻译、新闻摘要、经验总结等
- 识别不能翻译的硬实体：代码、命令、日志、API、配置、路径、文件名、参数、输出样例
- 识别需要重点清理的区域：TOC 残留、社交引流、页脚模板、引用标记、孤立锚点、断裂列表
Step 2. 执行翻译
- 所有英文自然语言正文、列表项、图注、引用说明、过渡句、注释性描述都要翻成自然中文
- 首次出现的重要术语可使用“中文（English）”，后续优先中文
- Kubernetes、Docker、PyTorch、CUDA 这类专有名词可直接保留英文
- 避免翻译腔，改成自然中文技术表达，但不能改变事实
Step 3. 修复 Markdown/MDX 结构
- 保证全文只有一个 H1
- 标题层级必须连续，不允许
## 后直接跳到 ####
- 所有 code fence 必须闭合，且尽量补充正确语言标记
- 修复标题、段落、列表、引用块前后的空行问题
- 修复列表缩进和引用断裂，避免 Astro/MDX 解析异常
Step 4. 清理非正文垃圾
- 删除正文内手写 TOC、目录、页内导航残留
- 删除订阅、点赞、分享、关注、打赏、二维码、页脚导航、转载模板、推广段落
- 作者 bio、社交链接、重复原文链接可按重复度保守清理
- 参考资料可去重，但不能清理到完全不可追溯
Step 5. 修复自洽性
- frontmatter
title 与正文 H1 不一致时统一
- 所有
[text](#anchor) 必须能跳转到文内真实标题
- 修改标题后，联动更新页内锚点链接
- 孤立半句、断裂锚点、截断说明都要修成自然完整句
Step 6. 验证与交付
- 至少自查标题层级、盘古空格、标点、代码块闭合、锚点跳转、引用清理、公式形式
- 若任务在仓库内执行，按需要运行相关检查命令
- 向用户反馈时，说明改了什么、为什么改，以及是否已完成验证
Translation rules
必须翻译
- 英文自然语言段落
- 英文列表项
- 图注、表注、引用说明
- 承上启下的说明句
- 对代码或实验结果的文字解释
禁止翻译
- 代码块内容
- 行内代码
- Shell 命令
- 日志输出
- API 名称、类名、函数名、变量名
- 路径、文件名、配置字段、CLI 参数
- URL、版本号、哈希值、标识符
术语处理
- 首次出现可写为“张量核心（Tensor Cores）”
- 后续优先写中文，除非英文更常见或更准确
- 不为追求中文化而硬翻项目名、库名、协议名
Pangu and punctuation rules
- 中文与英文单词、数字、数学符号之间补一个半角空格
- 正文中文优先使用全角标点：
，。？！：
- 代码、URL、路径、配置字段、行内代码内的空格和标点不要乱改
示例：
- 正确：
使用 React 开发了 5 个页面。
- 错误：
使用React开发了5个页面。
Markdown/MDX stability rules
标题
- 整篇文章只允许一个
#
- 不要用粗体、列表项伪装标题
- 标题前后保留合理空行
代码块
- fence 必须成对闭合
- 尽量为 fence 补正确语言，如
bash、yaml、json、python、ts、tsx
- 不改代码本身语义
列表与引用
- 修复嵌套缩进
- 修复空行导致的列表断裂
- 修复引用块与列表交错造成的解析问题
段落边界
- 标题前后、列表前后、代码块前后需要有足够空行
- 清理 tab/空格混用带来的异常
Formula rules
- 特别短的公式改成行内公式，例如
$x$、$ab$、$k^2$
- 只有长公式、多行推导、对齐展示时才保留块级公式
- 公式改写只能调整展示形式，不能改变数学含义
Citation cleanup rules
如果文章属于论文、学术解读、arXiv/ACL/NeurIPS 等类型，执行以下规则：
- 删除文中的作者年份式引用、方括号引用、编号引用
- 删除文末
References、Bibliography、参考资料 等引用列表
- 删除后若句子残缺，做最小必要改写，使中文语义完整
- 若某个 URL 或 DOI 是唯一可访问来源，可保留为“原文链接”或“项目链接”
Deliverable expectations
向用户汇报结果时，默认包含这些信息：
- 已处理的文件路径
- 主要修复类别：翻译、标题层级、渲染修复、锚点修复、非正文清理、引用清理、公式调整
- 是否运行了检查命令；若未运行，要明确说明原因
- 是否存在未解决风险，例如原文歧义、图片资源缺失、外链失效
Quick self-check
