Agent Skills
返回列表
简诗 AI MkDocs 文档翻译

简诗 AI MkDocs 文档翻译

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md ,安装 @user_fccf428b/mkdocs-translations。

技能介绍

为什么需要这个技能

把 MkDocs 站点推向多语言时,最常见的做法是手工复制一份 docs/en,然后逐篇翻译。问题在于这份工作琐碎且容易出错:目录层级要保持一致,include 引用要改到新路径,mkdocs.yml 里的 i18n 配置要补全,而任何一处遗漏都可能让构建静默失败或导航显示成英文原文。更麻烦的是,翻译过程中很容易顺手去修格式、调标题层级,最终 diff 里混入大量与翻译无关的改动。

这个技能的目标就是把这件事变成一条可重复的流水线:源目录不改动,翻译结果写入独立的语言目录,工程配置同步更新,整个过程无需人工确认每一步。

它如何工作

核心能力

  • 以用户提供的 locale code 作为唯一语言标识,贯穿目录名、输出路径和 Mkdocs 配置,避免混用
  • 按固定顺序枚举 docs/docs/en 与 docs/docs/includes/en 下的全部文件,逐个翻译且不中途停止
  • 完整镜像原有目录与文件结构,文件名保持不变
  • 保留标题、代码块、YAML metadata、链接等全部 Markdown 格式
  • 自动改写 include 引用,例如 includes/en/introduction-event.md 映射到 includes/es/introduction-event.md
  • 在 mkdocs.yml 的 i18n 插件中新增语言条目,并补上 nav_translations 与 admonition_translations 的译文

执行步骤

  1. 先向用户确认目标语言和 locale code
  2. 执行 git checkout -b docs-translation- 创建新分支
  3. 在 docs/docs/ 下按语言代码建目录,依次翻译每个文件
  4. 在 docs/docs/includes/ 下重复同样的流程
  5. 校验翻译文件数量与源文件数量是否一致,若有遗漏则继续未完成的部分
  6. 更新 mkdocs.yml 完成配置

适用边界与注意点

翻译涉及技术措辞时统一采用业界通用译法,不会自行发明术语。技能只做翻译这一件事:它不会去修 lint 问题、不会补全图片 alt 文本、不会调整标题层级或空行,也不会对这些格式问题发表任何意见。如果原文存在排版缺陷,译文会原样保留。

这也意味着翻译质量高度依赖源文档本身。代码注释里的字符串、front matter 中的品牌词、图片文件名都需要在源文件中已经处理妥当。分支创建后不会自动提交,后续的 commit 和 PR 流程需要你自行控制。

适用场景

适合已有成熟英文文档站、希望新增一种目标语言的团队。不适合需要同时产出多语言、或需要专业审校的正式出版物场景。


Translated using GitHub Copilot and GPT-4o.

使用场景

  • 开源维护者要把文档站英文内容翻译为西班牙语,输出到 docs/es 并保持目录结构不变
  • 文档里大量使用 includes/en/*.md 复用片段,翻译后需把 include 路径统一改写到目标语言目录
  • 正在做多语言改造,需要在 mkdocs.yml 的 i18n 插件中新增语言条目并补全导航与提示框译文
  • 已有完整英文文档库,想新增巴西葡萄牙语版本,要求逐文件翻译且不改动原文排版

适合人员

  • 开源项目维护者:英文文档已稳定,想把整站翻译为新的目标语言并保持目录结构一致
  • 文档工程师:负责多语言站点改造,需要批量翻译 includes 片段并同步导航与 admonition 文案
  • 技术写作:为 MkDocs 项目按 locale code 逐语言产出镜像目录,不希望译文夹带格式修复
  • 独立翻译者:承接技术文档本地化项目,需要忠实翻译且不擅自改标题层级或空行