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: Creating a Translation

  1. Buy, download,install and launch Poedit. You will need the professional version because it lets you create pot files and also translate the plugin headers.
  2. Click File > New
  3. Give a language (eg. English)
  4. Save your files (.po and .mo) to the desired folder
  5. Click Extract from sources
  6. On the Sources paths tab, add the folder to which you will scan for strings.
  7. On the Sources keywords tab, add __ and _e.
  8. On the Translation properties tab give the name of your plugin and your team


  1. Download and run Easy Po.
  2. Click File > New from source code files…

Step 5: Traslate your plugin’s name and description

To do so:

  1. Open your pot file with a text editor.
  2. Add the code below in your pot file somewhere (eg. right below the base path line).
  3. Save the file.
  4. Open the pot file with PoEdit.
  5. 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.

  1. Open poedit.
  2. Click File > New from pot/po file.
  3. Select your pot file.
  4. Select the language you want to translate it (let’s say for example Greek) an press ok.
  5. Save your file and name it like my-plugin-el. The last 2 characters, el in our case, is the language code.
  6. Open the my-plugin-el.po file with a text editor.
  7. Find a replace all msgstr “” with msgstr “xxx” and save.
  8. Open the my-plugin-el.po with PoEdit.
  9. Go to your WordPress site and change the site’s language through Settings > General.
  10. 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:

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

Learning resources