FastAPI 文档多语言生态：LLM 驱动的自动化翻译机制与贡献指南

FastAPI 文档多语言生态：LLM 驱动的自动化翻译机制与贡献指南

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

本文基于 docs/en/docs/translations.md 展开，完整剖析 FastAPI 当前采用的"LLM 自动翻译 + 母语社区审核"文档多语言机制：包括每种语言专属的llm-prompt.md提示词如何设计与改进、如何为一种全新语言申请官方翻译，以及配套的自动化流水线（翻译生成、过期检测、缺失补齐、PR 提交）。读完你既能掌握在 FastAPI 仓库中参与文档翻译贡献的完整路径，也能理解这套可复用的"提示词工程 + 人工把关"多语言工作流在代码层面的落地方式。

背景：FastAPI 的文档翻译是一次工程实践而非简单人工搬运

FastAPI 官方文档支持多种语言。在本仓库快照中，docs 目录下除了英文源文档 docs/en/docs，还维护着 12 个语种目录（de、es、fr、hi、ja、ko、pt、ru、tr、uk、zh、zh-hant），其中 zh 与 zh-hant 分别对应简体中文与繁体中文；每个语种目录下都有一份独立的llm-prompt.md提示词文件，以及一套对应语言的 Markdown 页面（本快照中各语种均为 123 个页面）。

与"翻译 PR 由志愿者逐篇人工翻译"的传统模式不同，docs/en/docs/translations.md 明确指出：

Translation pull requests are made by LLMs guided with prompts designed by the FastAPI team together with the community of native speakers for each supported language.

也就是说，翻译 PR 由LLM 生成，而 LLM 的行为由 FastAPI 团队与各语言母语社区共同设计的提示词来引导。母语者的工作重心从"逐字翻译"转向了"设计提示词 + 审核产出"，这是该文档贯穿始终的核心思想。

每种语言一份 LLM 提示词：llm-prompt.md

每个语种目录（即docs/<lang>/）中都包含一个llm-prompt.md，其中存放针对该语言的专属提示词。例如西班牙语的提示词位于 docs/es/llm-prompt.md。

以西班牙语提示词为例，它主要约定两类关键约束：

1. 语言风格基调：例如要求使用非正式语法（用 "tú" 而非 "usted"），命令式标题/说明保留命令式语态（"Edit it" → "Edítalo"）。
2. 术语对照表：大量技术词汇指定了必须使用的译法或保留英文原词，例如：
   • framework不译作 "marco"；
   • path operation function、path operation、path、query、cookie、header等 HTTP/框架术语保留英文；
   • type hints/type annotations→anotaciones de tipos，library→paquete（而非 "biblioteca"），docs→documentación（而非 "documentos"）；
   • Release Notes、Semantic Versioning、JSON Schema、OAuth2 Scopes、Machine Learning等专有名词直接保留。

这类术语表的价值在于：保证同一语言内术语翻译长期一致，避免不同 LLM 会话之间出现"一词多译"的分裂，也让未来的模型在重新生成页面时行为可预期。

你可以在自己的语言目录（如简体中文 docs/zh/llm-prompt.md、德语 docs/de/llm-prompt.md）看到同构的提示词文件。如果你的语言存在翻译错误，文档给出的处理方式正是直接向该语言目录下的llm-prompt.md提出修改建议，并申请重新生成受影响的特定页面。

改进提示词：一条以"母语者"为准的规则

docs/en/docs/translations.md 强调：对某语言专属 LLM 提示词提出修改建议的 PR，需要至少一位该语言的母语者批准（"PRs with suggestions to the language-specific LLM prompt require approval from at least one native speaker"）。

这条规则在仓库的自动化脚本中同样有迹可循。在 scripts/notify_translations.py 中定义了一组审核标签常量：

awaiting_label = "awaiting-review" lang_all_label = "lang-all" approved_label = "approved-1"

approved-1（"已获 1 人批准"）标签与"至少一位母语者批准"的规则一一对应，表明翻译/提示词修改的合入门槛在工程上是可量化执行的。

底层机制：翻译提示词如何组装与执行

提示词文件并不只是"给人看的规范"，它会被真实地拼入 LLM 调用的完整提示中。翻译执行脚本 scripts/translate.py 中的get_prompt()函数展示了完整的提示词组装链：

1. 读取通用提示词模板 scripts/general-llm-prompt.md，其中规定了跨语言的通用翻译纪律：代码块内容不译、/// note等特殊块用竖线追加标题译文、标题的花括号锚点（hash）不可翻译以免链接失效、内部链接只译文字不译 URL 与锚点、绝对链接若指向https://fastapi.tiangolo.com则插入语言码、abbr/dfn元素 title 属性的处理规则等；
2. 拼接该语言的docs/<lang>/llm-prompt.md；
3. 若目标页面已有旧译文，则追加一段"以旧译文为基础做最小 diff 更新"的指令，要求 LLM 仅在英文源变化处改动、逐行保留原有正确译文，以便人工审核时 diff 最小；
4. 最后附上被%%%包裹的英文源内容与目标语言声明。

translate_page命令的实现在 scripts/translate.py：使用pydantic-ai的Agent("openai-chat:gpt-5.5")执行翻译，最多重试 3 次；每次产出都通过scripts/doc_parsing_utils.py的check_translation()做结构校验（对齐英文源行数、链接、锚点等），失败则将错误信息回填进附加指令后重试。

源语言与"不可翻译"边界

