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。以西班牙语提示词为例它主要约定两类关键约束语言风格基调例如要求使用非正式语法用 tú 而非 usted命令式标题/说明保留命令式语态Edit it → Edítalo。术语对照表大量技术词汇指定了必须使用的译法或保留英文原词例如framework不译作 marcopath operation function、path operation、path、query、cookie、header等 HTTP/框架术语保留英文type hints/type annotations→anotaciones de tiposlibrary→paquete而非 bibliotecadocs→documentación而非 documentosRelease 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-1approved-1已获 1 人批准标签与至少一位母语者批准的规则一一对应表明翻译/提示词修改的合入门槛在工程上是可量化执行的。底层机制翻译提示词如何组装与执行提示词文件并不只是给人看的规范它会被真实地拼入 LLM 调用的完整提示中。翻译执行脚本 scripts/translate.py 中的get_prompt()函数展示了完整的提示词组装链读取通用提示词模板 scripts/general-llm-prompt.md其中规定了跨语言的通用翻译纪律代码块内容不译、/// note等特殊块用竖线追加标题译文、标题的花括号锚点hash不可翻译以免链接失效、内部链接只译文字不译 URL 与锚点、绝对链接若指向https://fastapi.tiangolo.com则插入语言码、abbr/dfn元素 title 属性的处理规则等拼接该语言的docs/lang/llm-prompt.md若目标页面已有旧译文则追加一段以旧译文为基础做最小 diff 更新的指令要求 LLM 仅在英文源变化处改动、逐行保留原有正确译文以便人工审核时 diff 最小最后附上被%%%包裹的英文源内容与目标语言声明。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.mdcontributing.md、translations.md贡献与翻译治理类文档本身保持英文也就是说docs/en/docs/translations.md 这类元文档刻意不翻译避免治理流程描述在多语言间产生歧义。申请一种全新语言三步走的社区流程如果某种语言尚无任何页面翻译原文以拉丁语 Latin 为例docs/en/docs/translations.md 给出了明确的申请路径先找到 2 位愿意一起长期审核该语言翻译 PR 的人凑齐至少 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 监听翻译分类下的 Discussionsquestions_translations_category_id结合awaiting-review/lang-all/approved-1标签向讨论区追加/更新评论通知母语审核者有哪些新译文需要审阅。翻译生命周期的工程化维护虽然 docs/en/docs/translations.md 面向人类贡献者描述流程但仓库内 scripts/translate.py 的多个 CLI 命令把整个生命周期自动化了可作为理解自动翻译 社区审核体系的补充证据命令作用关键实现translate-page翻译单个英文页面读取英文源与旧译文组装提示词LLM 生成并校验后写回docs/lang/docs/对应路径路径由generate_lang_path()做前缀替换得到translate-lang补齐某语言全部缺失页面遍历所有待翻译英文页跳过已存在译文者list-missing/list-outdated列出缺失 / 过期页面过期判定基于 Git 提交时间lang_commit_datetime en_commit_datetime即视为过期update-outdated/add-missing/update-and-add批量更新过期 / 补齐缺失 / 两者都做每次默认处理 10 个页面max10list-removable/remove-removable找出并删除英文源已不存在的孤儿译文反向检查docs/lang下每个 md 是否仍有对应英文源make-pr/push提交译文并推送分支 / 直接推送分支命名如translate-lang-command-随机hex由机器人提交这些命令主要靠环境变量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 hasnt been translated into your language yet. / Were currently switching to an automated translation system ...——即告知读者该语言正切换到自动化翻译体系并引导其前往翻译贡献入口。它从界面侧印证了缺失翻译是可被自动补齐的常态而非需要人工急催的缺口。贡献者实操小结综合 docs/en/docs/translations.md 与仓库源码对普通贡献者最有用的几条行动路径是发现母语译文的术语或风格问题不要直接逐句改写译文而是修改docs/lang/llm-prompt.md例如西班牙语看 docs/es/llm-prompt.md、简体中文看 docs/zh/llm-prompt.md在该语言术语表中增补/修正映射并请求重新生成特定页面——此类 PR 需至少一位母语者批准希望新增一种官方语言先在社区中召集另外 2 位愿长期审核的母语协作者合计至少 3 人按模板创建 Discussion 并请他们在评论中确认等待 FastAPI 团队评估后转正理解翻译 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
`)
