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

FastAPI 的一大特色就是其出色的文档？。但如果世界各地更多的人能够访问此文档不是更好吗？ ❤️

有时我们理所当然地认为所有人都可以阅读我们提供的文档，但这并不一定适合世界各地的人们。

？为什么要添加翻译？

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

进行快速谷歌搜索，您可以看到只有 17% 的 ?世界人口说英语。您可以查看此维基百科帖子：按英语人口列出的国家/地区列表，以检查您所在国家/地区讲英语的百分比。

例如，我是居住在巴西的巴西人。而在这里，只有 5% 的人口具有一定的英语水平。这仅占能够遵循英文文档的一小部分人。

继续说葡萄牙语，不仅葡萄牙和巴西说这种语言。还有安哥拉、莫桑比克、佛得角等许多国家。您可以在此处查看完整列表。

您知道当您翻译您最喜欢的编程语言或框架的文档时可以帮助多少人吗？从中受益的人数令人震惊。

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

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

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

因此，让我们一步步了解如何设置本地环境并开始创建英语以外的语言的翻译！

？分叉 FastAPI 的存储库

您要做的第一件事是分叉 FastAPI 存储库。 Github 有一个很棒的文档，解释了如何分叉存储库。但基本上，您需要做的就是浏览所需的存储库，在本例中为 FastAPI 的存储库，然后单击 Fork。

就是这样。知道您有自己的存储库副本。现在，如果您浏览自己的存储库，您会在那里看到分叉的存储库：

?️FastAPI的文档结构

FastAPI 的文档位于存储库根目录的 docs 文件夹内。文档中的所有源代码都位于 docs_src 文件夹中。

如您所见，在 docs 文件夹中，有所有当前有翻译的语言。它对每种语言使用 ISO 693-1 两个字母代码。

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

en 文件夹将包含完整的文档，但您会注意到，在其他语言中，尽管具有相同的结构，但并非所有文件都存在。那是因为并非所有文件都被翻译成所有语言（还吗？）。

？现在您知道查找可翻译内容的第一种方法：您的语言中缺少文件吗？您就可以开始翻译了！

☹️ 缺失的语言

并非所有语言都有翻译。例如，如果您寻找 ??文档中的亚美尼亚代码 (hy)，您会注意到它还不存在：

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

正如您从文档中看到的，FastAPI 有一个简洁的脚本来初始化新的语言翻译：

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

现在脚本添加了文件夹和文件，您可以按照向现有语言添加翻译的过程进行操作。

?️ 翻译现有语言

现在您已经分叉了 FastAPI 的存储库并了解了如何添加缺少的语言（如果您的情况），让我们看看翻译文档文件的整个过程。

？验证要翻译的文档的方法

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

1️⃣ Navigating through the docs

A simple and easy way is: Read the docs in your desired language. Just go to the docs at fastapi.tiangolo.com and select the desired language:

Once you reach a doc that has no translations, you'll see a warning telling you that the doc has not been yet translated:

Now you can go to the source code, find the doc file and create a copy at your desired language folder. The folder structure of the docs are pretty simple to understand.

In the example above, the breadcrumbs say that we are at: FastAPI (The root) - Learn - Advanced. So we can infer that the document lives somewhere in docs/en/docs. Probably in some folder named learn or advanced.

If we go to the source code, will see that the folder advanced really exists, and the file custom-response.md also exists.

An easier way to find the file is get the last part of the url and find for it in your editor. For example, in VSCode you can use ctrl + e and enter that name:

2️⃣ Looking in source code

Another way you can find files that has no translations it to open the source code with your editor. Then you'll expand the desired language and the english language.

You will probably notice that the English folder has more files than the folder for your desired language. Now you can pick the missing file, create a copy of it at the language folder and translate it.

3️⃣ Using FastAPI Translations Management package

I created a ? package to help with FastAPI translations named fastapi translations management.

It's basically a lib that will look at all doc files and check the last commit date. This will give you a list of files that has not been translated yet and the files that are outdated.

To use it, you can install it with pip:

pip install -U fastapi-translations

And then use it at the root folder of your forked FastAPI repository:

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

This will give you a brief summary of missing translations and outdated translations:

