FastAPI の支援: ドキュメントの翻訳に貢献する方法

FastAPI の優れた機能の 1 つは、その優れたドキュメントです。しかし、世界中のより多くの人がこのドキュメントにアクセスできた方が良いと思いませんか? ❤️

私たちが提供するドキュメントはすべての人が読めることを当然のことと考えることがありますが、それが世界中の人々にとってどのように機能するかは必ずしもそうではありません。

?翻訳を追加する理由

? FastAPI Web サイトには英語で書かれた非常に優れたドキュメントがすでに存在します。なぜ他の言語への翻訳を支援する必要があるのでしょうか?

Google で高速検索すると、? の 17% しか含まれていないことがわかります。世界の人口は英語を話します。このウィキペディアの投稿をチェックしてください: 英語を話す人口による国のリストで、あなたの国の英語話者の割合を確認してください。

たとえば、私はブラジルに住むブラジル人です。そしてここでは、人口のわずか 5% のみがある程度の英語力を持っています。これは、英語で書かれたドキュメントに従うことができる人口のごく一部に相当します。

そしてポルトガル語の話に続きますが、この言語を話すのはポルトガルとブラジルだけではありません。アンゴラ、モザンビーク、カーボベルデ、その他多くの国もあります。完全なリストはここでご覧いただけます。

お気に入りのプログラミング言語またはフレームワークからドキュメントを翻訳するときに、何人の人を助けることができるか考えていますか?その恩恵を受けている人の数を考えると、驚くべきことです。

さらに、翻訳を手伝うことは、プロジェクトの仕組み、ワークフロー、メンテナーが従う承認などを理解するための非常に実用的な方法です。

✏️ 初めての翻訳を作成する方法

FastAPI ドキュメントには、ドキュメントと翻訳のセクションを含む、プロジェクトへの貢献方法に特化したページがあります。

それでは、ローカル環境をセットアップして英語以外の言語への翻訳を作成する方法を段階的に見てみましょう!

? FastAPI のリポジトリをフォークする

最初に行うことは、FastAPI リポジトリをフォークすることです。 Github には、リポジトリをフォークする方法を説明した素晴らしいドキュメントがあります。ただし、基本的に行う必要があるのは、必要なリポジトリ (この場合は FastAPI のリポジトリ) を参照し、Fork をクリックすることです。

それで終わりです。リポジトリの独自のコピーがあることを確認してください。ここで、自分のリポジトリを参照すると、フォークされたリポジトリがそこに表示されます:

⁉️ FastAPI のドキュメント構造

FastAPI のドキュメントは、リポジトリのルートにある docs フォルダー内にあります。そして、ドキュメントのすべてのソース コードは docs_src フォルダー内に存在します。

ご覧のとおり、docs フォルダー内には、翻訳されている現在の言語がすべてあります。各言語に ISO 693-1 の 2 文字コードを使用します。

各言語フォルダーは同じ構造に従います:

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.

Seperti yang anda lihat, FastAPI mempunyai pasukan yang sangat baik dan membantu dan mereka sentiasa melakukan yang terbaik untuk membantu anda:

Jadi, jika anda memerlukan bantuan, cuba hubungi mereka. Hanya bersikap sopan dan sabar bahawa mereka akan membantu anda ❤️!

? Faedah menterjemah dokumen

Terdapat beberapa faedah membantu terjemahan ?.

Bagi saya, perkara yang paling penting ialah membantu orang yang mengalami kesukaran membaca dokumentasi dalam bahasa Inggeris.

Mereka boleh jadi ??? pelajar cuba mempelajari bahasa atau rangka kerja baharu, malah ?‍? profesional yang masih belum berpeluang belajar bahasa inggeris.

Selain membantu orang, anda juga boleh ? pelajari topik baharu, ketahui butiran yang anda gunakan tetapi tidak begitu faham sebabnya, dsb.

Selain itu, membantu menterjemah dokumen memerlukan anda menyemak dokumentasi asal. Ini mungkin menyebabkan anda menemui peningkatan, topik yang boleh dijelaskan dengan lebih baik, dsb.

Jadi, nasihat saya ialah: adakah anda mempunyai bahasa atau rangka kerja yang anda sangat suka dan ingin mula membantu? Mulakan dengan dokumentasi?!

以上がFastAPI の支援: ドキュメントの翻訳に貢献する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。