How to localize themes in WordPress

How to localize themes in WordPress

You’ve heard about localization (internationalization) WordPress plugins, which automatically translate plugin text into your blog language without changing any codes. But what about localization themes? How can we make a theme multilingual? It is as easy as working with plugins as you’ll see in this post.

Loading theme textdomain

The first step to make a theme multilingual is loading theme textdomain. Assume that our theme language files (.MO and .PO files, we will create them later) are located in the sub directory /lang/ of theme directory (ie. /wp-content/themes/theme_name/lang/). To load these language files, open functions.php file of your theme and put this code into it:

$lang = TEMPLATE_PATH . '/lang';
load_theme_textdomain('theme_textdomain', $lang);

Here ‘theme_textdomain’ is theme textdomain. Change it into anything you want, but it has to be unique. Usually, the theme name is used for this parameter.

Using _e(); and __(); functions

Now open your theme files (index.php, header.php, sidebar.php, etc.) and find all places where you echo strings. And change them with following instructions:

Instead of using echo function:

<?php echo 'Some string'; ?>

use _e() function:

<?php _e('Some string', 'theme_textdomain'); ?>

Instead of using “naked” strings:

<?php echo '<h2>Some string</h2>'; ?>

use __() function:

<?php echo '<h2>' . __('Some string', 'theme_textdomain') . '</h2>'; ?>

Remember the ‘theme_textdomain’ parameter which we declared in the section above. These functions will look into the .MO files, if strings are found then they’ll use them, otherwise the original strings are used.

For more information about using localized functions, see in WordPress Codex.

Creating .MO and .PO language files

After changing theme codes, we need to translate the text. The translated text are put in .MO and .PO files (which are located in a sub directory /lang/ of theme directory).

The easiest way to create .MO and .PO files are using PoEdit. After download and install PoEdit, open it and go to menu File → New catalog. In the Project info tab, just enter some information about project like name, email, charset, etc.

In the Path tab, enter ./ for the Base path and add a new value .. to Paths:

In the Keywords tab, add __ and _e to keywords:

Click OK. PoEdit will automatically scan files in your theme directory, and list all strings. Your work now is just translating them. After that, save the file in format language.po (ie. pt_BR.po, de_DE.po, etc.) in the /lang/ directory.

List of keywords


That’s all. When you change blog language, all strings of theme are changed correspondingly. Localization is needed when you want to spread your themes or to sell them. I hope this post is useful for you.

In case you want to use a plugin to translate your site, please read this list of top 7 multilingual plugins.


  1. Hello! Thanks for this great post! Is there a way to explain the process to localize a wordpress theme that doesn’t have localization options? I’m planing to buy a StoreFront Theme and i need to localize in spanish. Thanks!

    1. You should ask the author of that theme to confirm that the theme supports localization. As I explained in this article, localization must be done both in theme code and using MO files.

    2. Hi! thanks for your answer. The theme developer already told me that his theme doesn’t offer localization, besides that, i wonder if its possible to localize it because that theme has a lot of things that i need and i think it worth the try. Thanks and sory for my english.

  2. I have prepared my theme files for localization, the theme is on the desktop, and after I enter all the information, etc. and run Poedit, I always get an error – “Updating Catalog Failed…”  Any suggestions?  Is my theme meant to be on my desktop?  Thanks.

Comments are closed.