Menu Close

How to Localize & Translate Your WordPress Themes


As a WordPress theme developer it’s best practice to localize your themes so they are ready for easy translation. It’s actually a very easy process (although time consuming) and it will allow people from all over the globe to enjoy  your theme in their native language.

At this point people actually expect all Premium WordPress Themes to be localized and ready for translation. This means that they include .po and .mo files and the appropriate code necessary for translation.

Below I have highlighted the various steps required to localize and then translate your WordPress theme. It took me several tutorials to finally get it right and I hope I can explain it in the easiest way possible here, so you can get it done right from the start.

Video Guide!

The easiest way to learn how to localize your theme is probably watching the video guide below. Enjoy!

Step 1: Include The load_theme_textdomain Function

The first step is to include a function into your functions.php file which will search your theme directory for “for and load it (where locale is the current language, i.e.” – see the codex.

a. So add the following function to functions.php:

load_theme_textdomain( 'framework', get_template_directory() . '/lang' );

b. Change the term ‘framework’ to whatever you want, it can be the name of your theme, just make sure to keep it as 1 word to avoid any issues.

c. Change the Template path to the location where you will store your .po and .mo files.

Step 2: Localize The Theme

The next step is to edit your theme files to change all your text strings into functions. You will do this by changing all the text used in the theme to functions so the translation tools know what text to replace for translation.

a. Change echo functions:

Instead of using echo functions for showing text…

<?php echo 'Some string'; ?>

Use the _e(‘ ‘) function:

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

b. Change “naked” strings:

Instead of “naked strings”…

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

Use the _(”) function:

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

c. Change regular text

Instead of regular text….

Hi I am Text

Use the _e(”) function:

<?php _e('Hi I am Text','framework')

Step 3: Create .po & .mo Files & Add Textdomain To Functions.php

Now that your theme is ready you can create the .po and .mo files that are used for translation. For this tutorial I am using the Poedit program.

1. Open Poedit then click on File –> New Catalog

2. Enter a Name for your project info (the name of your theme is fine)

Localize WordPress With Poedit

3. Click on the “paths” tab and enter the path for the files that needs translating. Personally I put my .po and .mo files in a “lang” folder in my theme so my base bath is ../

Poedit WordPress 2 Localize

4. Click on the “keywords” tab and enter _ and _e for the keywords (these were used in step 2 to localize the theme)

WordPress Keywords Poedit

5. Now save your default .po file into your theme’s “lang” folder.

Saving Poedit For WordPress Translation

Step 4: Translate The .po File & Create A New .mo File

If you are selling the theme or giving away the theme for free you can simply include the default .po and .mo files and you are DONE.

However, if you want to translate your theme you now have to edit the default.po file to add your translations and save it for use.

a. Translate the default.po file

To translate the default.po file all you have to do is open it in Poedit and enter your translations for each value (click on a string of text and enter the translation below like shown in the image).

Wordpress Poedit Theme Translation

b. Save new file with translation

Now you have to save your translated .po file using a specific naming convention.

The naming convention is based on the language code (e.g. pt for Portuguese) followed by the country code (e.g. _BR for Brazil). So, the Brazilian Portuguese file would be called See the complete list of language codes and country codes to find your exact locale.

Example File Translated To Portuguese:


And as shown in the example, when you save it will automatically create both the .po and .mo files for you.

c. Add new .mo file to theme’s “lang” folder

The .mo file created in part “b” needs to go into your theme’s lang folder (or wherever you defined in step 1 of the tutorial).

Step 5: Change Your Language

Simply go to Settings > General and change the “Site Language” option.


If you have done everything correctly your site should now show the translated strings you created in step 4 on your site by locating and substituting the default strings in your theme.

View Source
Posted in WordPress