Aider FastAPI : Comment contribuer aux traductions de documents

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.

? Pourquoi ajouter des traductions ?

? 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.

✏️ Comment créer votre première traduction

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 !

? Forking du référentiel FastAPI

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 sur Fork.

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 :

?️ Structure de la documentation de FastAPI

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 !

☹️ Langues manquantes

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.

?️ Traduire les 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.

? Façons de vérifier quel document traduire

Il existe plusieurs façons de trouver facilement le document que vous pouvez traduire.

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.

Wie Sie sehen, hat FastAPI ein wirklich nettes und hilfsbereites Team, das immer sein Bestes gibt, um Ihnen zu helfen:

Wenn Sie also Hilfe benötigen, versuchen Sie, einen der Ansprechpartner zu erreichen. Seien Sie einfach höflich und geduldig, damit sie Ihnen helfen ❤️!

? Vorteile der Übersetzung von Dokumenten

Es gibt mehrere Vorteile, die bei den Übersetzungen helfen?.

Für mich ist es am wichtigsten, Menschen zu helfen, die Schwierigkeiten beim Lesen von Dokumentationen auf Englisch haben.

Sie können ???‍? Studenten, die versuchen, eine neue Sprache oder ein neues Framework zu lernen, oder sogar ein ?‍? Berufstätiger, der noch keine Gelegenheit hatte, Englisch zu lernen.

Sie können nicht nur Menschen helfen, sondern auch ? Lernen Sie neue Themen kennen, erfahren Sie mehr über das Detail, das Sie verwendet haben, aber nicht ganz verstanden haben, warum usw.

Wenn Sie beim Übersetzen von Dokumenten helfen möchten, müssen Sie außerdem die Originaldokumentation überprüfen. Dies kann dazu führen, dass Sie Verbesserungen finden, Themen finden, die besser erklärt werden könnten usw.

Mein Rat ist also: Haben Sie eine Sprache oder ein Framework, das Ihnen wirklich gefällt und bei dem Sie gerne helfen würden? Beginnen Sie mit der Dokumentation ?!

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!