The fourth Advent Calendar post describes and evaluates 5 ways to localize WordPress Plugins and Themes.


As a WordPress developer you probably know how to prepare plugin and theme strings for translation using one of the localization functions (__(), esc_html__() etc.). This is called internationalization. If you are unfamiliar with this topic, head over to the corresponding handbook pages for themes and plugins.

Unfortunately, the official documentation about localization is outdated and cumbersome for packages that are not hosted on the WordPress repository. So after you read the handbook pages on internationalization make sure to return here. But what is localization you ask? Well, read on!

Localize WordPress Plugins and Themes – what is that?

When you are done internationalizing your code (see above), you (or someone else) need to localize it. This is the process of translating all strings found in your package. Depending on where you want to use and distribute your code, you will probably end up with so called “language files”. These are basically files with the following extensions: .pot, .po and .mo.

In this post, we won’t discuss how language files are structured or how they work. This has been answered several times before in a great degree of detail (the above-mentioned handbook pages are a good start). Instead, we will examine various ways to create language files, i.e. how to extract them from the source code (automatically).

1. GlotPress – Translate free packages online

If you plan to host your (free) package in the official theme or plugin repositories (or already do), you almost certainly will only work with GlotPress. Available at https://translate.wordpress.org, it allows you to propose, submit or change translations for any WordPress theme, plugins or even WordPress core itself.

It works by extracting translatable strings from the package’s PHP source code (and JavaScript code soon too) and providing an interface to easily translate them.

In other words: You don’t need to distribute language files manually with your package because WordPress will parse the source files, create the files and make them available for download on their servers.

GlotPress is a powerful tool that will ease the burden of localizing your package but as with any tool, it has some drawbacks: First of all, there’s no versioning of language files. That means that WordPress will always download the latest translation update.

Imagine you have a project that uses a plugin from the WordPress repository. Now, an inexperienced translator forgets to add placeholders to a string, creating a faulty translation. Since there’s no way to “freeze” translation at a certain stage (version) after you updated translations, the string is run through sprintf() on your server and because placeholders are missing, the PHP engine will trigger a warning. If the (production) server is configured incorrectly, the warning will be displayed, at least breaking your design or in the worst case your entire site without it being your fault.

The next disadvantage is directly related to missing versioning: If you use Composer to setup your WordPress projects (and you should!) and disable file edits, there’s currently no “good” way to manage (download) language files. Although there are some packages available, checking for translation updates and downloading them requires several requests which have a negative impact on deploy length.

AdvantagesDisadvantages
No manual maintaining/updating/distributing of language files necessaryNo versioning
Clean VCS, no “translation commits”No Composer support
Everyone can contribute translations, even in parallel!Time-consuming to correct wrong translations of languages you are not Project Translation Editor of
For packages, translation progress of 95%* is required before GlotPress generates and provides language files

*more information

2. Loco Translate – Translate private (customer) packages

After we looked at GlotPress and how it helps package authors and volunteers to easily manage and submit translations for free packages, let’s move on to another very helpful localization tool: Loco Translate.

At first glance you might think it’s a locally running version of GlotPress. While partially true, the fact it runs on your local developer machine allows you to localize packages not meant for public distribution. In an agency, when working with clients, most of the packages (plugins) you write are custom-built and will will never be published on the WordPress repository. This is where Loco Translate comes into play. It offers an user interface similar to GlotPress and since it runs in WordPress, all users who have access can contribute translations.

Also, it takes care of naming and saving language files so they will definitely be recognized by WordPress (given you internationalized your packages correctly). If translations are not used, Loco Translate offers various debugging tools and info to easily spot errors in your internationalization configuration.

AdvantagesDisadvatages
No manual maintaining/updating of language files necessaryTranslation changes clutter the history of your VCS repository
All your WordPress users can participate in translationNo parallel translating from two or more users

3. Loco Translate – Correct premium package translations

