FastAPI 돕기: 문서 번역에 기여하는 방법

FastAPI의 뛰어난 기능 중 하나는 훌륭한 문서입니다. 하지만 전 세계의 더 많은 사람들이 이 문서에 접근할 수 있다면 더 좋지 않을까요? ❤️

때때로 우리는 우리가 제공하는 문서를 모든 사람이 읽을 수 있다고 당연하게 여기지만, 그것이 반드시 전 세계 사람들에게 적용되는 것은 아닙니다.

? 번역을 추가하는 이유는 무엇입니까?

? FastAPI 웹사이트에는 이미 영어로 작성된 훌륭한 문서가 있는데, 다른 언어로 번역하는 데 도움이 필요한 이유는 무엇입니까?

구글에서 빠르게 검색해 보면 ? 세계 인구는 영어를 사용합니다. 위키백과 게시물에서 영어 사용 인구별 국가 목록을 확인하여 해당 국가의 영어 사용자 비율을 확인할 수 있습니다.

예를 들어 저는 브라질에 거주하는 브라질인입니다. 그리고 여기에서는 인구의 5%만이 일정 수준의 영어를 구사합니다. 이는 영어로 작성된 문서를 따를 수 있는 인구의 아주 작은 부분을 나타냅니다.

그리고 계속해서 포르투갈어를 사용하는 것은 포르투갈과 브라질뿐만이 아닙니다. 앙골라, 모잠비크, 카보베르데 및 기타 여러 국가도 있습니다. 여기에서 전체 목록을 볼 수 있습니다.

좋아하는 프로그래밍 언어나 프레임워크의 문서를 번역할 때 얼마나 많은 사람에게 도움을 줄 수 있는지 아시나요? 그 혜택을 받는 사람이 많다는 것은 정말 놀라운 일입니다.

또한 번역을 돕는 것은 프로젝트가 진행되는 방식, 유지관리자가 따르는 작업흐름과 승인 등을 이해하는 매우 실용적인 방법입니다.

✏️ 첫 번째 번역을 만드는 방법

FastAPI 문서에는 문서 및 번역 섹션을 포함하여 프로젝트에 기여하는 방법에 대한 전용 페이지가 있습니다.

이제 로컬 환경을 설정하고 영어가 아닌 다른 언어로 번역을 시작하는 방법을 단계별로 살펴보겠습니다!

? FastAPI 저장소 포크

가장 먼저 하고 싶은 일은 FastAPI 저장소를 포크하는 것입니다. Github에는 저장소를 포크하는 방법을 설명하는 훌륭한 문서가 있습니다. 하지만 기본적으로 해야 할 일은 원하는 저장소(이 경우 FastAPI의 저장소)를 찾아 포크를 클릭하는 것입니다.

그리고 그게 다입니다. 자신만의 저장소 복사본이 있다는 것을 알아두세요. 이제 자신의 저장소를 탐색하면 바로 거기에서 포크된 저장소를 볼 수 있습니다.

?️ 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 중국어 웹사이트의 기타 관련 기사를 참조하세요!