Localizing WordPress: Full manual for Apps Developers

Setting the Text Domain

For each of your site’s localized plugins or themes, WordPress needs to know how to locate your localization files. This is done via the load_plugin_textdomain(), load_textdomain(), and load_theme_textdomain() functions. All three functions are similar, but take different parameters and make sense in different situations.

Whichever function you use, it should be called as early as possible in your app because any strings used or echoed through translation functions before the text domain is loaded will not be translated.

Here are a few ways we could load our text domain in includes/localization.php:

load_plugin_textdomain( $domain, $abs_rel_path, $plugin_rel_path )

This function takes three parameters. The first is the $domain of your plugin or app (schoolpress in our case). You then use either the second or third parameter to point to the languages folder from which the .mo file should be loaded. The $abs_rel_path is deprecated, but still here for reverse-compatibility reasons. Just pass FALSE for this and use the $plugin_rel_path parameter:

<?php
function schoolpress_load_textdomain(){
    //load text domain from /plugins/schoolpress/languages/
    load_plugin_textdomain(
        'schoolpress',
    	FALSE,
    	dirname( plugin_basename(__FILE__) ) . '/languages/'
    );
}
add_action( 'init', 'schoolpress_load_textdomain', 1 );
?>

This code loads the correct language file from our languages folder based on the WPLANG setting in wp-config.php. To get the path to the current file, we use plugin_basename(__FILE__), and then dirname(...) to get to the path to the root plugin folder, since we are in the includes subfolder of our schoolpress plugin folder.

load_theme_textdomain( $domain, $path )

If you have language files for your theme in particular, you can load them through the load_theme_textdomain() function like so:

<?php
function schoolpress_load_textdomain() {
	load_theme_textdomain(
        'schoolpress', get_template_directory() . '/languages/'
        );
}
add_action( 'init', 'schoolpress_load_textdomain', 1 );
?>

load_textdomain( $domain, $path )

This function can also be used to load the text domain, but you’ll need to get the locale setting yourself.

Calling load_textdomain() directly is not recommended for plugins or themes, but could be useful for projects in which you want to use a single domain across many different plugins. Calling load_textdomain() directly also adds some flexibility if you want to allow others to easily replace or extend your language files. You can use code like the following to load any .mo file found in the global WordPress languages directory (usually wp-content/languages/) first, and then load the .mo file from your plugin’s local languages directory second. This allows developers to override your translations by adding their own .mo files to the global languages directory:

<?php
function schoolpress_load_textdomain() {
  // get the locale
  $locale = apply_filters( 'plugin_locale',
                            get_locale(), 'schoolpress' );
  $mofile = 'schoolpress-' . $locale . '.mo';

  /*
  Paths to local (plugin) and global (WP) language files.
	 Note: dirname(__FILE__) here changes if this code
  is placed outside the base plugin file.
  */
	 $mofile_local  = dirname( __FILE__ ).'/languages/' . $mofile;
	 $mofile_global = WP_LANG_DIR . '/schoolpress/' . $mofile;

	 // load global first
	 load_textdomain( 'schoolpress', $mofile_global );

	 // load local second
	 load_textdomain( 'schoolpress', $mofile_local );
}
add_action( 'init', 'schoolpress_load_textdomain', 1 );
?>

This version gets the locale via the get_locale() function, applies the plugin_locale filter, and then looks for a .mo file in both the global languages folder (typically /wp-content/languages/) and the languages folder of our plugin.

__( $text, $domain = “default” )

This function expects two parameters: the $text to be translated and the $domain for your plugin or theme. It returns the translated text based on the domain and the language set in wp-config.php.

Here is an example of how you would wrap some strings using the __() function:

<?php
// setting a variable to a string without localization
$title = 'Assignments';

// setting a variable to a string with localization
$title = __( 'Assignments', 'schoolpress' );
?>

_e( $text, $domain = “default” )

This function expects two parameters: the $text to be translated and the $domain for your plugin or theme. It echoes the translated text based on the domain and the language set in wp-config.php.

This function is identical to the __() function except that it echoes the output to the screen instead of returning it. Here is an example of how you would wrap some strings using the _e() function:

<?php
// echoing a var without localization
?>
<h2><?php echo $title; ?></h2>
<?php
// echoing a var with localization
?>
<h2><?php _e( $title, 'schoolpress' ); ?></h2>

In practice, you will use the __() function when setting a variable, and the _e() function when echoing a variable.

_x( $text, $context, $domain = “default” )

This function expects three parameters: the $text to be translated, a $context to use during translation, and the $domain for your plugin or theme. It returns the translated text based on the context, the domain, and the language set in wp-config.php.

The _x() function acts the same as the __() but gives you an extra $context parameter to help the translators figure out how to translate your text. This is required if your code uses the same word or phrase in multiple locations, which might require different translations.

For example, the word title in English can refer both to the title of a book and also to a person’s title, like Mr. or Mrs. In other languages, different words might be used in each context. You can differentiate between each context using the _x() function.

In the following (slightly convoluted) example, we are setting a couple of variables to use on a class creation screen in SchoolPress:

<?php
$class_title_field_label = _x( 'Title', 'class title', 'schoolpress' );
$class_professor_title_field_label = _x( 'Title', 'name prefix', 'schoolpress' );
?>
<h3>Class Description</h3>
<label><?php echo $class_title_field_label; ?></label>
<input type="text" name="title" value="" />

<h3>Professor</h3>
<label><?php echo $class_professor_title_field_label; ?></label>
<input type="text" name="professor_title" value="" />

_ex( $title, $context, $domain = “default” )

The _ex() function works the same as the _x() function but echoes the translated text instead of returning it.

Escaping and Translating at the Same Time

