DEV Community

Cover image for Helping FastAPI: How to contribute to docs translations
Rafael de Oliveira Marques
Rafael de Oliveira Marques

Posted on

Helping FastAPI: How to contribute to docs translations

One of the great features of FastAPI is its great documentation πŸ‘. But wouldn't it be better if more people around the world had access to this documentation? ❀️

Sometimes we take for granted that all people can read the docs we provide, but it's not necessarily how it works to people around the world.

πŸ“ Why add translations?

πŸ“– There is already a really good documentation written in english in FastAPI website, so why help translate to other languages?

Making a fast google search, you can see that only 17% of the 🌎 world population speaks english. You can check this wikipedia post: List of countries by English-speaking population to check the percentage of english speakers in your country.

For example, I'm a brazilian living in Brazil. And here, only 5% of the population have some level of english. This represents a very small portion of the population that can follow documentation written in English.

And continuing with the portuguese, it's not only Portugal and Brazil that speaks this language. There's also Angola, Mozambique, Cape Verde and many other countries. You can see the full list here.

Do you have any idea on how many people you can help when you translate the docs from your favorite programming language or framework? It's mindblowing thinking in the number of people who benefit from it.

Additionally, helping with translations is a very practical way to understand the way the project works, the workflow and approval that maintainers follow, etc.

✏️ How to create your first translation

FastAPI docs has a page dedicated on how to contribute to the project, including a section for the documentations and translations.

So let's take a look step by step on how you can setup your local environment and start creating translations to a language other then english!

🍴 Forking FastAPI's repository

The first thing that you want to do is fork the FastAPI repo. Github has a great doc explaining how you can fork a repository. But basically, what you'll need to do is browse the repo you want, in this case FastAPI's repo and click Fork.

Fork FastAPI repository

And that's it. Know you have your own copy of the repository. Now if you browse your own repositories, you'll see the forked repo right there:

Forked repository

πŸ—‚οΈ FastAPI's documentation structure

The FastAPI's documentation lives inside the folder docs, in the root of the repository. And all the source code from the docs lives inside docs_src folder.

docs structure

As you can see, inside docs folder, there are all the current languages that has translations. It uses the ISO 693-1 two letter code for each language.

Each language folder will follow the same structure:

Language translation structure

The en folder will have the complete documentation, but you'll notice that in other languages, despite having the same structure, not all files are present. And that's because not all files are translated to all languages (yet πŸ˜‡).

πŸ’‘ So now you know the first way to find what you can translate: There is a missing file in your language? That's the one you can start translating!

☹️ Missing languages

Not all languages has translations yet. For example, if you look for the πŸ‡¦πŸ‡² Armenian code (hy) in the docs, you'll notice the it doesn't exist yet:

Missing language

In these cases, FastAPI docs has a really good explanation on how you can add translations to new languages.

As you can see from the docs, FastAPI has a neat script to initialize a new language translation:

python ./scripts/docs.py new-lang hy
Enter fullscreen mode Exit fullscreen mode

Now that the script added the folder and files, you can follow the process of adding translations to existing languages.

πŸ—ΊοΈ Translating existing languages

Now that you already forked the FastAPI's repository and learned how the add a missing language (if its your case), let's see the whole process of translating a file of the docs.

πŸ“‹ Ways to verify what doc to translate

There are a few ways you can easily find what doc you can translate.

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:

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:

doc not 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:

find the file in editor

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.

fastapi translation management repo readme

To use it, you can install it with pip:

pip install -U fastapi-translations
Enter fullscreen mode Exit fullscreen mode

And then use it at the root folder of your forked FastAPI repository:

fastapi_translations -l {two-letter-code-for-language}
Enter fullscreen mode Exit fullscreen mode

This will give you a brief summary of missing translations and outdated translations:

fastapi translation management translations summary

You can also generate a csv file with all files that are outdated and missing with -c:

fastapi_translations -l pt -c
Enter fullscreen mode Exit fullscreen mode

πŸ“‹ 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.

Discussions for translations

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:

Posts about translated docs

πŸ” 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.

Update forked repository

Now you can update your local repository with all changes from the main repo.

Pull master

πŸ”Ž Find the doc to translate

Now that our local repository is updated. Let's find some missing translation.

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:

Notify the translation

πŸ› οΈ Creating the translation

Not let's create a branch for the translation:

git checkout -b features/pt-advanced-security-index
Enter fullscreen mode Exit fullscreen mode

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.

Translating the file

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
Enter fullscreen mode Exit fullscreen mode

πŸ‘€ 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
Enter fullscreen mode Exit fullscreen mode

And you'll be able to check the result:

Preview of the translation

πŸ’» 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:

Github Warning to create a PR

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

Creating the PR

Now we can wait for all the checks to run (they must pass). And someone from the FastAPI team will add the necessary tags.

Wait for the checks

And of course, we need to update our post at the discussions to inform that we finished the translation:

Update the discussion

And after everything goes well, you'll get a message telling you that your PR was approved ✨:

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

PR problem

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.

Issue related

As you can see, FastAPI has a really nice and helpful team and they always do their best to help you:

FastAPI Team

So if you need some help, try to reach one the them. Just be polite and patiente that they will help you ❀️!

🎁 Benefits of translating docs

There are several benefits helping with the translations πŸŽ‰.

To me, the most important one is to help people who have difficulty reading documentation in english.

They can be πŸ‘©πŸ½β€πŸŽ“ students trying to learn a new language or framework, or even a πŸ‘©β€πŸ’» professional who has not yet had the opportunity to learn english.

In addition to helping people, you can also πŸ“– learn new topics, find out about that detail that you used but didn't quite understand why, etc.

Also, helping translate docs requires you to review the original documentation. This may result in you finding improvements, topics that could be better explained, etc.

So, my advice is: do you have a language or framework that you really like and would like to start helping? Start with the documentation πŸ“š!

Top comments (4)

Collapse
 
anil_mohite_2ac976aaab00f profile image
Anil Mohite

The way you explained each and everything in simple words is commendable. After reading your blog i created account on DEV. And we need more bloggers like you.πŸ”₯

Collapse
 
ceb10n profile image
Rafael de Oliveira Marques

Thank you very much Anil!! πŸ˜„

Collapse
 
ayikoandrew profile image
Ayiko Andrew

I love FastAPI and I would wish to translate the docs in my language and introduce it. Is it okay I mean my language is just a tiny bit. My question the language into which you are translating doesn't matter right?

Collapse
 
ceb10n profile image
Rafael de Oliveira Marques

Hi @ayikoandrew , sorry for the delay

You can translante to any language as far as I know :D