Translate a plugin or theme without additional software or plugins

If you want to translate a plugin or theme, I would always recommend to use the free Poedit software which is available on Windows, Linux and Mac. Even though the Pro version has some special WordPress specific feature, you don’t necessarily need it. But I can also highly recommend it. The one-time-payment is quite a good deal and it will save you a lot of time, especially translating themes, which have many similar strings.

But this blog post is not about how to use Poedit to translate plugins and themes. I want to show you how you can translate them using just just commands on a terminal. So even if you can’t translate using additional software (or plugins), it’s possible.

Create a translation template

The first step is creating a POT (Portable Object Template) file with all the strings your plugin/theme is using. When I use Poedit, I usually skip this step and use a language specific template that will allow Poedit to scan for all translatable strings. The easiest way is using a WP-CLI command to create such a file:

wp i18n make-pot . languages/text-domain.pot

When you execute this command, it will scan all PHP and JavaScript files for string with the text domain equal to the plugin/theme folder name and create a POT file in the languages folder (make sure this folder exists). The command knows all the different functions that WordPress is using for translation (the same functions I have in my template above).

Create a locale specific translation

Next you create a translation file for a specific language by copying the POT file into a PO (Portable Object) file. This file has to be prepended with the locale:

cp languages/text-domain.pot languages/text-domain-de_DE.po

You can now open up this file in a text editor and translate the strings manually. In the header of the file you can also define the language but it’s technically not necessary.

Generate the binary translation file

WordPress is using MO (Machine Object) files to load translations. There is also a command to do this task which is available on many operating systems (or included in git bash, cygwin or similar on Windows):

msgfmt languages/text-domain-de_DE.po -o languages/text-domain-de_DE.mo

This is all you need to generate the translations. You can now check them on your WordPress installation (make sure you used the corresponding load_textdomain function to load translations for your text domain in your plugin/theme).

Bonus: Updating translations

Any time you add more strings or you change some of them, you have to update your translation files. When you use software like Poedit (and you have properly configured it), you can simply scan for those new string. When you just use the terminal, you can also achieve this. Just run the command again:

wp i18n make-pot . languages/text-domain.pot

But this will simply just overwrite the template file with a new version. As POT files do not contain any translated string (as the are not for a specific language), that not an issue. But how do you update your localized translation file, without translating all strings again? For this, you can use the merge argument:

wp i18n make-pot . languages/text-domain-de_DE.po --merge=languages/text-domain-de_DE.po

This will scan all PHP and JavaScript files from the current directory, merge in the current translation file and write everything back into this file. Only those strings that are not already in that file will be added. The already translated strings will be left as they are. The only downside: this will not remove any strings that are no longer in your PHP or JavaScript files.

Conslusion

When you really want to easily translate plugins or themes, use Poedit or a similar solution. But if you can’t use them, now you should be able to translate them using some simple commands.

One area, where the wp i18n make-pot command might be very useful is in your CI/CD workflow. You setup a task wich runs the command making sure that the POT file is always up to date with your latest development.

Posted by

Bernhard is a full time web developer who likes to write WordPress plugins in his free time and is an active member of the WP Meetups in Berlin and Potsdam.

Leave a Reply

Your email address will not be published.