In This Blog, we talked about the importance of escaping strings that are displayed within HTML attributes or in other sensitive areas. When also translating these strings, instead of calling two functions, WordPress offers a few functions to combine two functions into one. These functions work exactly as you would expect them to by first translating and then escaping the text:

• esc_attr__()

• esc_attr_e()

• esc_attr_x()

• esc_html__()

• esc_html_e()

• esc_html_x()

Our File Structure for Localization

Before getting into the specifics of how to generate these files, let’s go over how we typically store these files in our plugins. For our SchoolPress app, we store the localization files in a folder called languages inside the main app plugin. We add all our localization code, including the call to load_plugin_textdomain(), in a file in the includes directory called localization.php.

So our file structure looks something like this:

1. ../plugins/schoolpress/schoolpress.php (includes localization.php)

2. ../plugins/schoolpress/includes/localization.php (loads text domain and other localization functions)

3. ../plugins/schoolpress/languages/schoolpress.pot (list of strings to translate)

4. ../plugins/schoolpress/languages/schoolpress.po (default/English translations)

5. ../plugins/schoolpress/languages/schoolpress.mo (compiled default/English translations)

6. ../plugins/schoolpress/languages/schoolpress-es_ES.po (Spanish/Spain translations)

7. ../plugins/schoolpress/languages/schoolpress-es_ES.mo (compiled Spanish/Spain translations)

When you’re building a larger app with multiple custom plugins and a custom theme, localization is easier to manage if you localize each individual plugin and theme separately instead of trying to build one translation file to work across everything. If your plugins will only be used for this one project, they can probably be built as includes or module .php files in your main app plugin. If you might use the plugins on another project, they need to be localized separately so the localization files can be ported along with the plugin.

Generating a .pot File

We’ll use the xgettext tool, which is installed on most Linux systems,¹ to generate a .pot file for our plugin.

To generate a .pot file for our SchoolPress app, we would open up the command line and cd to the main app plugin directory at wp-content/plugins/schoolpress. Then execute the following command:

xgettext -o languages/schoolpress.pot \
--default-domain=schoolpress \
--language=PHP \
--keyword=_ \
--keyword=__ \
--keyword=_e \
--keyword=_ex \
--keyword=_x \
--keyword=_n \
--sort-by-file \
--copyright-holder="SchoolPress" \
--package-name=schoolpress \
--package-version=1.0 \
--msgid-bugs-address="This email address is being protected from spambots. You need JavaScript enabled to view it." \
--directory=. \
$(find . -name "*.php")

Let’s break this down:

-o languages/schoolpress.pot

Defines where the output file will go.

--default-domain=schoolpress

Defines the text domain as schoolpress.

--language=PHP

Tells xgettext that we are using PHP.

--keyword=…

Sets xgettext up to retrieve any string used within these functions. Be sure to include a similar parameter for any of the other translation functions (like esc_attr__) you might be using.

--sort-by-file

Helps organize the output by file when possible.

--copyright-holder="SchoolPress"

Sets the copyright holder stated in the header of the .pot file. This should be whatever person or organization owns the copyright to the application, plugin, or theme being built.

--package-name=schoolpress

Sets the package name stated in the header of the .pot file. This is typically the same as the domain.

--package-version=1.0

Sets the package version stated in the header of the .pot file. This should be updated with every release version of your app, plugin, or theme.

--msgid-bugs-address="This email address is being protected from spambots. You need JavaScript enabled to view it."

Sets the email stated in the header of the .pot file to use to report any bugs in the .pot file.

--directory=.

Tells xgettext to start scanning from the current directory.

$(find . -name "*.php")

This appears at the end, and is a Linux command to find all .php files under the current directory.

Creating a .po File

Again, the Poedit tool has a nice graphical interface for generating .po files from .pot files and providing a translation for each string. Hacking it yourself is fairly straightforward though: simply copy the .pot file to a .po file (e.g., es_ES.po) in your languages directory and then edit the .po file and enter your translations on each msgstr line of the file.

Creating a .mo File

Once your .po files are updated for your locale, they need to be compiled into .mo files. The msgfmt program for Linux can be used to generate the .mo files using the command msgfmt es_ES.po --output-file es_ES.mo.

Using GlotPress for Your WordPress.org Plugins and Themes

If you are hosting your plugin or theme in the WordPress.org repository, using GlotPress is as easy as properly wrapping your strings for translation and making sure that your text domain matches your plugin or theme’s slug. If you did this properly, a new translation project is generated for you at one of the following locations:

• https://translate.wordpress.org/projects/wp-plugins<your-plugins-slug>/

• https://translate.wordpress.org/projects/wp-themes<your-themes-slug>/

That’s it. If you’ve already bundled existing .po files for your plugin in a /languages/ folder, they should be imported into the GlotPress project as locales with those strings already translated.

Once your plugin or theme is integrated with GlotPress, you no longer need to bundle language files with your project. WordPress looks for language packs based on your locale and automatically downloads them for use. However, note that only locales that are 95% or more translated will be distributed automatically. So make sure you stay on top of the translations to make them complete. Alternatively, you can download .po and .mo files for incomplete translations and bundle them with your plugin per the instructions earlier in this post.

Creating Your Own GlotPress Server

If you host your plugin or theme on your own server, you can still take advantage of the GlotPress technology by setting up your own translation server. The GlotPress team has created a WordPress plugin that you can install and activate on any WordPress site. The GlotPress Plugin will set up an endpoint at /glotpress/ where you can create new translation projects for your own self-hosted plugins and themes.

Once your GlotPress server is set up, you can create a new project for your non-WordPress.org plugin. WordPress won’t download those translations automatically for your users, but you can export the .po and .mo files to include in your plugin files.

Depending on the use case of your web application, translating your app may be essential to its success. When building a custom theme or plugin, it’s good practice to write all of your code with localization in mind!