Localizing and Translating WordPress Themes

As a WordPress theme developer, it is essential to localize your themes to make them ready for easy translation. This process is simple yet time-consuming, but it allows people from all over the world to enjoy your theme in their native language. Nowadays, people expect all Premium WordPress Themes to be localized and ready for translation, which means they should include .po and .mo files and the appropriate code necessary for translation.

To help you localize and translate your WordPress theme, we have highlighted the various steps required below. It may take some time to get it right, but we hope that we can explain it in the easiest way possible so that you can get it done right from the start.

Step 1: Include the load_theme_textdomain Function

The first step is to include a function into your functions.php file that will search your theme directory for “for locale.mo and load it (where locale is the current language, i.e. pt_BR.mo).” You can see this in the codex.

To do this, add the following function to functions.php:

load_theme_textdomain( ‘framework’, get_template_directory() . ‘/lang’ );

Change the term ‘framework’ to whatever you want, which can be the name of your theme. Just make sure to keep it as one word to avoid any issues. Also, 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 that the translation tools know what text to replace for translation.

To do this:

a. Change echo functions:

Instead of using echo functions for showing text…

Use the _e(‘ ‘) function:

b. Change “naked” strings:

Instead of “naked strings”…

Some string

‘; ?>

Use the _(“) function:

‘ . __(‘Some string’, ‘framework’) . ‘

‘; ?>

c. Change regular text:

Instead of regular text…

Hi, I am Text

Use the _e(“”) function:

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, we are using the Poedit program.

To create the files:

1. Open Poedit and click on File -> New Catalog.

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

3. Click on the “paths” tab and enter the path for the files that need translating. We put our .po and .mo files in a “lang” folder in our theme, so our base path is ../

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

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

Step 4: Translate the .po File & Create a New .mo File

If you are selling 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.

To do this:

a. Translate the default.po file:

To translate the default.po file, open it in Poedit and enter your translations for each value (click on a string of text and enter the translation below as shown in the image).

b. Save a 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 pt_BR.mo. See the complete list of language codes and country codes to find your exact locale.

Example File Translated to Portuguese:



As shown in the example, when you save it, 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. Localizing and translating your WordPress theme is an essential step in making it accessible to people from all over the world. It may take some time, but it is worth it in the end.

Stay in Touch


Related Articles