Internationalization for Your WordPress Theme

Abbas Suterwala

WordPress is used to create a variety of types of websites. When building a WordPress theme, you should build it for as large of an audience as possible. That goal also implies that your theme should be ready for sites in different languages. WordPress provides a simple API that you can use in a theme to provide internationalization for it. In this article, you will see how you can make your theme ready for different languages.

How to Configure WordPress for Different Languages

You can add different languages to your WordPress site. For that, you can download the translation files from the blog of the WordPress translator team. From this page, you can see the various languages whose translations are present, as well as what percentage of the translation is complete. Suppose I want to download the French language. I will go to the French language row, then click on the percentage as shown in the image below.


Then, you can click on the WordPress version, and export the .mo file as shown in the image below

Export .mo Files

Once you have downloaded the .mo file, you will have to upload it to the wp-content/languages folder of your WordPress installation. You can then go to the Settings -> General in your WordPress admin. There you should be able to see the language options which you have put in the wp-content/languages folder as shown below in the image. Please select the desired language you want to change the site to and click ‘Save Changes’


Loading the Text Domain in Your Theme

The first step to internationalization for your theme is to create the theme. You can start, in this example by creating a child theme of the theme twentyseventeen. To create a child theme, first create a folder wp-content/themes/wpinternationlizationtheme. In this folder add the file style.css with the following content:

 Theme Name:   wpinternationlizationtheme
 Description:  Twenty Seventeen Child Theme.
 Author:       Abbas Suterwala
 Author URI:
 Template:     twentyseventeen
 Version:      1.0.0
 Text Domain:  wpinternationlizationtheme

This file defines a child theme with the name wpinternationlizationtheme. This is the child theme of twentyseventeen. In the above, every field is standard fields which we define for a child theme. The field Text Domain is the field which defines a unique name for the text domain of this theme. This theme should load the translation files with this key as the unique identifier.

Create a functions.php with the following code

function wpinternationlizationtheme_enqueue_styles() {

    $parent_style = 'parent-style'; 

    wp_enqueue_style( $parent_style, get_template_directory_uri() . '/style.css' );
    wp_enqueue_style( 'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( $parent_style ),
add_action( 'wp_enqueue_scripts', 'wpinternationlizationtheme_enqueue_styles' );


The above code loads the parent theme (which is twentyseventeen in this case) styles. Then the styles from the child theme are loaded.

This allows the child theme styles to be the ones who are loaded last, and can be customized to the needs of the child theme. Now you’ll want to load the text domain, which means indicating where will WordPress search for the translations for this theme. You can load the theme’s text domain using the WordPress function load_theme_textdomain.

To do that, add the following code to your functions.php:

function wpinternationlizationtheme_setup(){
    $domain = 'wpinternationlizationtheme';
    // wp-content/languages/wpinternationlizationtheme/
    load_theme_textdomain( $domain, trailingslashit( WP_LANG_DIR ) . $domain );
    // wp-content/themes/wpinternationlizationtheme/languages/
    load_theme_textdomain( $domain, get_stylesheet_directory() . '/languages' );
    // wp-content/themes/wpinternationlizationtheme/languages/
    load_theme_textdomain( $domain, get_template_directory() . '/languages' );
add_action( 'after_setup_theme', 'wpinternationlizationtheme_setup' );

The above code hooks up to the after_setup_theme action. On that action, you load the text domain for the theme. This is done using the function load_theme_textdomain. This function is setup to look for the .mo files in the following directories:

- Languages directory
- Child theme directory 
- Parent theme directory

WordPress Functions for Internationalization

Once you have set up the text domain, take a look at the functions you can use for internationalization in WordPress. There are primarily two functions which you can use. The first one is __ . This function takes two arguments, the first being the string and the second the domain. This function then returns the approriate localized string based on the language selected.

So if you want to add some text at the end of each post, but also want this to be localized based on the language select, add the following code to your functions.php:

function wpinternationlizationtheme_after($content) {
    return $content . __('Read more', 'wpinternationlizationtheme');
add_filter('the_content', 'wpinternationlizationtheme_after');

The other function is _e. This takes the same two arguments as __. This function displays the localized text directly on the page rather than just returning it.

So, for example, if you wanted to add a footer message which should display localized, then you should create a footer.php with the following content:

_e('This site is powered by WordPress','wpinternationlizationtheme');

Creating the .mo Files

Once you have created the code necessary for internationalization you will want to create the localization files. There are many tools available to create .mo files. In this article, you are going to see one of the popular ones, poedit. You can download poedit for your operating system from

Once you have downloaded poedit you can select ‘file->New Catalog’ to see the following screen:

Project Info Screen

In this screen, you can enter the basic information about the project. The next tab is to give the path of the code which needs to be parsed to find the strings which need to be localized, as shown below:

Path Settings

The next tab lets you enter the keywords which need to be searched to get all the strings which need localization. As you have already used the two functions __ and _e in the above examples, add those two on this tab.

Keyword Settings

Once you have done this, the tool will search all the strings which need localization as shown in the image below.

Localization Screen

You can now add the localization for each string and then click ‘Save’ to save the file at wp-content/themes/wpinternationlizationtheme/languages/

Now, finally, if you change the language to ‘French’ you should see your strings localized in French on the main site.


WordPress is one of the most popular CMS platforms. You can learn about WordPress theme development with relative ease. The users of sites made on WordPress themes are vast in number and variety. Hence the pressing need for your theme to have a wide range of languages available. In many industries, it’s absolutely necessary for your WordPress site to be able to cater to an audience of different regions and countries.

Making your theme ready for internationalization can be a key factor for success. The WordPress API for internationalization is easy to use. It makes it very easy to localize your theme without changing any of the code files. So, have fun internationalizing your next WordPress theme, and tell us about your experiences in the comments below!