You can also generate a csv file with all files that are outdated and missing with -c:

fastapi_translations -l pt -c

? Things to know before start your first translation

? Discussions

If you want to translate to a language that already exists, probably it has a Topic created under Discussions. You can search your language in github.com/fastapi/fastapi/discussions.

At portuguese discussions, we have a pattern to always post the file we are translating, and after we finish, we edit it to add the PR link:

? Reviews

All pull requests for translations must have at least two approvals from a person who speaks that language.

For example, if you create a translation for Japanese. Two people that speaks Japanese must review it before some mantainer approves the PR.

??‍⚖️ Another rules

There are some other rules that apply when we are translating some docs.

✅ Don't translate the code in docs_src;
✅ Only translate the markdown files;
✅ Inside code blocks, only translate the # comments;

You can check all the rules in FastAPI docs for tips and guidelines for translations.

✨ Creating your first translation

Now that we know almost everything that is to be know about translating FastAPI docs, let's get started and translate a new doc.

⚙️ Update your FastAPI fork

Whenever you start a new translation, you need to update your forked repository to make sure everything is updated ✔️.

The easiest way to do this is to navigate to your repository at github and click in sync fork -> update branch.

Now you can update your local repository with all changes from the main repo.

? Find the doc to translate

Now that our local repository is updated. Let's find some missing translation.

We can see that under docs/pt/docs/advanced, the ? folder security is missing. So let's translate the index.md for the advanced security topic.

??‍♀️ Notifying about translation in progress

Now that we picked a file to translate, let's tell everyone that in the ? Discussion for Portuguese translations that we are working on it:

?️ Creating the translation

Not let's create a branch for the translation:

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

Since we working on our local forked repository, we don't necessarily need to create a specific branch. But I think it's a good thing to do. And working this way, we can start another work while people are reviewing our PR.

Now we can create both the missing folder ?, and the missing file ? under docs/pt/docs/advanced.

When I'm translating some file, I like to split the editor with the file that I'm working on, and the original file in english. But feel free to work the way is best for you.

Now that we finished our work translating the file, we can commit it:

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

? Previewing the translation

Now that we finished the translation, we can see how it will look like on the official docs.

You can type in your terminal ??‍? (remember to install all deps):

python scripts/docs.py live pt

And you'll be able to check the result:

? Creating the Pull Request

Remember that we are working on our fork. Now that we commited to our repository, we need to send it to the FastAPI repository. Luckily, this is very easy to do.

If you go to the FastAPI repository, github will warn you that you pushed to your fork, and now you can create a PR to merge it:

We can click on compare & pull request and create the PR following the pattern for the title:

? Add Portuguese translation for path/of/file.md

Now we can wait for all the checks to run (they must pass). And someone from the FastAPI team will add the necessary tags.

And of course, we need to update our post at the discussions to inform that we finished the translation:

And after everything goes well, you'll get a message telling you that your PR was approved ✨:

? Dealing with problems

I didn't anticipate this when I started writing this article. A problem related with github actions and upload-artifact started happening and the checks from my PR failed ?.

This was a really nice thing to happen to demonstrate how we can deal with situations that our PR has some problems.

When I saw the failing checks, I tried to see if it was related with my PR directly. I saw it was not related, and then I marked Alejandra, who is a very helpful member of the FastAPI team. Sofie, who is also a member of the team mentioned the issue related with the problem right away.

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

因此，如果您需要帮助，请尝试联系其中之一。只要有礼貌和耐心，他们就会帮助你❤️！

？翻译文档的好处

帮助翻译有几个好处？.

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

他们可以是??‍?学生尝试学习新的语言或框架，甚至是 ??‍?还没有机会学习英语的专业人士。

除了帮助别人，你还可以？学习新主题，找出您使用但不太明白原因的细节，等等

此外，帮助翻译文档需要您查看原始文档。这可能会让您发现改进、可以更好解释的主题等。

所以，我的建议是：你是否有一种你真正喜欢并愿意开始提供帮助的语言或框架？从文档开始？！

以上是帮助 FastAPI：如何为文档翻译做出贡献的详细内容。更多信息请关注PHP中文网其他相关文章！