同文件 scripts/translate.py 中还定义了一组不参与翻译的英文节区：

• reference/（API 参考，通常只生成英文版）
• release-notes.md、fastapi-people.md、external-links.md、newsletter.md、management-tasks.md、management.md
• contributing.md、translations.md（贡献与翻译治理类文档本身保持英文）

也就是说，docs/en/docs/translations.md 这类"元文档"刻意不翻译，避免治理流程描述在多语言间产生歧义。

申请一种全新语言：三步走的社区流程

如果某种语言尚无任何页面翻译（原文以拉丁语 Latin 为例），docs/en/docs/translations.md 给出了明确的申请路径：

1. 先找到 2 位愿意一起长期审核该语言翻译 PR 的人；
2. 凑齐至少 3 位承诺共同维护该语言的贡献者后，方可进入下一步；
3. 按照模板创建一个新的 Discussion，并 @ 另外 2 位协作者，请他们在评论区确认愿意参与维护。

当讨论区聚集了足够多的参与者后，FastAPI 团队会评估讨论，并可能将该语言提升为官方翻译语言。此后：

• 文档将由 LLM 自动翻译；
• 该语言的母语者团队负责审核译文；
• 同时协助调优该语言的 LLM 提示词（即docs/<lang>/llm-prompt.md）。

新增语言在仓库侧的落点

从代码结构看，"官方支持一种语言"意味着仓库中会新增以下内容：

• docs/<lang>/llm-prompt.md：该语言的提示词文件。这一点是硬性前置条件——scripts/translate.py 中有assert lang_prompt_path.exists()，缺失该文件会直接断言失败；
• 该语言的翻译配置会用到 docs/language_names.yml。该 YAML 以 ISO 639 语言码为键（如es: español、zh: 简体中文、zh-hant: 繁體中文），translate.py通过get_langs()读取它来获取语言显示名，并据此判定哪些语言已具备llm-prompt.md、可作为 LLM 翻译目标（见get_llm_translatable()）。

翻译生成后的去向

一旦新语言获批并完成首批翻译，工作流继续闭环：

• 文档内容更新或有新章节时，系统会在同一个 Discussion 中发布评论，附上新译文的审阅链接（"there will be a comment in the same discussion with the link to the new translation to review"）；
• 这一"评论到讨论区"的行为由 scripts/notify_translations.py 支撑。该脚本通过 GitHub GraphQL API 监听翻译分类下的 Discussions（questions_translations_category_id），结合awaiting-review/lang-all/approved-1标签，向讨论区追加/更新评论，通知母语审核者有哪些新译文需要审阅。

翻译生命周期的工程化维护

虽然 docs/en/docs/translations.md 面向人类贡献者描述流程，但仓库内 scripts/translate.py 的多个 CLI 命令把整个生命周期自动化了，可作为理解"自动翻译 + 社区审核"体系的补充证据：

这些命令主要靠环境变量（LANGUAGE、EN_PATH、GITHUB_TOKEN、GITHUB_REPOSITORY、GITHUB_REF_NAME等）驱动，在 CI 中被编排为默认流水线remove-removable → update-outdated → add-missing（见commands_json中的default_commands）。也就是说，社区期望的"最新最全"状态是通过先清理孤儿译文、再更新过期页面、最后补齐缺失页面的顺序达成的。

未翻译页面的占位呈现

对于尚无译文的页面，仓库使用 docs/missing-translation.md 作为占位模板。它以/// warning特殊块输出："This page hasn't been translated into your language yet. 🌍 / We're currently switching to an automated translation system 🤖..."——即告知读者该语言正切换到自动化翻译体系，并引导其前往翻译贡献入口。它从界面侧印证了：缺失翻译是"可被自动补齐"的常态，而非需要人工急催的缺口。

贡献者实操小结

综合 docs/en/docs/translations.md 与仓库源码，对普通贡献者最有用的几条行动路径是：

1. 发现母语译文的术语或风格问题：不要直接逐句改写译文，而是修改docs/<lang>/llm-prompt.md（例如西班牙语看 docs/es/llm-prompt.md、简体中文看 docs/zh/llm-prompt.md），在该语言术语表中增补/修正映射，并请求重新生成特定页面——此类 PR 需至少一位母语者批准；
2. 希望新增一种官方语言：先在社区中召集另外 2 位愿长期审核的母语协作者（合计至少 3 人），按模板创建 Discussion 并请他们在评论中确认，等待 FastAPI 团队评估后转正；
3. 理解翻译 PR 为何呈现为当前形态：翻译 PR 由 LLM 依据 scripts/general-llm-prompt.md + 语言提示词自动产出，因此审核重点应放在语义准确性与术语一致性，而非英文残留或行内代码被改动——这些属于通用提示词纪律，已在生成阶段被约束。

小结

docs/en/docs/translations.md 表面上是篇幅不长的贡献指南，背后却是一套在仓库中完整落地的工程系统：docs/<lang>/llm-prompt.md定义每种语言的翻译契约，scripts/general-llm-prompt.md 定义跨语言通用纪律，scripts/translate.py 将提示词组装、LLM 生成、结构校验、过期/缺失检测与 PR 提交串成流水线，而"母语者审核提示词与译文"由approved-1等标签在 scripts/notify_translations.py 中固化执行。理解了这一层，再回头看"3 人发起新语言申请"的规则就会更清楚：它保证的不是"有人愿意翻译"，而是每一个官方语言背后都有一组能长期负责审核与调优提示词的母语维护者。

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi