How to Translate a WordPress Plugin

Step 1: Internationalizing a Plugin

Internationalizing a plugin essentially means making it ready for translations. This involves wrapping translatable strings in special functions which will be used later to load the correct translations.

The function we’ll be using is __(). This function takes two arguments: the text to translate and the text domain, it looks something like this in action:

<?php $greeting = __( 'Hello There!', 'text-domain' ); ?>

The function returns the translation for the marked string if it exists. If it doesn’t, the original string is returned.

It uses the current language to determine the needed translation. You can switch languages in WordPress in the Settings section, whatever setting is selected there will be applied to all translations.

The text domain is the final missing piece of the puzzle. A text domain is a way to group translations that belong together. The theme you are running will have its own text domain and so will all your plugins. This makes it easy to differentiate between them.

Note that for plugins the text domain should be the name of the plugin’s folder. For example, the text domain could be my-awesome-plugin. To internationalize our plugin all we need to do is wrap our strings in the __() function.

Step 2: Mofidy the plugin’s header

You will have to add these 2 lines in your plugin’s main file:

* Text Domain: my-awesome-plugin
* Domain Path: /languages/

Step 3: Implementing Translations

We’ve now marked translation ready strings, but there are no translations anywhere in sight. We need to tell WordPress where translations for our plugin reside. The standard is a lang directory within our plugin. Create that folder now and use the following code in the main plugin file to let WordPress know where to look for translations.

add_action('plugins_loaded', 'load_textdomain');
function load_textdomain() {
    load_plugin_textdomain( 'my-awesome-plugin', false, dirname( plugin_basename(__FILE__) ) . '/lang/' );
}

Step 4: Create a Translation pot file

Download and run Easy Po.
Click File > New from source code files…
Go to Source Files
Select your plugin folder
Go to Build
Select your output file
Click Execute command

This way, you have created a pot file for you plugin and you can now translate it (eg. with loco translate).

Step 5: Traslate your plugin’s name and description

To do so:

Open your pot file with a text editor.
Add the code below in your pot file somewhere (eg. right below the base path line).
Save the file.
Open the pot file with PoEdit.
Press update and save.

Here is the code you need to inject.

"X-Poedit-WPHeader: my-plugin.php\n"

You will now see in the translations the name and description of the plugin.

Step 6: Check if your plugin is fully translatable

Here is a trick to do so. The logic is that we will show a dummy text, eg. xxx, wherever we have a translatable string at our plugin. This way we can easily find if a plugin is fully translatable.

Create a translation for your plugin by using Loco Translate. This will create a .po file for your language.
Open the my-plugin-el.po file with a text editor.
Find a replace all msgstr “” with msgstr “xxx” and save.
Go to your WordPress site and change the site’s language through Settings > General.
Now go to your plugin and see if all the strings show the xxx dummy string. If not, find these strings at your code and translate them using the method from step 1.

Updating a translation

Any time you add a new string to your plugin, you will need to update your pot file. To do so:

Go to your plugin’s languages folder.
Open your plugin’s pot file with PoEdit.
Press the Update button.