Translation bot

This article brings details about how to organize team translation.

If you’re translating alone – we encourage you to spread the word, tell others that you’re translating, let them join!

The best thing about team work is reviews. They really help to make the text better, more fluent, and fix typos.

Our bot named javascript-translate-bot watches translation repositories. It adds/removes labels and requests reviews to ensure that every PR gets at least two reviews. Also it edits the Progress Issue, marks articles.

What’s the flow for the team translation?

Here’s the flow for the team translation. It was tested with large teams and is known to work well.

Roles:

• Translator – any person who wants to contribute.
• Maintainer – a member of the org, good at JS, with enough knowledge to review translations. Ask me to become a maintainer.
• Bot – a cheerful robot that struggles to help, adds/removes labels and requests reviews.

The flow:

Translator

• Selects an article from the Progress Issue.
• Adds a comment to the Progress Issue with the title of the article.
• Forks the tutorial and makes a translation.
  • If many articles are translated, a separate branch/PR is recommended for each one.

Bot

• Labels the article in the Progress Issue.

⌛ …Translator translates…

Translator

• Makes a PR with the same title as the English article title.

Bot

• Adds “review needed” label and requests review from the team.

…Maintainer is notified (if subscribed) OR finds the PR with review needed label, and…

Maintainer

• Reviews the PR, adds comments in the “Files changes” tab if needed.
• Approves if all good. Or requests changes, here:

Bot

• Changes the label to needs +1 (if approved) or changes requested (if requested).

When changes requested:

Translator

• Discusses the changes in the “File changes” tab.
• Fixes the translation and pushes the changes.
• Adds a comment with the /done word to the PR.

Bot

• Changes the PR label back to review needed.

Maintainer

• Reviews again.

⌛ …That’s until the PR is approved and merged, then we celebrate! 🎉

Double reviews

Normally, the first reviewer should “Approve” changes, then the bot adds the needs +1 label, to request a second review from another person.

Still, if the PR is obviously good to merge, or the team is small, the reviewer can just merge the PR without approvals.

What exactly the bot does?

Here are more details about the bot, just in case you’re confused about low-level details.

The bot listens to repository events and performs actions:

1. When the Progress Issue gets a comment with a title of an article:
   • Appends the translator name to the article in the Progress Issue.
2. When a PR with a title of an article is created:
   • PR gets review needed label.
   • Review requested from @javascript-tutorial/translate-(lang) team.
   • PR number and author are appended to the Progress Issue item matching PR title.
3. When PR changes are requested by a reviewer:
   • PR label changes: review needed → changes requested.
   • Bot writes a comment suggesting to comment /done when changes are finished.
4. When PR comment /done appears
   • PR label changes back: changes requested → review needed .
5. When changes are approved:
   • PR label changes review needed → needs +1
   • The next reviewer may request more changes leading to additional review needed/changes requested cycles.
   • When a reviewer is satisfied with the PR with needs +1, they should merge it.
6. When the PR is merged:
   • The progress issue item is labeled with [x].
   • The bot adds a congratulating comment.

Got any questions?

Create an issue and mention @iliakan or ask me: [email protected].

– Ilya Kantor