Membantu FastAPI: Cara menyumbang kepada terjemahan dokumen

Salah satu ciri hebat FastAPI ialah dokumentasinya yang hebat ?. Tetapi bukankah lebih baik jika lebih ramai orang di seluruh dunia mempunyai akses kepada dokumentasi ini? ❤️

Kadangkala kami mengambil mudah bahawa semua orang boleh membaca dokumen yang kami sediakan, tetapi ia tidak semestinya cara ia berfungsi kepada orang di seluruh dunia.

? Mengapa menambah terjemahan?

? Sudah ada dokumentasi yang sangat bagus yang ditulis dalam bahasa Inggeris dalam tapak web FastAPI, jadi mengapa membantu menterjemah ke bahasa lain?

Membuat carian google yang pantas, anda boleh melihat bahawa hanya 17% daripada ? penduduk dunia bercakap bahasa inggeris. Anda boleh menyemak siaran wikipedia ini: Senarai negara mengikut populasi berbahasa Inggeris untuk menyemak peratusan penutur bahasa Inggeris di negara anda.

Sebagai contoh, saya warga Brazil yang tinggal di Brazil. Dan di sini, hanya 5% daripada populasi mempunyai beberapa tahap bahasa Inggeris. Ini mewakili sebahagian kecil daripada populasi yang boleh mengikuti dokumentasi yang ditulis dalam bahasa Inggeris.

Dan meneruskan dengan bahasa portugis, bukan sahaja Portugal dan Brazil yang bercakap bahasa ini. Terdapat juga Angola, Mozambique, Cape Verde dan banyak negara lain. Anda boleh lihat senarai penuh di sini.

Adakah anda mempunyai sebarang idea tentang bilangan orang yang boleh anda bantu apabila anda menterjemah dokumen daripada bahasa pengaturcaraan atau rangka kerja kegemaran anda? Pemikiran yang memeranjatkan bilangan orang yang mendapat manfaat daripadanya.

Selain itu, membantu dengan terjemahan ialah cara yang sangat praktikal untuk memahami cara projek berfungsi, aliran kerja dan kelulusan yang diikuti oleh penyelenggara, dsb.

✏️ Cara membuat terjemahan pertama anda

Dokumen FastAPI mempunyai halaman khusus tentang cara menyumbang kepada projek, termasuk bahagian untuk dokumentasi dan terjemahan.

Jadi mari kita lihat langkah demi langkah tentang cara anda boleh menyediakan persekitaran setempat anda dan mula mencipta terjemahan kepada bahasa selain bahasa Inggeris!

? Forking repositori FastAPI

Perkara pertama yang anda mahu lakukan ialah menolak repo FastAPI. Github mempunyai dokumen hebat yang menerangkan cara anda boleh membuat garpu repositori. Tetapi pada asasnya, apa yang anda perlu lakukan ialah menyemak imbas repo yang anda mahu, dalam kes ini repo FastAPI dan klik Fork.

Dan itu sahaja. Ketahui bahawa anda mempunyai salinan repositori anda sendiri. Sekarang jika anda menyemak imbas repositori anda sendiri, anda akan melihat repo bercabang di sana:

?️ Struktur dokumentasi FastAPI

Dokumentasi FastAPI tinggal di dalam dokumen folder, dalam akar repositori. Dan semua kod sumber daripada docs tinggal di dalam folder docs_src.

Seperti yang anda lihat, di dalam folder dokumen, terdapat semua bahasa semasa yang mempunyai terjemahan. Ia menggunakan kod dua huruf ISO 693-1 untuk setiap bahasa.

Setiap folder bahasa akan mengikut struktur yang sama:

Folder en akan mempunyai dokumentasi lengkap, tetapi anda akan dapati bahawa dalam bahasa lain, walaupun mempunyai struktur yang sama, tidak semua fail hadir. Dan itu kerana tidak semua fail diterjemahkan kepada semua bahasa (belum ?).

? Jadi sekarang anda tahu cara pertama untuk mencari perkara yang boleh anda terjemah: Terdapat fail yang hilang dalam bahasa anda? Itulah yang anda boleh mula menterjemah!

☹️ Hilang bahasa

Belum semua bahasa mempunyai terjemahan lagi. Sebagai contoh, jika anda mencari ?? Kod Armenia (hy) dalam dokumen, anda akan perasan bahawa ia belum wujud lagi:

Dalam kes ini, dokumen FastAPI mempunyai penjelasan yang sangat baik tentang cara anda boleh menambah terjemahan kepada bahasa baharu.

Seperti yang anda lihat daripada dokumen, FastAPI mempunyai skrip yang kemas untuk memulakan terjemahan bahasa baharu:

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

Sekarang skrip menambah folder dan fail, anda boleh mengikuti proses menambah terjemahan kepada bahasa sedia ada.

?️ Menterjemah bahasa sedia ada

Sekarang anda sudah mencantas repositori FastAPI dan mempelajari cara menambah bahasa yang hilang (jika ini kes anda), mari lihat keseluruhan proses menterjemah fail dokumen.

? Cara untuk mengesahkan dokumen yang hendak diterjemahkan

Terdapat beberapa cara anda boleh mencari dokumen yang boleh anda terjemahkan dengan mudah.

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.

Comme vous pouvez le constater, FastAPI a une équipe vraiment sympa et serviable et ils font toujours de leur mieux pour vous aider :

Donc, si vous avez besoin d'aide, essayez d'en joindre un. Soyez juste poli et patient pour qu'ils vous aident ❤️ !

? Avantages de la traduction de documents

Il y a plusieurs avantages à aider avec les traductions ?.

Pour moi, le plus important est d'aider les personnes qui ont des difficultés à lire la documentation en anglais.

Ils peuvent être ???‍? les étudiants essayant d'apprendre une nouvelle langue ou un nouveau cadre, ou même un ?‍? professionnel qui n'a pas encore eu l'occasion d'apprendre l'anglais.

En plus d'aider les gens, vous pouvez aussi ? apprenez de nouveaux sujets, découvrez ce détail que vous avez utilisé mais que vous n'avez pas bien compris pourquoi, etc.

De plus, pour aider à traduire des documents, vous devez revoir la documentation originale. Cela peut vous amener à trouver des améliorations, des sujets qui pourraient être mieux expliqués, etc.

Alors, mon conseil est le suivant : avez-vous un langage ou un framework que vous aimez vraiment et que vous aimeriez commencer à aider ? Commencer par la documentation ?!

Atas ialah kandungan terperinci Membantu FastAPI: Cara menyumbang kepada terjemahan dokumen. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!