Translating a Custom WordPress Theme

August 27, 2024

Did you create your own WordPress theme and now want to translate it? You’re in the right place. In this article, I won’t be covering how to translate your pages and posts—there are translation plugins like Polylang or WPML for that, which don’t require much development skill. Instead, I’ll show you how to make the text strings in your theme’s source code translatable—this process is called internationalization. By doing this, your theme will be compatible with the plugins I just mentioned.

Creating a Text Domain for Your Theme

The first step in internationalizing (translating) your custom theme is to declare a text domain. A text domain acts as an identifier that allows WordPress to locate the strings that need translation. Don’t worry—it will all make sense soon:

• First, go to your functions.php file. Using the load_theme_textdomain function, you’ll register your text domain. The first parameter will be the name—choose something descriptive. The second parameter is the path to the directory where your translations will be stored; by convention, name this directory languages. Make sure to create this directory manually as well. Finally, attach the function to the after_setup_theme hook.

<?php
function my_theme_after_setup_theme(){
    load_theme_textdomain('my_theme',get_template_directory()."/languages");
}

add_action('after_setup_theme', 'my_theme_after_setup_theme');

• Next, you’ll also need to include your textdomain in the header of the style.css file, along with the path to the translations directory.

/*
Theme Name: My theme
Text Domain: my_theme
Domain Path: /languages
*/

Encapsulating Text Strings

To translate the text strings in your WordPress theme, encapsulate them using WordPress’s native internationalization functions. This prevents the strings from being hard-coded directly into your template files. Personally, I stick to the simplest of these functions: _(). However, there are more advanced options available that can handle things like plurals if needed.

In the code below, I’ve encapsulated the text strings for my 404.php template file. This is a good example because your textual content is often directly written into this template. To fully translate your WordPress theme, you’ll need to perform this operation across all your .php files that contain text strings.

<?php get_header(); ?>
<main>
    <h1><?php echo __("Erreur 404","my_theme"); ?></h1>
    <p><?php echo __("Vérifiez que vous n'avez pas fait d'erreur dans l'URL.","my_theme"); ?></p>
</main>
<?php get_footer(); ?>

Generating a Translation Template File

From here, everything will take place in the WordPress back office:

1. Download the Loco Translate plugin from the WordPress plugin directory.
2. Go to the Themes tab within the plugin. Your theme and its textdomain should appear.
3. Click on your theme, then select Create a template. This will generate a .pot translation template file in your languages folder.

This .pot file contains all the text strings you’ve encapsulated using the internationalization functions.

Creating Files to Translate Your WordPress Theme into Any Language

Now you can click the New Language button:

1. Choose the language you want.
2. For the location, I recommend selecting the Author option. This will save your translation files in your languages directory, making your theme easier to distribute for other WordPress installations.
3. Click Start Translating.
4. The new language should now appear in the interface, and you can click Edit. From there, you’ll have a graphical interface to translate all the strings individually.

Once the translation is complete, two files (.po and .mo) will be created in your languages directory, containing the translated strings. You won’t need to edit these manually.

Updating Your Translation Template

As you continue to update your WordPress theme files over time, you’ll need to translate any new strings:

• Remember to encapsulate your new strings using the internationalization functions.
• To update the .pot translation template, go to the Loco Translate plugin and click on your theme.
• Click on Edit Template, then select Sync.

This will retrieve your new strings, allowing you to update each translated language:

• Click on the language you want to update.
• Click Sync.
• You can then translate the new strings from the interface.

This will update the .mo and .po files for each language.

How It Works with WordPress Multilingual Plugins

The benefit of translating your WordPress theme is that it will be compatible with multilingual site plugins like WPML or Polylang. This way, the text strings in your template files will display in the correct language as you switch between languages on your site.