Baptiste Dufour

Translating a Custom WordPress Theme

Translate a WordPress theme

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.

  1. Creating a Text Domain for Your Theme
  2. Encapsulating Text Strings
  3. Generating a Translation Template File
  4. Creating Files to Translate Your WordPress Theme into Any Language
  5. Updating Your Translation Template
  6. How It Works with WordPress Multilingual Plugins

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:

<?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');
/*
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:

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

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.