Improving Our Translation Workflow

Automating WordPress Translation Updates With GlotPress

Pascal Birchler,

We set out on a mission to reduce the repetitive work involved in managing translations for our custom built themes and plugins. Additionally we wanted to enable our clients to easily translate strings instead of having to sending translations back and forth. The result is Traduttore, a liaison between WordPress, GlotPress and GitHub. Of course it’s all open source.

Soon after the release of WordPress 15 years ago, support for internationalization was added to the software. This meant that themes, plugins, and WordPress itself could be translated. This was a huge deal as WordPress is used all over the world today, in countries where English is not the main language. WordPress was quickly translated into German, Japanese and many more languages.

Today the translations for WordPress core can be easily managed on translate.wordpress.org and users automatically get translations once updated. The same goes for plugins or themes on the official WordPress.org repositories. Unfortunately, private plugins and themes don’t benefit from this translation platform. For these projects you need to go through many manual steps to update the translations.

Screenshot of translate.wordpress.org
Thousands of translators make WordPress available in over 170 languages.

For instance, you need to extract all translatable strings from the source code to create a so called translation catalog file (the ones with a *.pot extension). This file is then used as the base for translations. To add translations we normally use editors like Poedit to create machine-readable translation files that can be placed in the plugin or theme. When you want clients to add translations on their own, you can’t expect them to install new software just for this. On the other hand, converting the generated files into another format and sending translations back and forth is quite cumbersome and not really a viable option either.

With most of our clients located in Switzerland, a country with four official languages, we deal with multilingual websites and translation files all the time. There had to be a better way to manage them.

Meet Traduttore

Luckily, our team member Dominik is the lead developer of GlotPress, the software that powers translate.wordpress.org. Soon after joining us, he set up a similar platform for us and our clients. This allowed us to import catalog files into our GlotPress installation and let clients add their translation. The final translations could then be downloaded and copied into the plugins and themes.

Now, this change was quite an improvement. We could simply send our clients a link to our translation platform and then update translations with the next release/deployment. However, there were still many manual steps involved. We eventually figured: when WordPress.org can do automatic translation updates, why can’t we?

How The Translation Platform Works

We figured that if we could mimic the behavior of the WordPress.org translation API, we could automate all the things. That’s when we began writing a plugin called Traduttore, which is Italian for ‘translator’. A play in three acts:

First, we didn’t want to manually create and import translation catalog files anymore. Hence we built a direct integration with GitHub to do this behind the scenes. Whenever we push new code to a plugin or theme repository on GitHub, GitHub sends a webhook event to Traduttore’s REST API endpoint. The plugin then checks out the latest changes and imports strings using an all new wp i18n make-pot command I helped build. This command is fully open sourced and available on GitHub. The goal is to bundle this command with WP-CLI itself so others can benefit from it as well.

Second, we needed a way to prepare so-called language packs that could be downloaded by WordPress. Every time someone updates translations on our platform, Traduttore generates a ZIP archive containing all the current translations. All ZIP archives are available via a simple API endpoint similar to the one on WordPress.org. That means WordPress will understand it right away.

Third, with string extraction and ZIP archives now in place, we needed a way to tell WordPress where to find our new language packs. For this, we built a small library that can be used in a theme or plugin. It simply points WordPress to the API endpoint with the ZIP archives. We called it Traduttore Registry.

required Translation Platform Context Diagram
Putting our translation platform into context

The Benefits

Thanks to our new setup, we don’t have to worry about keeping translations up-to-date anymore. We save time by not dealing with merge conflicts due to updated translation files and our clients can translate their websites via an easy-to-use web interface. They don’t need us to release new translations either. Everything happens independently. As an added benefit, we’re now much more cautious to make sure all strings are easy to translate and as unambiguous as possible.

Traduttore Slack Notifications
Traduttore even notifies us on Slack whenever translations are updated.

Summary

After setting up a GlotPress-based translation platform for us and our clients, we finally take full advantage of it. Today, translatable strings our automatically extracted from the source code and made available for translators. The final translations are then automatically downloaded by the websites whenever they are updated.

All the code involved in this is 100% open source:

  • Traduttore extracts source code and generates ZIP files containing the translations.
  • Traduttore Registry introduces your WordPress plugin or theme to these new ZIP files.
  • WP-CLI i18n-command allows you to easily generate translation catalog files.

Note: Traduttore and Traduttore Registry are also available on Packagist alongside many of our other open source projects.