L'une des fonctionnalités intéressantes de FastAPI est son excellente documentation ?. Mais ne serait-il pas préférable que davantage de personnes dans le monde aient accès à cette documentation ? ❤️
Parfois, nous tenons pour acquis que tout le monde peut lire les documents que nous fournissons, mais ce n'est pas nécessairement ainsi que cela fonctionne pour les gens du monde entier.
? Il existe déjà une très bonne documentation écrite en anglais sur le site Web FastAPI, alors pourquoi aider à traduire dans d'autres langues ?
En effectuant une recherche rapide sur Google, vous constatez que seulement 17 % des ? la population mondiale parle anglais. Vous pouvez consulter cet article wikipedia : Liste des pays par population anglophone pour vérifier le pourcentage d'anglophones dans votre pays.
Par exemple, je suis un brésilien vivant au Brésil. Et ici, seulement 5% de la population possède un certain niveau d’anglais. Cela représente une très petite partie de la population pouvant suivre une documentation rédigée en anglais.
Et pour continuer avec le portugais, il n'y a pas que le Portugal et le Brésil qui parlent cette langue. Il y a aussi l'Angola, le Mozambique, le Cap-Vert et bien d'autres pays. Vous pouvez voir la liste complète ici.
Avez-vous une idée du nombre de personnes que vous pouvez aider lorsque vous traduisez les documents à partir de votre langage ou framework de programmation préféré ? C'est époustouflant de penser au nombre de personnes qui en bénéficient.
De plus, aider aux traductions est un moyen très pratique de comprendre le fonctionnement du projet, le flux de travail et l'approbation suivis par les responsables, etc.
FastAPI docs comporte une page dédiée à la manière de contribuer au projet, y compris une section pour les documentations et les traductions.
Voyons donc étape par étape comment configurer votre environnement local et commencer à créer des traductions vers une langue autre que l'anglais !
La première chose que vous voulez faire est de créer le dépôt FastAPI. Github a un excellent document expliquant comment créer un référentiel. Mais en gros, ce que vous devrez faire est de parcourir le dépôt que vous souhaitez, dans ce cas le dépôt de FastAPI et de cliquer surFork.
Et c'est tout. Sachez que vous disposez de votre propre copie du référentiel. Maintenant, si vous parcourez vos propres référentiels, vous verrez le dépôt forké ici :
La documentation de FastAPI se trouve dans le dossier docs, à la racine du référentiel. Et tout le code source de la documentation réside dans le dossier docs_src.
Comme vous pouvez le voir, dans le dossier docs, il y a toutes les langues actuelles qui ont des traductions. Il utilise le code à deux lettres ISO 693-1 pour chaque langue.
Chaque dossier de langue suivra la même structure :
Le dossier en contiendra la documentation complète, mais vous remarquerez que dans d'autres langues, malgré la même structure, tous les fichiers ne sont pas présents. Et c'est parce que tous les fichiers ne sont pas traduits dans toutes les langues (encore ?).
? Alors maintenant, vous connaissez la première façon de trouver ce que vous pouvez traduire : il manque un fichier dans votre langue ? C'est celui-là que vous pouvez commencer à traduire !
Toutes les langues n'ont pas encore de traduction. Par exemple, si vous recherchez le ?? Code arménien (hy) dans la doc, vous remarquerez qu'il n'existe pas encore :
Dans ces cas, la documentation FastAPI contient une très bonne explication sur la façon dont vous pouvez ajouter des traductions dans de nouvelles langues.
Comme vous pouvez le voir dans la documentation, FastAPI dispose d'un script soigné pour initialiser une nouvelle traduction de langue :
python ./scripts/docs.py new-lang hy
Maintenant que le script a ajouté le dossier et les fichiers, vous pouvez suivre le processus d'ajout de traductions aux langues existantes.
Maintenant que vous avez déjà créé le référentiel FastAPI et appris comment ajouter une langue manquante (si c'est votre cas), voyons l'ensemble du processus de traduction d'un fichier de documentation.
Il existe plusieurs façons de trouver facilement le document que vous pouvez traduire.
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:
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.
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
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:
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.
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.
Now that we know almost everything that is to be know about translating FastAPI docs, let's get started and translate a new doc.
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.
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.
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:
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
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:
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 ✨:
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中文网其他相关文章！
