简诗 AI MkDocs 文档翻译
将以下提示词粘贴到你的 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的译文
执行步骤
- 先向用户确认目标语言和 locale code
- 执行
git checkout -b docs-translation-创建新分支 - 在
docs/docs/下按语言代码建目录,依次翻译每个文件 - 在
docs/docs/includes/下重复同样的流程 - 校验翻译文件数量与源文件数量是否一致,若有遗漏则继续未完成的部分
- 更新
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 逐语言产出镜像目录,不希望译文夹带格式修复
- 独立翻译者:承接技术文档本地化项目,需要忠实翻译且不擅自改标题层级或空行