blog-post-translation

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.md
• docs/architecture.md
• docs/ci-workflow.md
• scripts/README.md
• README.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 check
• npm run test
• npm run test:e2e
• npm 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

• 我只修改了用户指定的文章文件或用户给出的文本
• 我保留了代码、命令、路径、API、配置字段等硬实体含义
• 我逐行检查了标题、段落、列表、代码块、锚点、公式、引用
• 我处理了盘古空格和中文标点，但没有误伤代码或 URL
• 我删除了手写 TOC、引流、页脚模板等非正文垃圾
• 若是论文类文章，我已清理全文引用标记与引用段
• 我确认文章结构与 Markdown/MDX 渲染是稳定的
• 若任务涉及仓库文件，我已尽量完成并说明质量检查结果