帮助 FastAPI：如何为文档翻译做出贡献

FastAPI的一大优点就是它完善的文档👏。但如果全世界更多的人都能访问到这些文档，岂不是更好吗？❤️

我们有时会想当然地认为所有人都能阅读我们提供的文档，但对于世界各地的人们来说，情况并非总是如此。

📝 为什么要添加翻译？

📖 FastAPI 网站上已经有非常好的英文文档，所以为什么要帮忙翻译成其他语言呢？

快速谷歌搜索一下，你会发现全球只有17%的人口会说英语。你可以查看这篇维基百科文章：按英语人口排列的国家/地区列表，了解你所在国家/地区的英语使用者比例。

例如，我是一名居住在巴西的巴西人。在这里，只有5%的人口具备一定的英语水平。这意味着能够阅读英文文件的人口比例非常小。

说到葡萄牙语，不仅葡萄牙和巴西使用这种语言，安哥拉、莫桑比克、佛得角以及其他许多国家也使用这种语言。您可以在这里查看完整列表。

你知道当你把你最喜欢的编程语言或框架的文档翻译成其他语言时，能帮助到多少人吗？想到会有这么多人从中受益，真是令人难以置信。

此外，协助翻译也是了解项目运作方式、维护人员遵循的工作流程和审批流程等的一种非常实用的方法。

✏️ 如何创建您的第一个翻译

FastAPI 文档有一个专门介绍如何为该项目做出贡献的页面，其中包括文档和翻译部分。

那么，让我们一步一步地来看看如何设置本地环境，并开始创建英语以外的其他语言的翻译！

🍴 Fork FastAPI 的仓库

首先，你需要 fork FastAPI 的代码库。GitHub上有一篇很棒的文档，解释了如何 fork 代码库。但简单来说，你需要做的就是浏览你想要的代码库，在本例中是FastAPI 的代码库，然后点击“Fork”。

就这样。现在你已经拥有了仓库的副本。如果你浏览自己的仓库，就能看到这个 fork 的仓库了：

🗂️ FastAPI 的文档结构

FastAPI 的文档位于代码仓库根目录下的 docs 文件夹中。而文档中的所有源代码都位于 docs_src 文件夹中。

如您所见，在 docs 文件夹中，包含了所有已翻译的语言。每种语言都使用ISO 693-1 双字母代码。

每个语言文件夹都将遵循相同的结构：

文件en夹内包含完整的文档，但您会注意到，在其他语言版本中，尽管结构相同，但并非所有文件都存在。这是因为并非所有文件都已翻译成所有语言（目前还不是😇）。

💡 现在你知道找到可翻译内容的第一种方法了：你的语言中缺少某个文件？那就是你可以开始翻译的文件！

☹️ 缺少语言

并非所有语言都有翻译。例如，如果您在文档中查找亚美尼亚语代码 (hy)，您会发现它目前还不存在：

在这些情况下， FastAPI 文档对如何添加新语言的翻译有非常好的解释。

从文档中可以看出，FastAPI 提供了一个简洁的脚本来初始化新的语言翻译：

python ./scripts/docs.py new-lang hy

现在脚本已经添加了文件夹和文件，您可以按照以下步骤将翻译添加到现有语言中。

🗺️ 翻译现有语言

既然您已经 fork 了 FastAPI 的存储库，并且了解了如何添加缺失的语言（如果这是您的情况），那么让我们来看看翻译文档文件的整个过程。

📋 如何验证要翻译的文档

有几种方法可以轻松找到您可以翻译的文档。

1️⃣ 浏览文档

一个简单易行的方法是：阅读您所需语言的文档。只需访问fastapi.tiangolo.com并选择所需的语言即可：

当您找到一个没有任何翻译的文档时，您会看到一条警告，告诉您该文档尚未被翻译：

现在您可以查看源代码，找到 doc 文件，并在您想要使用的语言文件夹中创建一个副本。文档的文件夹结构非常简单易懂。

在上面的例子中，面包屑导航显示我们当前位于：FastAPI（根目录）- 学习 - 高级。因此我们可以推断，该文档位于 docs/en/docs 目录下的某个位置，可能在名为 learn 或 advanced 的文件夹中。

如果我们查看源代码，就会发现 advanced 文件夹确实存在，而且该文件custom-response.md也存在。

查找文件的更简便方法是获取 URL 的最后一部分，然后在编辑器中搜索它。例如，在 VSCode 中，您可以使用 `<filename>`ctrl + e并输入该文件名：

2️⃣ 查看源代码

另一种查找没有翻译的文件的方法是，用编辑器打开源代码。然后展开所需的语言和英文。

您可能会注意到，英文文件夹中的文件比您所需语言的文件夹中的文件要多。现在，您可以选择缺失的文件，在语言文件夹中创建该文件的副本，然后进行翻译。

3️⃣ 使用 FastAPI 翻译管理包

我创建了一个名为fastapi translations management 的📦 包来帮助进行 FastAPI 翻译。

它本质上是一个库，会检查所有文档文件并查看其最后提交日期。这样就能列出尚未翻译的文件以及已过时的文件。

要使用它，您可以使用以下命令安装pip：

pip install -U fastapi-translations

然后将其用于你 fork 的 FastAPI 仓库的根文件夹：

fastapi_translations -l {two-letter-code-for-language}

