How to Translate a WordPress Theme

Translation is one of the most highly requested topics in the WPMU DEV support forums, and no wonder – according to the 2012 WordPress Survey, two-thirds of WordPress users live outside the US.

That’s a lot of people who probably speak English as a second language – and also people who develop websites for those who might not speak English at all.

So today I’m kicking off a series on translating WordPress. Over the next week I’ll feature a new post every day on translating different aspects of WordPress. If you have any requests please me know in the comments below.

In this first post I’ll show you how to translate a translation-ready theme.

This post is part of our Translation Week series:

Finding a Theme Ready to Translate

First things first, you’ll need to find a theme to translate. But you can’t just translate any old theme – you need a theme that has been localized using the GNU gettext framework. In other words, the theme is ready to be translated. If your theme hasn’t been localized, come back later this week for a run down on how to make your themes translation ready.

Developers don’t always create translation ready themes, so when you’re buying a premium theme make sure to ask if it’s translation ready.

Translation ready
The WordPress Theme Repository includes tags for finding translation ready themes.

If you just want a free theme, it’s easy to search for translation ready designs in the WordPress Theme Repository. Go to and go to Themes > check out our new filter and tag interface. On the next page tick “translation-ready” and click Find themes.

Once you’ve got your theme, open up the zip file and find the language folder. It should contain a POT file.

WordPress uses the GNU gettext localization framework for translation. There are three types of files used in the framework:

POT (Portable Object Template) files: The first step in the translation process is using a program to search through the WordPress source code to pick out text passed into a __() or  __e() function, generating a POT file. This file will contain all the text available for translation.

PO (Portable Object) files: The second step involves translating the text in a POT file into the target language, saving both English and translator messages in a PO file.

MO (Machine Object) files: In the last step, the PO file is converted into a machine readable format.

Translating Using Poedit

There are a few different options for translating WordPress, as outlined in the WordPress Codex. For this tutorial, we’re going to use Poedit, an easy to use open source program available for Mac OS X, Windows and UNIX/Linux.

1. Install Poedit.

2. Open Poedit and go to File > New catalog from POT file and select the POT in your theme’s languages folder.

3. A catalog properties box will pop up asking for information about what you are translating. Enter the language you want to translate here.

Poedit catalog
Enter the language you want to translate along with any other important details and hit “OK.”

4. After you hit “OK,” you’ll be asked what you want to name your translation file. The name is important and there’s a particular format you will need to follow. For example, if you’re translating Chinese for China, the file should be name zh_CH.po, and for a Tagalog translation for the Philippines would be tl_PH.po

Poedit language
Each language and country has a specific code you will need to use when saving translation files. This code indicates Tagalog for the Philippines.

