Hedy Translation Tutorial
This page help to get you started if you want to translate Hedy.
Hedy is now (partly) available in different languages but we'd love to support more languages and complete the ones we have! Translating is hard work, but not hard. No programming experience is needed, but it takes a bit of effort to know how to translate. We use an external tool called Weblate (explain in depth below) for translation.
Before we dive into details, know that translation can be a bit cumbersome, so if you have any questions or run into any problems, please reach out to us in the Discord translators channel, that our preferred way of communication. Alternatively, you can also reach us at hello@hedy.org but tends to be slower.
We regularly add content in English, and sometimes we make changes based on our own teaching experience. If you want to stay up to date with new content, register for the newsletter for translators and we will let you know when new texts are there.
There are different parts of Hedy that have been translated.
Most notably, the website and UI elements (shown in Dutch)
Explanation for kids to try in the different tabs (we call these: Adventures) (shown in Turkish):
Finally, code snippets are translated, and can use tranlated keyword, here shown in Chinese:
These different parts of Hedy are stored in different Weblate components. The Weblate documentation explains these components in detail, but you do not have to read all of that now.
The audience of Hedy are kids aged 10 and up, so where possible use language that fits our audience. Some parts are for teachers, like the teachers guide, there a more adult tone can be fitting. English lacks a lot of nuance that is present in other language, so you will sometimes have to make decisions on style that are not present in the original texts. For example:
Gender. Some languages use gender in addressing readers, try to be inclusive of different genders when possible. Portuguese for example uses "Bem-vindo(a) a Hedy!" in the text.
Formal form. Some languages have a formal form of addressing people, like Dutch or German. These languages tend to use the informal form in Hedy (jij, Du).
If you run into concepts that do not exist raising questions, you can firstly try to look at a similar language what they choose (explained below how that works) or alternatively, you can ask us in the Discord translators channel.
One element of Hedy that can be translated are keywords, for example like this in Portuguese:
The keywords here are translated, but as translator you do not have to translate them, which can be confusing!
This is what that looks like in Portuguese:
And this is what you would translate from, in English:
As you can see, the keywords are not translated, but always shown in English between curly brackets, these ones -> {}. To help you remember to not translate the keywords, they appear grey in Weblate.
When translating, it is important to leave the curlies in and leave the keywords in English. The curlies help our engine translate the keywords automatically, so you only have to changes them in one place, and that place is not in the snippets. Please do not translate them or the code will break. This is not a real problem (it will not break on the website, because we test all code you translate) but we will have to fix the snippets which takes time.
This is the general workflow:
If none of this means anything to you, don't worry and continue reading below. Just know that everything you translate will magically be send to us and will show up on the website after a while!
If you understand the above graph, you know that a pull request will be created automatically by Weblate, without effort. If you want your contributions to show up on your GitHub timeline (for example for #hacktoberfest) be sure to log into Weblate with your Github account and it will be connected and show on your profile.
The Hedy team maintains the English and Dutch translations of string, and we do our best to also maintain Spanish. All other languages are community translated, so they can be outdated, as English and Dutch are regularly updated. Content can also be wrong, since translators misunderstood content. If you encounter issues, feel free to make small improvements, there matter too!
Sometimes, translators make errors in code snippets, which is completely natural. Unfortunately, Weblate doesn't give us a good mechanism to catch Hedy errors as translators are translating. We can only detect this quite late in the workflow: only after they've entered their translation into Weblate and a PR has been created. At that point, this error in a snippet is holding up all other translations from being merged. In order to keep the pipeline rolling, we revert the failing snippets back to the English version automatically (assuming that is correct), and we post a message to the Weblate PR indicating what we rolled back. It looks like this:
When this happens, we encourage translators to copy the previous code from the message and try again, keeping the error in mind. You can try the translated code in the actual Hedy editor for the right level to double check if it works or not.
A few common reasons that errors occur:
You have translated keywords in between curlies This is explained above
You have inconstantly translated variables
Let's look at the example above in English again:
What we often see is that a translator translates the first variable into their language (animaux in the example below in pink) but they forget another occurrence of the variable (animals below in dark blue), like this:
This too will break, since the variable animals can't be found. Again, don't worry, a test will pick this up, bit it will take us effort to fix it, so it would be nicer if you try to avoid this.
The easiest way to translate Hedy is by using the translation website of Weblate. You can find it here.
You will have to login first, you can choose which way you can login into Weblate.
After sign in if you look up right you see your profile. Now is time to make some changes in your profile so that you can translate using Zen mode. When you begin translating you might want to sit back and relax while working on your translations. This can be achieved with Zen mode. This possibility simplifies the layout and removes additional user interface (UI) elements. Open your profile like so and choose Settings:
When you choose Settings you land on this page. Here you have different options, you can focus now on Languages:
You can set a default language:
You can click now on Preferences:
Here you have options between Full editor and Zen mode. Choose Zen mode. You can also choose between having your translations listed Top to bottom or Side by side:
Scroll bellow and click Save:
You should now see this:
For the new changes and updates to really take place you will have to Sign out and Sign in again.
When you are logged in again you can choose for example from your profile Hedy:
Here you land on a page that shows you different Components (you have seen this before you changed your translator profile into Zen mode). You can choose for example Adventures:
After you have chosen Adventures you can see for this specific component the translation progress of different languages. The language you set up by default in your profile will show up at the top.
You can click on your language and see the progress Overview for component "Adventures". You can now click on Browse.
You can now click on Browse. This will land you on this page. The marked in red strings are not yet translated or need editing:
Click on a red string and it will land you on this page. You can now start translating.
Depending on the choices you made on your preferences Side by side or Top to bottom, you might see this:
While translating you might notice at the top right of your screen you see a smal text: Exit Zen. You can click on this if you want, this will change your UI, showing more information about Glossary and Nearby strings.
You can always come back to the Zen mode by clicking on Zen button at the top right of your screen (lightning symbol).
If you have any questions or run into any problems, let us know, you can reach us at hello@hedy.org, or you can join our Discord translators channel
People with programming experience and experience on Github might prefer to translate the files locally. You can do this by simply creating a fork of Hedy and translating files locally. There are two location for the files:
- in /translations, in the po files
- in /content in yaml files
In both cases, the ISO language code for your language is the filename (for example: nl.yaml is the text in Dutch).
Make changes locally, push your branch and create a pull request (PR).
If you have no strong preference, we prefer changes in Weblate, since we will then have all changes together in one PR.
The remainder of this document covers a few more advanced topics related to translations. Of course you are free to read all of it, but it is not needed to know these things for regular translators (so don't worry if you don't get it at all!)
If there are too many changes, Weblate might not be able to resolve them automatically. You will then have to fix stuff locally, to do so, follow these steps:
- Gather the commits from weblate by adding an extra remote to your local repo
git remote add weblate https://hosted.weblate.org/git/hedy/adventures/
This enables us to contact the weblate repo.
-
Now grab the Weblate commits With
git fetch weblateyou get all commits that exist in weblate. -
Make a new branch Switch to a fresh branch with
git checkout -b newbranchname -
Merge Weblate commits in Now with
git merge weblate/mainyou can merge the Weblate commits into the current branch. This can lead to merge conflicts (in fact, it will, cause why otherwise would you be going through all this trouble?) that you will have to manually fix. -
Push the fixed branch Now push newbranchname and Weblate is happy again, because it will see that all its commits are in the repo.
-
Accept but do not click merge! If all is in order (all tests pass), you can accept the PR. But! Do not merge it with the button since Weblate PRs require a merge commit instead of a squash merge. Mergify will do this automatically.
Weblate creates a PR every morning, which will be merged automatically. When translators edit translations on Weblate in the period after Weblate has created a PR but before it has been merged (takes about ~1 hour), Weblate can get into a state where it has merge conflicts.
To resolve those, do the following:
- Run the Resolve Weblate Conflicts GitHub Workflow
- Afterwards, click "Reset" on the Weblate Repository Maintenance page.
Sometimes Weblate gets angry because we accidentally repeat a certain key. Since Babel does not care about that, we only see this when we have merged into main and Weblate is updated. Maybe there is a setting that can fix that but for now, this little bash magic will also tell you where the problem lies:
-
For the po files:
for x in */LC\_MESSAGES/messages.po; do echo $x ; sort $x | uniq -c | grep "2 msgid"; done -
For
messages.pot:sort messages.pot | uniq -c | grep "2 msgid"
There are a few Weblate peculiarities that are handy to know in working with the strings. If you add a new string in the code base in English, it will be automatically copied to all languages in English, and then shown in English in the UI. However if you
Installing wlc pip install wlc gives you some control over the Weblate environment. To use this, create a .weblate file in the root and put the following content in there:
[weblate]
url = https://hosted.weblate.org/api/
translation = hedy/adventures
key = <personal key>
The personal key can be found in your profile on Weblate.