这将为您提供缺失翻译和过时翻译的简要概述：

您还可以使用以下命令生成一个csv包含所有过期和缺失文件的文件-c：

fastapi_translations -l pt -c

📋 开始你的第一次翻译之前需要了解的事项

💬 讨论

如果您想翻译成一种已存在的语言，那么在“讨论”版块下可能已经有相关的主题。您可以在github.com/fastapi/fastapi/discussions中搜索您的语言。

在葡萄牙语讨论中，我们有一个惯例，就是总是先发布我们正在翻译的文件，翻译完成后，再编辑文件添加 PR 链接：

🔍 评论

所有翻译相关的拉取请求必须至少获得两位该语言母语人士的批准。

例如，如果您创建了一个日语翻译，则必须由两位懂日语的人进行审核，然后管理员才能批准该 PR。

👨🏾‍⚖️ 另一条规则

翻译某些文档时，还有一些其他规则需要遵守。

✅ 不要翻译代码块内的代码docs_src；
✅ 只翻译 Markdown 文件；
✅ 在代码块内，只翻译 # 注释；

您可以查看 FastAPI 文档中的所有规则，以获取翻译技巧和指南。

✨ 创建您的第一个翻译

既然我们已经了解了翻译 FastAPI 文档所需的大部分知识，那就让我们开始翻译一份新文档吧。

⚙️ 更新您的 FastAPI 分支

每当你开始一个新的翻译时，你需要更新你派生的仓库，以确保所有内容都已更新✔️。

最简单的方法是访问您在 GitHub 上的存储库并点击进入sync fork -> update branch。

现在您可以将主仓库中的所有更改更新到本地仓库。

🔎 查找要翻译的文档

现在本地代码库已更新。让我们查找一些缺失的翻译。

我们可以看到，在“ ”下缺少docs/pt/docs/advanced📁 文件夹。所以让我们翻译一下高级安全主题的内容。securityindex.md

🙋🏿‍♀️ 正在通知翻译进行中

既然我们已经选定了要翻译的文件，那就让我们在葡萄牙语翻译讨论区告诉大家我们正在进行翻译工作吧：

🛠️ 创建翻译

现在我们创建一个翻译分支：

git checkout -b features/pt-advanced-security-index

由于我们是在本地 fork 的仓库上工作，所以不一定需要创建专门的分支。但我认为这样做是好事。这样一来，在其他人审核我们的 PR 时，我们就可以开始其他工作了。

现在我们可以创建缺失的文件夹📁和缺失的文件📃 docs/pt/docs/advanced。

我翻译文件时喜欢把编辑器分成两部分，一部分是我正在翻译的文件，另一部分是英文原文。不过，你可以根据自己的情况选择最合适的工作方式。

文件翻译工作已经完成，现在可以提交了：

git add docs/pt/docs/advanced/security/index.md
git commit -m "Add translation to docs/pt/docs/advanced/security/index.md"
git push origin features/pt-advanced-security-index

👀 预览翻译

现在翻译已经完成，我们可以看到它在官方文档中的样子了。

你可以在终端中输入以下命令👨🏼‍💻（记得安装所有依赖项）：

python scripts/docs.py live pt

然后您就可以查看结果了：

💻 创建拉取请求

请记住，我们正在开发自己的分支。现在我们已经提交到了自己的代码库，接下来需要将其发送到FastAPI 代码库。幸运的是，这非常容易做到。

如果你访问FastAPI 代码库，GitHub 会警告你已将代码推送到你的 fork 分支，现在你可以创建一个 PR 来合并它：

我们可以点击compare & pull request并按照以下标题格式创建 PR：

🌐 添加葡萄牙语翻译path/of/file.md

现在我们可以等待所有检查运行完毕（它们必须通过）。之后 FastAPI 团队的成员会添加必要的标签。

当然，我们还需要更新讨论区的帖子，告知大家翻译已经完成：

一切顺利的话，你会收到一条消息，告诉你你的PR申请已经获批✨：

💣 处理问题

我开始写这篇文章的时候并没有预料到这种情况。GitHub Actions出现了问题，upload-artifact我的PR中的检查失败了💥。

这件事很好，它向我们展示了如何处理公关方面出现问题的情况。

当我看到检查失败时，我尝试查看是否与我的 PR 直接相关。我发现无关，于是联系了FastAPI 团队中非常热心的成员Alejandra。团队成员Sofie也立即指出了与此问题相关的其他原因。

如您所见，FastAPI 拥有一支非常友善且乐于助人的团队，他们总是尽力为您提供帮助：

所以如果你需要帮助，可以尝试联系他们。请保持礼貌和耐心，他们会帮助你的❤️！

🎁 翻译文档的好处

参与翻译有很多好处🎉。

对我来说，最重要的是帮助那些阅读英文文档有困难的人。

他们可能是正在学习新语言或框架的学生，甚至是还没有机会学习英语的专业人士。

除了帮助他人之外，你还可以学习新知识，了解你曾经使用过但不太明白为什么的细节等等。

此外，协助翻译文档需要您审阅原始文档。这可能会让您发现一些改进之处，例如哪些内容可以解释得更清楚等等。

所以我的建议是：你有没有特别喜欢的语言或框架，并且想开始贡献力量？那就从文档入手吧📚！