Anki 文档网站 docs-site 架构解析与多语言翻译协作指南
Anki 文档网站 docs-site 架构解析与多语言翻译协作指南【免费下载链接】ankiAnki is a smart spaced repetition flashcard program项目地址: https://gitcode.com/GitHub_Trending/an/anki本篇技术指南以仓库中的 docs-site/README.md 为线索系统梳理 Anki 官方文档网站docs-site的整体架构包括基于 Mintlify 的站点布局、docs.json导航与主题配置、多语言与 RTL 排版支持并给出从翻译.mdx页面、创建语言子目录到注册docs.json的完整协作流程。读完本文你将掌握 Anki 文档体系的组织方式能够以贡献者身份参与文档翻译与站点结构维护。docs-siteAnki 官方文档的统一门户docs-site/目录是整个 Anki 仓库中面向最终用户与贡献者的文档集合其定位在 docs-site/README.md 中写得很明确这是一个基于 Mintlify 构建的文档站点原文This directory contains Mintlify docs。与仓库根目录下另一套面向构建流程的 docs/Sphinx 风格、以.md文件组织不同docs-site 采用 Mintlify 生态的.mdx格式页面支持 JSX 组件如首页的 CardGroup/Card 卡片导航更适合渲染成交互式的现代文档门户。该目录覆盖六类文档主题与docs-site/index.mdx首页的六个卡片一一对应子目录内容定位入口页面docs-site/manual/桌面端 Anki 用户手册学习、编辑、模板、导入、偏好设置等manual/introdocs-site/ankimobile/iPhone / iPad 版 AnkiMobile 使用文档ankimobile/introdocs-site/faqs/支持与故障排查问答调度、同步、媒体、卡片模板等faqs/getting-helpdocs-site/addons/插件开发文档hooks、配置、调试、移植等addons/introdocs-site/developers/核心开发、构建、架构与 API 文档developers/developmentdocs-site/translators/翻译贡献者指南translators/intro此外还有 docs-site/releases/ 承载历代版本发布说明。docs-site/index.mdx的 frontmatter 中对该站点有一段概括性描述它将 Anki 的手册、FAQ、贡献者文档、翻译文档与发布说明统一集中到一个站点中a unified Mintlify proof of concept是 Anki 文档体系的单入口。站点骨架docs.json 全量配置解析Mintlify 站点的行为完全由 docs-site/docs.json 驱动这也是 README 明确要求翻译贡献者修改的配置文件。逐段拆解如下基础元信息与品牌主题{ $schema: https://mintlify.com/docs.json, name: Anki Docs, theme: mint, colors: { primary: #4B94D8, light: #6BADE8, dark: #2F75B5 }, favicon: /media/anki-logo.svg, logo: { light: /media/anki-logo.svg, dark: /media/anki-logo.svg }, fonts: { family: Hanken Grotesk } }name定义站点名会在浏览器标签与站点标题中呈现theme/colors控制 Mintlify 内置主题风格与主色三态亮色、浅色、深色色值favicon与logo均指向仓库内的 docs-site/media/anki-logo.svg该 SVG 同时被docs/_static/favicon.svg复用为构建版文档图标fonts.family指定全站正文字体 Hanken Grotesk。路径重定向redirectsredirects: [ { source: /getting-help, destination: /manual/getting-help }, { source: /when-problems-occur, destination: /manual/troubleshooting }, { source: /faqs/when-problems-occur, destination: /manual/troubleshooting }, { source: /manual/faqs, destination: /faqs/ }, { source: /faqs/ankiapp-is-not-part-of-the-anki-ecosystem, destination: /faqs/anki-knockoffs } ]重定向表用于平滑迁移历史 URL。例如旧的/getting-help被指向新的manual/getting-help说明文档经历过一次从扁平结构到manual/分组结构的重构而/faqs/ankiapp-is-not-part-of-the-anki-ecosystem被映射到faqs/anki-knockoffs则对应 FAQ 条目的改名。维护重定向是保证站外旧链接不 404 的关键手段。导航结构tabs / groups / pagesnavigation字段是 docs.json 体量最大的部分采用标签页 → 分组 → 页面的三层结构顶层tabs定义了站内主标签页。英文en站点下共有 7 个标签页Manual、AnkiMobile、FAQs、Add-ons、Developers、Translators、Releases每个 tab 内通过groups分组组织页面分组可嵌套如 Desktop Manual 下的 Platform Notes 再分出 Windows / MacOS / Linux 三个子组并分别配了iconmicrosoft、apple、bird最内层pages数组按顺序列出页面 ID如manual/intro、manual/getting-started与manual/等目录下的.mdx文件一一对应。分组与页面顺序直接决定侧边栏的渲染顺序因此新增文档页后必须在对应的pages数组中登记否则不会被站点收录——这一点与 README 中对翻译页的要求一致。多语言切换器与全局锚点navigation.languages数组按语言组织导航除了完整的英文配置外de、es、fr、it、id、uz、pl、pt、ru、uk、ar、ja、zh-Hans各语言均只有 Manual 一个标签页且目前大多只挂了一个intro页面对应各语言子目录下的manual/intro.mdx。这印证了 README 的说法新语言目录建立后需要在这里登记才能被 Mintlify 的语言切换器识别。global.anchors则定义了导航栏右上角的固定锚点分别指向 Anki 官网与 Anki 的 GitHub 仓库作为站点与主项目之间的互链入口。多语言文档体系与 RTL 排版支持docs-site 的语言支持分为两类目录内容语言目录ar/、de/、es/、fa/、fr/、id/、it/、ja/、pl/、pt/、ru/、uk/、uz/、zh-Hans/均以语言代码/manual/的子结构存放翻译页与 README 中 create one with the same structure (e.g.ru/manual) 的指导完全吻合英文内容目录manual/、ankimobile/、faqs/、addons/、developers/、translators/、releases/。以 docs-site/zh-Hans/manual/intro.mdx 为例可以看到一个典型尚未翻译的占位页正文只有一行说明本手册尚未翻译为简体中文并引导用户查看社区维护的简体中文版手册同时建议想参与翻译的读者阅读翻译文档。这种占位页模式可以视为各语言子目录的入口状态页翻译到位后会被逐步替换为真实内容。对于阿拉伯语ar/、波斯语fa/等从右向左书写的语言docs-site 通过 docs-site/rtl.js 在浏览器端动态处理排版方向var RTL_LANGS [ar, fa, he, ug, yi]; function applyDirection() { var lang window.location.pathname.split(/)[1]; if (RTL_LANGS.indexOf(lang) ! -1) { document.documentElement.classList.add(is-rtl); } else { document.documentElement.classList.remove(is-rtl); } }该脚本的要点通过 URL 第一段路径判断当前语言命中 RTL 列表阿拉伯语、波斯语、希伯来语、维吾尔语、意第绪语即为根元素添加is-rtlclass同时监听popstate浏览器前进/后退并包装pushState/replaceState确保在 Mintlify 这类 SPA 客户端路由切换语言时is-rtl状态能即时刷新避免页面残留错误的排版方向。这与仓库中 docs-site/style.css 及_static/custom.css共同构成文档站点的样式体系。参与网站翻译从 .mdx 到 docs.json 的完整流程按 docs-site/README.md 的 Translations 小节翻译工作流分两种情况为已有语言补充/修正翻译直接编辑对应语言子目录下的.mdx页面并提交 Pull Request。例如为俄语站点翻译某个页面就修改docs-site/ru/下的文件页面使用标准 Markdown 加 frontmatter 的.mdx格式顶部title字段用于站点标题显示。翻译时应保持与英文源页的路径结构一致如ru/manual/intro.mdx对应manual/intro.mdx便于维护者对照检查与持续同步。为全新语言创建子目录若你的语言尚无子目录需要三步创建目录按现有语言的结构创建例如ru/manual把翻译好的页面放进去修改 docs.json 登记语言在docs-site/docs.json的navigation.languages数组中新增一项参考现有语言条目如{ language: ru, tabs: [ { tab: Manual, groups: [ { group: Desktop Manual, pages: [ru/manual/intro] } ] } ] }把已翻译的页面 ID 列入pages提交 PRREADME 同时提示语言切换器的具体配置方法见 Mintlify 官方国际化文档Configure the language switcher。从仓库现状看14 种非英语语言的注册条目目前都只挂了intro单页新语言加入后同样可以按此最小配置起步再逐步扩充页面列表。值得交叉印证的是docs-site 下的 docs-site/translators/anki/manual.mdx 在介绍翻译手册时明确写道——翻译手册比翻译应用界面更复杂需要 fork 主仓库并与 Markdown 文件打交道You have to fork the main Anki repo and work with Markdown files并直接引用了本 README 的 Translations 小节作为操作指引。可见本小节描述的流程正是官方认可的仓库内翻译路径。许可证与贡献须知README 明确声明除非另有说明任何提交的文档修改均按CC BY-SA 4许可证授权the CC BY-SA 4 license。这对贡献者意味着提交到 docs-site 的文档内容默认采用知识共享署名-相同方式共享 4.0 协议该协议与仓库主代码的 AGPL 3.0 授权相互独立文档与代码的贡献采用不同的许可条款贡献前应知悉这一区别仓库内 docs-site/LICENSE 文件提供了完整的许可文本。延伸网站翻译与应用翻译的分工docs-site 的Translators标签页docs-site/translators/intro.mdx介绍了另一条平行的翻译渠道翻译Anki 应用界面走的是官方在线翻译接口需要申请账号且要求贡献者在留言中附带 I license any translations I contribute under the 3-clause BSD license 的授权声明——应用界面翻译与网站翻译采用不同的许可体系。而应用界面的翻译文件本体位于仓库 ftl/ 目录ftl/core/所有平台通用的文本与ftl/qt/仅桌面端使用的文本按 Fluent 格式组织例如ftl/core/scheduling.ftl、ftl/qt/addons.ftl等翻译系统的详细规则复数、变量、Fluent 语法见 docs-site/translators/anki/core.mdx开发者如何新增可翻译字符串见 docs-site/translators/anki/developers.mdx。两者的关系可以概括为文档网站翻译修改docs-site/下的.mdx并注册到docs.json应用界面翻译走在线接口并维护ftl/下的.ftl文件。二者共同构成了 Anki 社区的多语言协作体系而本文所讲的 docs-site/README.md 正是前者网站翻译的权威入口文档。小结docs-site/README.md 是 Anki 官方文档网站的入口说明定义了站点的 Mintlify 技术底座、CC BY-SA 4 许可协议与翻译协作规范站点的结构、导航、主题与多语言注册全部收敛在 docs-site/docs.json 一个配置文件中新增文档页或语言都必须同步维护它多语言支持采用语言代码子目录 docs.json 登记的模式阿拉伯语、波斯语等 RTL 语言由 docs-site/rtl.js 在客户端动态处理排版方向若你的语言尚未被覆盖按创建语言目录 → 翻译.mdx→ 注册 docs.json → 提交 PR四步即可为 Anki 文档体系贡献一个全新的语言版本。【免费下载链接】ankiAnki is a smart spaced repetition flashcard program项目地址: https://gitcode.com/GitHub_Trending/an/anki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考