Check out the GNU `gettext’ utilities to find your language and country codes.

Save your file in the languages folder of your theme.

5. Now you can start translating your theme. Poedit has a simple and straight forward interface that doesn’t involve a steep learning curve. The space at the top will display all the text ready to translate, and any completed translations will display to the right. The boxes underneath show the source text you’ve selected to translate, your translation and any notes for translators.

Tagalog Poedit
It’s easy to cycle through the text and enter your translations.

Translating a line of text is really easy – just select a word or phrase, enter your translation and click “Update.”

6. When you’ve finishing translating, simply save your file. Poedit will automatically create both .po and .mo files in your theme’s languages folder.

7. Now that your theme has been translated, you can upload it to your WordPress install either using FTP or by logging into your WordPress site and uploading your theme by going to Appearance > Themes > Install Themes (after you’ve zipped your theme, of course).

Setting Up Your Translated Theme in WordPress

As English is the default language for WordPress, you will need to play with a little code to force WordPress to use your translated files.

In order to do this, you will need to FTP into your WordPress install and open up the wp_config file and add this line of code:

define ('WPLANG', 'zh_CN');

This line specifies Chinese for China, so you’ll need to replace zh_CN with your language and country code.

Adding this line tells WordPress you want to use translation files for Chinese. Since you’ve translated only your theme and not your backend, your site will display in Chinese but your WordPress admin area will continue to display in English.

I’ll cover changing the default language for your WordPress backend in another post as part of this series this week.

Translation Tips

The WordPress Codex offers some solid tips for translation that anyone translating WordPress should keep in mind:

Don’t translate literally, translate organically: Languages have different structures, rhythms, tones, and inflections. Translated text don’t need to be structured the same way as the English ones: take the ideas that are presented and come up with a message that expresses the same thing in a natural way for the target language.

Try to keep the same level of formality (or informality):Try to accomplish the equivalent in the target language, within your cultural context.

Don’t use slang or audience-specific terms: Stay away from colloquialisms and to stick with what you think a new blogger would understand.

Read other software’s localizations in your language: If you get stuck or need direction, try reading through the translations of other popular software to get a feel for how they have tackled translations.

Have you translated a WordPress theme? What do you want to know about translation? Tell us in the comments below.

Image credit: orijinalWordPress State of the Word 2012.

19 Responses

    • 53 pts
      60 pts
      LEVEL 3

    The issue I have with the WP translation model is it presumes that the original labels are the same labels the theme / plugin users want to use.

    For example (and admittedly not the best one), perhaps I don’t want to call the blog a Blog but instead I want to call it News. So Blog in French doesn’t do me any good if I want News in French. See?

    My point being, there needs to be a way to move past simple and literal brute force language translation and allow for great theme and plugin label customization at the user+install level.

    This 2005 one size fits all approach needs some new ideas.

    IMHO, of course ;)

    • 3 pts
      0 pts
      LEVEL 0

    I think this article is massively missing out on how to configure POedit to actually use all wordpress based gettext variants, and only vaguely covers __() and _e() without describing how to configure POedit to use them, which it does not out of the box

    It also does not cover how to add a text domain to an existing theme, what commands load theme text domains v. what command loads plugin text domains, or in fact how to configure POedit to look for a specific text domain.

    It does not mention the difference in file formats between plugin and theme text domains.

    Also it does not cover how to update a text domain with new items that you might have coded that also need translation.

    And now I come to think about it, how to setup the base path so that POedit finds all the strings.

    in a word this article is “piffle”.

      • 802 pts
        9088 pts
        LEVEL 27

      Yes, but if you are importing from a POT file as this article assumes then all that stuff is done for you. Now if the developer hasn’t done their job then that’s a whole other technical tutorial.

      Raelene Morey
      • 30 pts
        57 pts
        LEVEL 3

      Geez, tough review! This is the first in a series and I’ve tailored this particular post to people who’ve never translated a theme before. Translation is a big topic so I’m breaking it down into several posts over the coming days, as I mentioned in the beginning of the article.

      It’s a shame you think it’s “piffle” but I hope this post helps other people who are learning about translation.

    pablo rey
    • 50 pts
      0 pts
      LEVEL 0

    The problem I face, is the poor PoEdit docs, I know there is a way of reusing the sentences already translated… but I can’t find who to do that.

    It surely is trivial question but I couldn’t find the answer.

    • 6 pts
      0 pts
      LEVEL 0

    A new alternative to poedit, is a new translation community effort called WP-Translations.

    The idea beyind this project is to create a community of translators based on wordPress standards and open source spirit.
    You stop translating by yourself and you can share what you have already translated. If it has be done once, why doing it again and again. Maybe your project is already translated.

    Plus devs can use a dedicaded client and directly pull your translations. Stop losing your translations, they got integrated as soon as they are ready in the next update.

    Interesting! you should have a look:

    What do you thing?

    • 53 pts
      18 pts
      LEVEL 1

    You say “2. Open Poedit and go to File > New catalog from POT file and select the POT in your theme’s languages folder..”. My theme has got a .po not a .pot file. What are the steps for a .po file?
    Do I import the .po file in Poedit and then save the output like fr_FR.po for example?

      • 6 pts
        0 pts
        LEVEL 0

      Yes open the po file and save it as plugin-slug-fr_FR.po for example

      But you also need to setup the properties of the file in Catalog>Properties especially the lang and the plural forms fields

    • 58 pts
      529 pts
      LEVEL 6

    Hi There,

    We are translating the front end part of themes on a regular basis. Always the same strings like “Commentary” “older”, “newer” and that kind of stuff.

    I wonder if there is a clever way to somehow copy these recurring strings to a new themes’s .po file.

    Any idea anyone?

    Thanks, Tee.

    PS.: Great article. Keep on going!

    • 3 pts
      0 pts
      LEVEL 0

    I struggled a little bit to get Poeditor running to translate my WordPress theme following your instructions. To make things clearer here are a few advices:

    1. Create a directory named “language” in your theme directory on your local machine (not on the live website ;-)

    2. Install Poeditor

    3. Go tot “File > New file” and than save it in the “language” directory

    4. Go to “Catalog > Preferences”

    Sources paths:
    Add “../” as base path
    Add “..” in path

    Sources keywords: do not add brackets
    Add “_e” and “__” and not “_e()” and “__()”

    Now my blog is working fine in French ;-)

Comments are closed.