How To Localize Your WordPress Theme For Translation?

Localize a WordPress Theme

English is the preferred language while writing and documenting in WordPress. It is a common language that is quite handy for communication between developers, maintainers and users from all over the world. But from a 2012 WordPress survey, it was evident that almost two-thirds of WordPressers use English as a secondary language or don’t use it at all. And most people wish to have the option to select their own native language in WordPress and would rather be using their mother tongue for day to day’s work, as much as possible.

Hence, translating theme is a sought after topic. In the previous post for translation, we looked at translating themes that are translation ready. But as said, not all themes are natively translation ready. So, how do you make a theme translation ready?

You have to localize your WordPress Theme. As a WordPress theme developer, it’s best practice to localize themes so they are ready for translation. It’s actually a very easy process but is time consuming. But your efforts to localizing will allow people from over the world to enjoy your theme in their native language.

So, the question is:

How To Localize WordPress Theme?

Be familiar with i18n, l10n

To localize WordPress Theme, you need to get familiar with the terms that are its essence.

i18n is an abbreviation for internationalization. There are 18 letters between “i” and “n” and hence the name i18n was given.

l10n is short for localization and using the same logic as i18n, the name l10n is because there are 10 letter between “l” and “n”.

These two are processes that involves making a file ready for translation, or making the strings in your files so they can be translated.

Understanding the Localization Framework

WordPress uses the GNU gettext localization framework for translation.  It uses 3 types of files:

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 passes into a  __() or __e() function, generating a POT file. This file will contain all the text available for translation.

PO (Portable Object) files: This 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 this final step, the PO file is converted into a machine readable format.

Include The load_theme_textdomain Function

In order to prepare your WordPress theme for localization, you need to include a function into your function.php file which will search your theme directory for “for and load it (where locale is the current language, i.e.” – see the codex.

  1. So add the following function to functions.php:
     load_theme_textdomain( 'yourtheme', templatepath.'/languages' ); 
  2. Change the term ‘yourtheme’ to the name of your theme, just make sure to keep it as 1 word to avoid any issues.
  3. Change the Template path to the location where you will store your translation (.po and .mo) files.

Localize Your WordPress Theme

The next step is to edit your theme files to change all your text strings into functions. You can do this by changing all the text used in the WordPress theme to functions so the translation tools know what text to replace for translation. You need to wrap them in a __() function call. So:

<?php echo '<h2>Hello world!</h2>'; ?>


<?php echo '<h2>' . _'Hello world!', 'yourtheme') . '</h2>'; ?>

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

<?php echo 'Hello world!'; ?>


<?php _e('Hello world!', 'yourtheme'); ?>

You can also wrap regular text. For example:

Hello world!

Would become:

<?php _e('Hello world!','yourtheme')

Create POT files & Add Textdomain to Funtions.php

Now that your theme files are ready for translation, you need to create a POT file. POT files are often created by theme authors and delivered along with the theme to help translators. Poedit is the most commonly used program for this.

  1. Install Poedit.
  1. Open Poedit and go to Catalog
  1. Under Catalog, click Properties to open Catalog Properties window.
  1. Enter a name for your project (the name of your theme is fine). Poedit 1
  1. 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. Personally, I put my .po and .mo files in a “Languages” folder in my theme so may base would be “../” Source paths - Catalog Properties
  1. Click on the Sources keywords Here, we need to define the functions we used to localize the text in our theme files, __()and _e().Source keywords - Catalog Properties
  1. Then, click OK. You’ll be asked to name and save your POT files. By default, Poedit will want to save your file as .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 your theme, give it a .pot extension and save it folder named “Languages” in your theme directory.
  1. After 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.
  1. Last step – save your POT file.

Now, your theme is translation ready.

If you want to learn how to translate your now localized theme, check out our previous article on How To Translate Your WordPress Theme.

Do you localize WordPress themes you develop? What intrigues you about translation? Tell us in the comments below.



Leave a Reply

Your email address will not be published. Required fields are marked *