How can I improve H5P translations?

Have you ever wondered why some H5P content types provide translations for a certain language while others don’t – and you wanted to add a translation? Or have you spotted a spelling error that nobody seems to notice but you would fix if only you could? You can!

The H5P core team does not consist of polyglots, but it is depending on your help. H5P is an open source project. That means that you can contribute to it in multiple ways, even if you do not know how to code … Adding and improving translations is one of those things.

One thing to keep in mind is that H5P content types need to follow a couple of rules in order to be translatable. Most do, but there are some where certain things have been hardwired into the code. Here you would need to be able to code in order to change that. But let’s leave aside those edge cases …

Contribute the hard way

There some form of default for contributing translations, but there’s a better way in my opinion. That’s why I will only mention this default method here for the sake of completeness. But only briefly, and I am going to assume some familiarity with terms or expect you to dig a little deeper yourself.

The source code of most content types is available publicly in repositories. Those repositories are scattered across different repository owners and even different platforms, so you’d need to know where to find them. We’ll use the True-False content type as an example here, because there is not too much to translate. You can find the repository on github.

If a content type is prepared for being translated, the repository will hold a directory named language. Duh! Inside, you should find a file named .en.json. That’s the English language template in JSON format. Just have a look at the template of True-False.

translation template file of H5P True-False content type showing a JSON structure

If you now wanted to translate that, you would need to fork the repository, copy the template into a new file inside that language folder and rename it appropriately using the ISO-639-1 language code as the file name followed by the .json extension. If there already is a file for the language that you want to work on, just open that one. Then, inside that file, simply translate all the JSON values, but not the keys – a line that needs translation would follow the scheme “key”: “value”.

It may help to open the editor of the content type in order to get a little context of that translation. Pay a little attention, because sometime values should remain as they are. For instance, something like @total should remain @total. It’s placeholder that will be replaced later on, here with the total score.

When you’re done, create a pull request, and that should have been it.

Contribute the not so hard way

There’s nothing wrong with the “hard” way. But it does not feel too convenient, does it? And there are a couple of things that could go wrong. One could, for instance, accidentally change the structure of the JSON file which would cause trouble and work on side of the H5P core team later on. And I left out that translations of editor widgets work a little different … Luckily, there’s a not so hard way to translate H5P content types.

Sebastian Rettig set up Translate H5P. It is based on Weblate, a software that was designed for localizing. Translate H5P offers a couple of advantages compared to directly translating the files:

  • You do not need to bother with finding the repositories. Most likely, the one that you want to work on has already been hooked up to Translate H5P. If not, it probably only requires a short message …
  • You do not need to bother with github or the JSON format. You will translate in a form in your browser and Translate H5P will take care of the rest.
  • You can see how terms have been translated in other content types and directly use that with just one click. This way ensuring uniform translations across H5P content types becomes much easier.
  • You can see how terms have been translated in other languages. This may provide some more context.
  • You can get notified when the translation template got changed, for instance when the content type got new features requiring new translations.
  • You can leave comments for other translators.

translation form of Translate H5P showing text input fields for different languages and other options

I am not going to describe how Translate H5P works in detail here, because Sebastian has already provided a “How to contribute” section. It essentially means to register on the site. Then you check where some work need to be done and you get going.

I also recommend to configure your newly created profile a little. For instance, you should list languages that you can translate to and languages that you can at least understand. If you want to track translation updates, you should configure the notifications. This way you will know when some help might be needed.

I can definitely recommend Translate H5P. Don’t forget to say thanks to Sebastian who maintains and fund that site!

Contribute the lazy way

You could also post translations on the H5P forum or hint to spelling errors there. That may be pretty, pretty, pretty convenient for you, but please only use that way as a last resort. You could do the change yourself. Just throwing typos into a post feels like you expect others to do the work that you could do yourself.

I have translated something, but it is still not available in the content type!1!! Why?

Neither creating a pull request directly nor via Translate H5P will immediately change anything in the official code. A pull request is kind of an offer to the H5P core team that they need to accept. There’s no fixed schedule, but they seem to accept new translations about every four weeks. That means they get included in the official code. Still, that does not mean that they will be available in the content type that you are using.

The H5P core team will need to release a new version of the content type, and that may involve other things. Unfortunately, there’s not even a rule of thumb for when a new release might come out. But I hope this at least explains why translations are not available immediately.