How to prepare a WordPress theme for localization

There's more to localizing a WordPress theme than simply downloading translation files from Loco, or from any other platform.

WordPress's own instructions are good and won't be repeated here. However, here's a quick summary of the preparation steps.

1. Choose a text domain - be sure to add the appropriate headers to your styles.css file.
2. Prepare all translatable strings - nothing is translatable unless it's passed through a WordPress translation function.
3. Prepare the file loader - your theme's translations are not loaded automatically, you have to tell WordPress what to do.
4. Generate a POT file - this is the master template that lists all translatable strings in your source code.

Generating the translations

With the above four steps complete we are ready to translate the theme. The tools you use for this are up to you, but the goal is the same - to generate a Gettext MO file for every one of your target languages. It is these MO files that WordPress will load in order to display your translations.

Regardless of your software choice the process is much the same. From your template file (mytheme.pot) you will create a PO file for each language. e.g. fr_FR.po. A translator will edit this file either using a text editor or a PO file editor like Loco. Once complete this file is compiled into the final MO file and saved to the correct location within your theme.

See WordPress's introduction to Gettext.

Using Gettext tools to generate files

You can generate all the above file types using Gettext command line tools.

• Extract POT - xgettext
• POT to PO file - msginit
• Compile PO to MO - msgfmt
• Update PO from new POT - msgmerge

Using Loco to generate files

The Loco WordPress plugin is the best way to use Loco for translating WordPress themes. As well as providing a PO file editor, Loco can extract strings from your source code into a POT file and compile the final MO files.

Gettext is not a requirement for using the Loco plugin, it can generate MO files without any special software requirements.

Common mistakes

You've got as far as generating valid MO files, but that doesn't necessarily mean everything has gone swimmingly. Here are a few gotchas to look out for when localizing a WordPress theme.

Bad translation calls

When preparing translatable strings, pass only string literals as translatable text. Don't pass variables, constants or any other kinds of expressions to the translate functions. Although this will work at runtime most extraction software won't be able to pull out the string.

Example of non-literal string parameter:

$dynamic_text = "Do not do this!";
echo __( $dynamic_text, 'badtheme' );

Be sure to pass the text domain in every call and make sure you're passing it as the right parameter. WordPress won't complain if this is missing, it will just look in its own "default" text domain and find nothing. It'll be doing exactly what you asked.

Examples of text that won't be found in the "mytheme" domain:

echo __( "You won't see this" );
echo _x( "You won't see this", 'mytheme', 'A contextual message with wrong parameter order' );

Not all software detects the text domain during string extraction, but Loco does. If you're extracting strings with Loco, be sure to specify the text domain literally. As with string expressions above, Loco won't be able to extract dynamic text domain parameters.

Bad text domain loader

If you don't tell WordPress where you're keeping your translation files it will look in the root folder of your theme. So if you're placing translations in a subdirectory, make sure your load call passes the full path as follows:

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

Bad file paths

WordPress is strict about where you've placed your MO files. Make sure they're named correctly and are in the right locations. For problems loading translation files, see our MO file loading troubleshooting guide.

Good practices

The following suggestions aren't required by WordPress, but we recommend you follow them to help other people (and other software) understand how your theme is set up.

Conventional file names

Your theme's POT (template) file should make itself known. For example default.po is a bad name. my-domain.pot is much better. WordPress doesn't need this file, but it shows at a glance which file is the template and what your text domain is called.

PO files should also follow the same naming conventions as the MO files that WordPress loads. Always keep the corresponding PO and MO files together, differing only by their file extension.

Declare your text domain

It's not required by WordPress, but it's good practice to declare your choice of text domain, especially if it's not the same as the name of your theme. If your theme is called "foo" but your text domain is "bar" add the following lines to the header tags in style.css

/*
 Theme Name:  foo
 Text Domain: bar
 Domain Path: /languages
*/