As we all know, custom file edits get overwritten if the package is updated. But what to do if you need to use a paid plugin that has not been translated to your language (yet)? What to do if the translation is incorrect? Of course, you can localize the plugin with Loco Translate as described in the previous section. Then, to “persist” your changes, you could submit the language files to the plugin author, hoping he will notice your message and include the files in the next plugin update. Mostly, you will need to send them by mail because there’s no public GitHub repository you could do a PR in. And if the author forgets to include your translation files, you lose all your work. Altogether, this process is very error-prone and arduous.

There must be a better way and luckily, there is: Loco Translate to the rescue once more! In addition of localizing private packages, the plugin is able to add or change translations of (paid) plugins “permanently”. It works (simply put) by adding a directory called loco/ in the default WordPress language files folder (wp-content/languages/). Then, it loads translations from this folder additionally.

This is exactly what you need. Following the official tutorial on custom translations, Loco Translate makes a copy of the existing language files (or create a new language) and saves them in the mentioned folder. This way you won’t lose your custom translations when the plugin is updated. However, this approach has a drawback: By default, Composer-based WordPress projects .gitignore everything in wp-content/. That means you now have to add the folder to the main project repository manually, heavily cluttering the VCS history. You could symlink the folder but this can become time-consuming.

AdvantagesDisadvantages
Fast and easy correction of existing translation of paid packagesYou still need to send translations to the plugin author if you want to “do it right”
Update-proofTranslations clutter the main repository for Composer-based projects
Plugin needs to be active for custom translations to work

4. Traduttore – The agency-wide GlotPress for private packages

Traduttore (Italian for “translator”) is the new kid on the block. Released in 2017, it “is a WordPress plugin that allows you to host your own WordPress.org-style translation API for your WordPress projects.” Simply put, it’s a self-hosted GlotPress that brings all the benefits of the “official” GlotPress to your private packages. Think about it: All advantages of GlotPress and the ease of Loco Translate combined for the ultimate translation workflow!

Since Traduttore is a WordPress plugin that runs in a standard WordPress installation, you can even let your clients translate their strings. Gone are the days when developers had to send strings to the customer by mail or in a ticket and had to enter translations manually.

Traduttore requires some initial amount of work to set it up. In addition to host the plugin itself, you also need to “register” your translation API endpoint in every package you want to translate. To keep this post short we won’t describe the steps needed to get started as there’s already a great official documentation.

AdvantagesDisadvantages
No manual maintaining/updating/distributing of language files necessaryNo versioning
Clean VCS, no “translation commits”No Composer support
Everyone who has access to the WordPress Traduttore runs on can participate in translation, even in parallel, and even clients

5. PoEdit – The legacy workflow

Last and least there’s PoEdit, a stand-alone app available for all operating systems. While it certainly is useful for general localization tasks, translating WordPress-specific packages is cumbersome and a very manual process. Not only do you need to keep an app installed (and updated), you also need to have the Pro version for WordPress support.

Once you have it installed, it works very similar to GlotPress and Loco Translate: It scans (PHP) source code files and provides an interface to translate strings one by one.

Compared to other tools mentioned in this post, there’s an additional step when you are done translating. You need to name the language files correctly and store them at the right place. Since naming convention differs between plugins and themes, you might get easily confused ({package}-{locale}.mo for plugins and {locale}.mo for themes).

In summary: Only use PoEdit if you don’t publish your package on the WordPress repository. And you may use it if you cannot install/use Loco Translate on your local machine for whatever reason.

AdvantagesDisadvantages
Crowd-sourced online translation suggestionsManual naming and distribution of language files
Machine translationTranslation changes clutter the history of your VCS repository
Not web-based, (charged) app needed

Conclusion

In this post, we listed 5 ways and 4 tools that help you localize your code or participate in localizing other’s code. Depending on your workflow, you now have a good basis to decide which tool is best for you.

At Inpsyde, we believe that Traduttore is absolutely the way to go for professional, agency-level WordPress development.

Do you know other ways to translate WordPress packages? What are your thoughts on Traduttore? Do you also think it’s the best tool for client packages? Or do you disagree with our rating? Feel free to leave a comment down below!

Leave a reply

Your email address will not be published. Required fields are marked *