Introducing the Translations PR Bot! 🤖

Documentation
1

The time has come to finally merge the long awaited Translations PR Bot!

If you haven’t been following the process so far, here is a bit of context:

  • To help the community organize the community translation efforts in one place, we set up a new GitHub org and a lean, GitHub-based translation workflow for new translations.
  • We wanted to make keeping the translations up-to-date with the English reference documentation as easy as possible, and asked for help from the community to implement a “PR Bot” that will help keeping the translation repos up-to-date: Repo Automation: Diff Bot for Translation Updates · Issue #8 · solidity-docs/translation-guide · GitHub
  • o-lenczyk picked up the issue and implemented the bot.
  • cameel did minor final touches and will help bring the repositories into the right shape (more details on that below).

What does the translation PR bot do?

In simple terms, the bot compares the English reference documentation to the state of the translation repositories and creates PRs with the (untranslated) difference between the English docs and the corresponding translation repository.

This way, translators know what parts of the docs have been updated and do not need to check this manually.

How does it influence the translations workflow?

  • The translation bot will create PRs in your language repository containing all the content that has been changed in the English version recently
  • To translate, update the pieces in the PR that the bot reverted back to English and then merge the PR. Sometimes the only changed parts will be the code snippets, which do not need to be translated - in that case the PR can be merged without any adjustments.
  • If there are multiple pending PRs from the bot, always use the latest (newest) PR, since it will have a compilation of all the changes included. You can then close all the old PRs, that are not needed anymore once you translated the newest.
  • Once your translation is complete and fully up to date, you’ll want to start creating version tags in you repository. For this reason the bot always includes the Solidity version in PR titles. If you have pending PRs for multiple versions first deal with the latest PR for the oldest version, then create a tag, and only then proceed to the PRs for the next version.

Updating the repositories to the right format

In order for the translation bot to work, the translation repositories need to have the full commit history of the Solidity repository.

Since some of the translation repositories were originally created without it, by simply copying the English docs at a specific point in time and committing them, cameel will add the history. A copy of the develop branch from the main repository up to the time when you took a snapshot and started working on it will be pushed to your repository. It will also contain all the translation work you did on top of it. We will then change the default branch of your repository to this new develop branch.

You can expect the first PR from the bot to be big, especially if your copy of the documentation was made a long time ago - it will contain all the documentation changes that happened since then.

Note that each repository will still retain the original branches so nothing can be lost in the process. Your original branch will now be obsolete but it will still be there, exactly the way it was before the conversion. This is important if you’re actively working on your translation while the conversion is performed. Any commits merged into your old branch after the conversion will not be in develop and you’ll have to move them over manually (we can help). To avoid having to do this, please ensure that all your local work has been pushed to Github. Also, any open PRs will need to be rebased on the develop branch.

These repositories will be updated:

  • Korean
  • Japanese
  • Persian
  • French
  • Indonesian
  • Portuguese
  • German

These repositories are fine as is (already have commit history):

  • Spanish
  • Russian
  • Chinese
  • Turkish

We will start the update process for the affected repositories on Wednesday, July 13.

Subsequently, we will enable the bot in all repositories step-by-step.

We hope the PR bot makes contributions easier and your life as a translator easier!

Please let us know if you have any feedback or questions.

Also, make sure to join the Solidity Docs Community Translations coordination channel on Matrix if you didn’t do so already.

2 Likes
2

Hello everyone!

As announced above, we’ll be converting repos and launching the bot today. The plan is as follows:

  1. Repository conversions
    • I have already converted de-german, which at this point is just a test repository (no active translators there).
    • Later today I’ll push the new develop branch and set it as the default branch in the following repos:
      • fr-french,
      • id-indonesian,
      • ko-korean,
      • ja-japanese.
      • pt-portuguese
    • fr-french and ko-korean have open PRs. It’s just one PR in each of them and there does not seem to be much activity in the PRs so I’m going to go ahead and rebase them myself. No action from translators needed.
    • There’s one repository where conversion is more tricky due to past conflict resolutions: fa-persian. I’ll need to handle that one specially and I’ll be doing that only after I’m done with everything else.
  2. Bot launch
    • I’m configuring the bot to check for new changes in the English docs daily, around midnight UTC. I think this might be too frequent and annoying in the long run but initially that will give us chance to spot and resolve problems quickly. After some time we’ll adjust the interval based on the feedback from translators.
    • Today I’ll enable the bot for de-german and one extra repository as a canary. es-spanish looks like a good target since it has recent activity and the translators seem reachable via Matrix.
    • In the next few days I’ll be enabling the bot in more repositories.
    • The Turkish team opted out of the bot for now since they want to have a complete translation of 0.8.15 docs first. We’ll be enabling the bot in their repo only after that goal is reached.

Hopefully it all goes smoothly.

1 Like
3

The bot is now enabled in the Spanish repo and should start creating PRs soon.

Conversion went without major problems. Below is a list of extra stuff I needed to do in each repo.

fa-french

  • Deleted old develop branch (was merged anyway)
  • The repo has one tag (v0.8.11) and it still points at the old version without history (so that it cannot be fully deleted). The tag could be moved to the corresponding commit in the new version d5cffba0 but changing published tags is discouraged to I leave that decision to the maintainers of the repo.
  • I rebased the branch from PR #7 but github does not like changes like that and closed the PR. The branch is still there and is rebased but the submitter needs to create a new PR.
    • You can also see the original commits from the PR at n1c01a5-main-backup. Can be safely deleted after making sure nothing’s missing (which should be trivial given how simple the PR is).

id-indonesian

  • A big issue in this repo was that all files were converted to DOS line endings. This makes git see everything as just deleted and recreated from scratch. I fixed the endings while rebasing.
  • The repo was using the old structure with files directly at root. I moved them into docs/.
  • Some file names in the repo were translated. I had to change that back to English to get changes properly detected by git.

ko-korean

  • Here I just squashed some commits while rebasing. The one deleting .vscode folder (seems to have been added by mistake) and “Bind Auction - Simple Open Auction (unsaved issue fixed)”.
  • This one has a PR too. I rebased its branch but left it for the submitter to pick up to avoid having github close the PR.

ja-japanese

No extra changes needed here.

pt-portuguese

  • There were only a few sentences translated in this repo (in index.rst) and by now they’re out of date and need to be retranslated anyway so I decided to simply recreate the repo from scratch. The translated bits can still be seen in index.rst from commit 188711f8.
  • I deleted the basics branch, which was at the same commit as main.

fa-persian

  • This one is still TODO.

Repo settings

I slightly tweaked the configuration of all repos:

  • Disabled wikis in all repos except for fa-persian (which seems to be the only one actually using it). Feel free to re-enable if you actually want to use it.
  • Enabled “Automatically delete head branches” in all repos. PR branches are useless after a merge and it’s a good practice to delete them.
1 Like
4

The bot is now enabled for Chinese and Korean.

Also, the first PR from the bot is up in Spanish repo: Sync with ethereum/solidity@v0.8.15-99-g454603e17 2022-07-14. Any feedback is welcome.

5

Just a quick update. All repos are now converted and bot is enabled for German, Spanish, Japanese, Korean, Russian and Chinese. Only Persian, French and Portuguese remaining and that’s mostly because first I want to do some tweaks to the PR description and improve the instructions on how to properly deal with it.