How to Localize a WordPress Theme

Posted OnJul 31, 2014     CategoryDevelopment     CommentsNo comment

This guide will show you how to localize your WordPress theme – making it ready for translation. This might seem daunting, but it’s actually a relatively simple task that is important for every theme developer to know.

Why Localization is Important

Currently, on alone, 29% of blogs are published in 119 different languages other than English. That’s a size-able chunk for any developer to consider and doesn’t even take into account those users with self-hosted WordPress sites. Or those using English as their second language. If you care at all about usability, making your theme translation ready is a huge matter for that 29%. You can get up to the minute stats on usage here.

What This Guide Will Cover

To localize your WordPress theme you will mark all of the strings contained in it’s files by wrapping them in a gettext translate function. You then generate a translation ready file which contains all localized strings. For this step you will need to download and install Poedit – a fantastic and simple program used to generate your POT file (which translators need to create new language files for your theme).

The localization process is sometimes referred to as “l10n” (because there are 10 characters between l and n in the word localization). l10n is the abbreviation and l10n.php is the WordPress include which contains all the localization functions.

So, where do you begin? Let’s get down to it.

Load a Text Domain for Your Theme

A textdomain is required for the translate functions which we’ll be using next. Load a text domain in functions.php with the load_theme_textdomain() function. Add this line, replacing “yourtheme” with the name of your theme:

load_theme_textdomain( 'yourtheme', get_template_directory() . '/languages' );

You can use whatever path you like for the language files, but it makes sense to name the folder “languages”. Add this folder to the root of your theme.

Localize Your Theme

Now you’re ready to edit all of the strings contained in your theme. We’re going to wrap each one in a function which will make it translatable. There are a few aliases of the translate function you can use to identify your strings.


This is the basic localization function which you can pass two arguments – a string and your text domain. This makes the string ready for translation and is often used when passing text to other template functions. For example:

<?php edit_post_link( 'Edit', '<p>', '</p>' ); ?>

Would become:

<?php edit_post_link( __( 'Edit', 'yourtheme' ), '<p>', '</p>' ); ?>


This function works in the same way, but also echoes the string. For example:

<h2>Not Found</h2>

Would become:

<h2><?php _e( 'Not Found', 'yourtheme' ); ?></h2>

_x() or _ex()

Sometimes a particular word is tricky to translate. It might have multiple meanings or it could be an idiom or colloquialism. These aliases allows you to add a note to the translator which provides context for the string. For example:


Could become;

<h2><?php echo _x( 'Bear', 'Noun: Big grizzly bear', 'yourtheme' ); ?></h2>


<h2><?php _ex( 'Bear', 'Verb:  This tree can bear fruit', 'yourtheme' ); ?></h2>

_x() localizes the string and provides context whereas _ex() echoes the string as well.

When you have finished editing all of the strings in your theme templates and functions, it is time to move on and create your translation ready language file.

How to Create Your Language (POT) File

Next we’re going to to generate your new POT file using Poedit. Once you pack your POT file with your theme it will be translation ready. Translators will be able to use Poedit to create more language files to suit and people from all over the world can enjoy your theme.

  1. Install and open Poedit.
  2. Choose File > New Catalog
  3. This will open a new Catalog Properties window. You’ll need to fill in the details under each tab.
    Poedit - Catalog Properties

    Poedit – Catalog Properties

  4. First enter your theme details and language options under Translation Properties.
  5. Next, click on Sources Paths. Here we need to edit the Base Path. If you created a languages directory in the root of your theme, you’ll need to tell Poedit to look at all the files in the parent folder from that using ../ as your Base Path. You can add extra paths below as required.
  6. Now navigate to the last tab, Sources Keywords. Here we’re going to list the function names we have used to mark our strings: __, _e, _x and _ex.
  7. When you click OK you’ll get to name your POT file and choose where it will be saved. Name it after your theme and manually choose a .pot extension instead of the default .po which Poedit will suggest. Then choose to save the .pot file in your themes languages folder.
  8. This time when you click OK, Poedit will scan all of the paths you specified under Sources Paths. You’ll see all the localized strings from your theme listed.
  9. Save your POT file.

You’re Done

Your theme is now localized and can be tagged as translation-ready.



Leave a Reply

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

Send this to friend