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-lenczykpicked up the issue and implemented the bot.
cameeldid minor final touches and will help bring the repositories into the right shape (more details on that below).
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.
- 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.
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
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
These repositories will be updated:
These repositories are fine as is (already have commit history):
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.