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中文網其他相關文章！
