翻译状态
FastAPI-fastkit 以多种语言发布文档,但这些翻译并不总是完全同步。本页面会说明哪些内容已经翻译、未翻译时会显示什么,以及您可以如何参与补充。
权威来源
英文(
en)是权威来源。 文档中描述的所有产品、CLI 与 API 行为,都先在英文文件中编写。其他语言是这些英文源的翻译,可能落后于某个版本。如果某个翻译页面与英文页面不一致,请以英文页面为准,直到翻译跟上为止。
英文文件位于 docs/en/。所有其他语言(docs/ko/、docs/ja/,……)都是翻译目标。
仓库根目录的 CHANGELOG.md 也属于这份英文权威来源。各语言的 changelog.md 页面可以作为入口页或包装页存在,但会刻意复用规范的英文版本历史,而不是维护一份独立的翻译版本。
各语言的完成度
下表中的数字是各语言目录中的 Markdown 页面数,相对于英文源的比例。它们反映的是仓库中实际存在的内容 —— 而不是语言切换器中显示的样子(下一节会解释)。
| 语言 | 状态 | Markdown 页面数 | 备注 |
|---|---|---|---|
🇬🇧 英文(en) |
✅ 权威来源 | 26 / 26 | 标准来源。 |
🇰🇷 韩文(ko) |
✅ 完成 | 26 / 26 | 该语言的所有页面都已存在。Phase 1：顶层页面 + 核心用户指南；Phase 2：其余用户指南 + 全部教程；Phase 3：贡献文档 + 参考文档。docs/ko/changelog.md 刻意复用规范的英文 CHANGELOG.md。 |
🇯🇵 日文(ja) |
✅ 完成 | 26 / 26 | 该语言的所有页面都已存在。Phase 1：顶层页面 + 核心用户指南；Phase 2：其余用户指南 + 全部教程；Phase 3：贡献文档 + 参考文档。docs/ja/changelog.md 刻意复用规范的英文 CHANGELOG.md。 |
🇨🇳 中文(zh) |
✅ 完成 | 26 / 26 | 该语言的所有页面都已存在。Phase 1：顶层页面 + 核心用户指南；Phase 2：其余用户指南 + 全部教程；Phase 3：贡献文档 + 参考文档。docs/zh/changelog.md 刻意复用规范的英文 CHANGELOG.md。 |
🇪🇸 西班牙文(es) |
✅ 完成 | 26 / 26 | 该语言的所有页面都已存在。Phase 1：顶层页面 + 核心用户指南；Phase 2：其余用户指南 + 全部教程；Phase 3：贡献文档 + 参考文档。docs/es/changelog.md 刻意复用规范的英文 CHANGELOG.md。 |
🇫🇷 法文(fr) |
✅ 完成 | 26 / 26 | 该语言的所有页面都已存在。Phase 1：顶层页面 + 核心用户指南；Phase 2：其余用户指南 + 全部教程；Phase 3：贡献文档 + 参考文档。docs/fr/changelog.md 刻意复用规范的英文 CHANGELOG.md。 |
🇩🇪 德文(de) |
✅ 完成 | 26 / 26 | 该语言的所有页面都已存在。Phase 1：顶层页面 + 核心用户指南；Phase 2：其余用户指南 + 全部教程；Phase 3：贡献文档 + 参考文档。docs/de/changelog.md 刻意复用规范的英文 CHANGELOG.md。 |
快照验证时间：2026-06-18；在 Phase 3(贡献文档 + 参考文档)完成后,已基于当前分支重新统计 zh 这一行。中文目前 26 个本地化页面全部就位,状态记为 ✅ 完成。 此表通过人工维护；如需在仓库根目录重新统计当前状态,请运行：
$ for loc in en ko ja zh es fr de; do
echo "$loc: $(find docs/$loc -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
done
若重新统计的结果与表格不一致,说明表格已过时 —— 请更新它(或开 PR / issue 报告差异)。
图例:
- ✅ 权威来源 —— 我们以此语言为基准撰写。
- 🟡 部分翻译 —— 已翻译部分页面；缺失的页面会回退到英文。
- 🔴 骨架 —— 语言切换器中存在该入口,但尚未提交任何翻译过的页面。站点会在翻译后的导航标签下渲染英文内容。
回退机制如何工作
文档站点使用 mkdocs-static-i18n 并开启 fallback_to_default: true。这意味着:
- 对每个翻译语言,MkDocs 只为该语言目录中存在的页面生成输出。
- 对每个不存在于某语言的页面,构建会回退到该页面的英文版本。
- 全站语言切换器始终列出所有已配置的语言,而不论每个语言实际包含多少页面 —— 因为构建会为每种情况生成可访问的 URL(本语言页面 → 必要时回退到英文)。
所以,语言切换器中的 🔴 骨架条目并不意味着文档已经翻译完成 —— 它只表示该语言的构建目标已经配置好。这样设计是有意为之(外部贡献者可以逐页翻译,而不会破坏链接结构),但也确实会让语言切换器看起来比实际内容更完整。
如何阅读站点
- 默认使用英文,若您希望获得最准确、最新的信息。
- 先查看本页确认状态,再决定是否使用翻译语言。如果状态是 🟡 或 🔴,而您打开了尚未翻译的主题,实际看到的会是英文回退内容,只是外层仍显示翻译后的导航标签。
如何提供帮助
当前的推进方式是：每种语言对应一个跟踪 issue,再把工作拆成若干阶段（phase）。例如 ko 会分为 Phase 1（顶层页面 + 核心用户指南）、Phase 2（其余用户指南 + 全部教程）和 Phase 3（贡献文档 + 参考文档）。每个阶段都会以独立 PR 落地,这样审阅者可以聚焦于一个完整的小范围,不必等到整套翻译全部完成。
如果您想贡献:
- 阅读 翻译指南,了解工作流程、工具与风格约定。
- 优先查找或创建对应语言的跟踪 issue。 若该语言已有一个开放的跟踪 issue,请在其中认领某个 phase(或 phase 内某个具体页面),以避免重复工作。如果尚不存在跟踪 issue,请创建一个,列出每个 phase 所属的页面,然后从 Phase 1 开始。
- 首选每个 phase 对应一份 PR。更小的“只修这一页”PR 同样欢迎 —— 尤其适合修复与英文不同步的内容 —— 但对于全新的语言翻译工作,按 phase 打包更有利于保持术语和交叉链接措辞的一致性。
- 提交 PR,将文件加入
docs/<locale>/<相同路径>下。请保持文件名与英文源完全一致,这样 MkDocs 才会自动识别。 - 将本地化的 changelog 页面视作规范英文
CHANGELOG.md的包装页或入口页,除非项目政策以后明确调整。 - 更新本页表格以反映新的完成度(可使用本页顶部的重新统计片段),并同步更新“快照验证时间”,方便审阅者确认上次对齐的时间点。如果该语言仍处于部分翻译状态,请在“备注”列注明已经完成到哪个 phase。
也欢迎报告翻译页面与英文源失同步的缺陷 —— 请同时附上英文页面与翻译页面的链接,便于分流。
为何还要保留 🔴 骨架语言
两个原因:
- 可预测的 URL 结构。 每种语言的
/<locale>/子树都已可访问,这样翻译页面一旦落地,链接从第一天起就是稳定的 —— 包括本指南里已经发布过的链接。 - 降低贡献门槛。 只翻译单页的贡献者无需再去修改 MkDocs 配置接入新的语言构建目标 —— 直接把文件放到对应位置即可。
如果某个语言长期处于 🔴 骨架且没有任何贡献,我们会重新评估是否保留它的构建目标。该决定会单独跟踪,不会由这个状态页面悄悄改变。