How to Localize a WordPress Theme and Make it Translation Ready

How to Localize a WordPress Theme and Make it Translation Ready

Localizing WordPress themes isn’t something developers should simply dismiss. And if you’re a developer who doesn’t know how to localize a theme, then you should definitely read on.

This is the second post in 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.

Yesterday, we looked at translating themes that are translation ready. But how do you make a theme translation ready?

In this post I’ll show you how to localize your themes and make them ready for a translator to convert into another language.

This post is part of our Translation Week series:

What is i18n, l10n and Why Should I Care?

I18n is an abbreviation for internationalization and is called i18n because there are 18 letters between “i” and “n.”

l10n is short for localization and you can probably guess why it’s referred to as l10n.

As far as WordPress goes – and for developers in particular – i18n and l10n refer to the process or making a file ready for translation, or marking the strings in your files so they can be translated.

The 2012 WordPress Survey revealed two-thirds of WordPress users live outside the US, so there are likely a heck of a lot of people who use WordPress and speak English as a second language and whose clients might not speak English at all. If that’s not a good enough reason to make your themes translation ready, I don’t know what is.

The idea of prepping your themes for translation might seem overwhelming, but it’s actually pretty straightforward and something every developer should know.

Understanding the Localization Framework

Firstly, let’s look at the types of files we’ll be working with so we can understand what’s involved in localizing a theme.

WordPress uses the GNU gettext localization framework for translation and 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. PO files are identical to POT files in every aspect except for their purpose.

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

Include the load_theme_textdomain Function

In order to prep your theme for localization, you need to include the following function in your theme’s functions.php file.

Change “yourtheme” to the name of your theme and “templatepath” to the location in your themes folder where you want to save your translation files. I would recommend creating a “Languages” folder in your theme directory and saving your files there.

Localize Your Theme

The next step is editing the text strings in each of your theme files and turning them into functions so they are translatable. To do this, you just need to wrap them in a __() function call. So:


If your code echoes the string to the browser, use the _e() function instead, so:


You can also wrap regular text. For example:

would become:

Create a POT File

Now that your theme files are ready, the next step is to create a POT file. POT files are often created by theme authors and delivered along with themes so translators can translate files using Poedit.

There are a few steps involved here. For this tutorial we’ll 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.

3. Fill in your project’s information in the Translation properties tab of the Catalog Properties window.

Poedit new catalog
You will need to fill out your theme’s details for each of the tabs in the Catalog Properies window.

4. Next, go to the Sources paths tab where you’ll need to enter the path for the folder Poedit will use to search for source files containing translatable text. Earlier in this tutorial I recommended creating a “Languages” folder in your theme directory and saving your files there. So in this instance the base path would be “../”

5. Click on the Sources keywords tab. Here, we need to define the functions we used to localize the text in our theme files, __() and _e().

6. After you click “OK” you’ll be asked to name and save your POT file. By default, Poedit will want to save your file as a .po file but since the two file types are identical you can get around this by simply choosing to save the .po file as a .pot file. Name your file after you theme, give it a .pot extension and save it in a folder named “Languages” in your theme directory.

7. When you click “OK” Poedit will scan the folders you specified in the Sources paths tab and will list the localized text in your theme’s  files.

8. Last step – save your POT file.

Now your theme is translation ready!

If you want to translate your theme, check out How to Translate Your WordPress Theme.

Do you localize WordPress themes you develop? What do you want to know about translation? Tell us in the comments below.

Image credits: orijinal.