Translating WordPress plugins

If you didn’t write the plugin – how do you translate it? I found lots of information for plugin developers to make their plugins translatable but not for people that just want to translate it.

Executive summary / tl;dr

Edit: The Codestyling Localization plugin I suggested previously isn’t available from WordPress directly any more.

Instead there seems to be an equally good plugin Loco Translate that is complemented by the developers own site for translating any application.

Failing that try the ‘Blank WordPress POT’ with POEdit and put that in the plugin’s languages directory. This seems to be a rock solid approach but takes a bit of learning.

If you put your translations in the plugins language directory, you’ll lose your translations when the plugin gets updated. Either keep backups or, if the plugin loads the translations correctly, you can put your translations in the separate wp-content/languages/[plugin-name] directory.

For worker ants who want to know a bit more

  1. The plugin must be translatable (It has been internationalized)
  2. You can check this by looking through the plugin code
  3. Otherwise just carry on and hope that the developer made it translatable
  4. Then you need to create a translation file that converts the English words into your language (localize it)
  5. A POT (.pot) file is a skeleton file that contains all the words and phrases in the plugin that can be translated
  6. A .po file is a .pot file that has had the translated strings in your language added next to each of the translatable phrases
  7. When you save a .po file it also generates a .mo file (where as you can read a .po file in notepad you can’t read a .mo file)
  8. WordPress plugins rely on .mo files
  9. You first need to find the .pot file
  10. Typically this will be in the root of the plugin directory
  11. Or it will be in a languages directory
  12. If you find it, great. Open it in POEdit, do your stuff and save
  13. If it hasn’t been created at all …
  14. … Then you need to check in the code (look for load_plugin_textdomain in the main plugin file) to see where/if you should create one and create the .pot file yourself

If you don’t know about editing PO files I suggest following the WordPress instructions on using POEdit.

For developers to ‘internationalize’ their plugins

I recommend using the Blank WordPress POT file that I mention below in the POEdit revisited section.

Translation fumbling


Initially I tried the POEdit method recommended in WPMU DEV tutorial

However the POT files that I made never worked – they didn’t pick up the translated words. I think it was because of __() and _e() instead of __ and _e.


  • WordPress
    and Tom McFarlin talk about using makepot.php but its confusing if you’re not using Linux
  • It requires using the wp-plugin as the project name which I assumed that you changed to the name of your plugin but you don’t – it has to stay wp-plugin
    so the required command is (for windows):
  • cd path\to\tools\i18n
  • php makepot.php wp-plugin path\to\plugins\your-plugin-name
  • However I got the following error when running it from windows
  • 'msguniq' is not recognized as an internal or external command
  • This appears to be because msguniq is a linux command
  • Actually this had created the your-plugin-name.pot file in the plugin directory but I just didn t realise because of the error
  • If you do want to use makepot.php use grapper’s Github i18n repo which includes all the correct WordPress files rather than the official WordPress subversion directories.

POEdit revisited

Hidden at the end of the WordPress localization document is the excellent ‘Blank WordPress POT’.

That can be put in the plugin’s languages directory and has instructions for creating the PO files from it:

The pot file include in this folder is ready to use.

  1. Double click on it and open it with poedit
  2. In poedit goto File → New Catalog from POT file…
  3. Select and Open the pot file from the languages folder
  4. Enter your name, email address, your language and country (i.e. french fr_FR, german de_DE) to the setting form
  5. Click the update button in the main poedit ui.
  6. Save the file :
  7. For a plugin like filename-xx_XX.po with xx_XX for your language and country.
  8. For a theme xx_XX.po
  9. That’s it, go to your WordPress blog and see your translation in action. N’joy your blogging!!!

This actually worked first time that I tried it – i.e. it pulled in all the translated strings.

First off you can then save the file as a my-plugin-name.pot file in the languages directory. Then you can add in your translations and save it with the locale xx_XX.po file ending and that should generate the .mo file that you need too.


Edit: The simplest route was via the Codestyling Localization plugin.

But that is no longer available through the WordPress plugins directly – possibly because it isn’t working or from a security issue. It is still available via the developer’s own site though

Instead you can use Loco Translate which appears to be excellent – but I haven’t tried it.

(These are old instructions for Codestyling Localization) Once it is installed:

  1. Click ‘Add New Language’
  2. Select your locale and it generates an empty .po file
  3. Click ‘Rescan’ to populate the .po file
  4. Click ‘Edit’ and ‘generate mo file’ to get the .mo file out

Dealing with plugin updates

None of this solves the problem that you will lose your translation files once when the plugin is updated.

Copy your .po files into the wp-content/languages/[plugin-name] directory – which might or might not work. If yes, great, if not raise a support query (be nice and give details) with the plugin developer.

This directory is update safe basically because of the translations are loaded with the following priority:

  1. wp-content/languages/[plugin-name] (never changed by updates)
  2. wp-content/languages/plugins/ (changed with updates)
  3. wp-content/plugins/[plugin-name]/languages (changed with updates)

If developers follow this Geert DeDeckere’s excellent guide on loading WordPress language files the right way then there shouldn’t be a problem with using the wp-content/languages directory.

You can also read WooCommerce’s documentation on Making your Localization upgrade safe which recommends either Loco or using /wp-content/languages/woocommerce.

I found these two Support questions useful for learning about handling upgrades:


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.