Translating a Plugin/Theme using Loco Translate

Introduction

When you create a WordPress theme or plugin, it is possible to include translations to other languages. This is particularly helpful for situations when someone uses your theme/plugin and the information is displayed in their language. Otherwise you would have a blog whose content is in Spanish and would have links in English such as “Read More”.

The process of translation is a not complicated but includes some steps along the way which were not very straightforward. This post will show you the basics of translation and will hopefully shed some light along the way in this process.

Declaring Text Domains

When you are working with translations you should specify a text-domain. A text domain should be a unique string that specifies the package of your plugin and/or theme. Try to be a specific as possible and pick a creative name to avoid clashes with other plugins and themes.

Declaring the Text Domain in a Theme

You should specify the text domain in the functions.php file. You can attach to the after_setup_theme action and declare it in a function like this:

function btalegal_theme_setup() {
    load_theme_textdomain( 'btalegal_theme', get_stylesheet_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'btalegal_theme_setup' );

Two things to note here:

1. You do not need to specify the second parameter, but it is good practice to specify the directory inside your theme where the translations will be stored.
2. If you are using a child theme, you must use the load_child_theme_textdomain function instead.

Declaring the Text Domain in a Plugin

To declare the theme-domain in the plugin, you specify it inside the comments header of your plugin’s file. For example:

/*
...
Author URI: http://scorpiotek.com/
Text Domain: bta-legal-temas-de-interes
*/

Specifying Translatable Strings

You must specify which strings are translatable in your plugin/theme. There are two functions that will help you achieve this: __() and _e()

_e()

The e() function will output the string- think as if you were using echo. This function takes two arguments: the first is the string that will be translated, and the second one is the text-domain:

<?php _e( 'Recent news', 'btalegal_theme' ); ?>

__()

The __() function should be used when you do not want to output to string but rather will do something with the returned translated string. In this case, we are assigning the returned value to a variable that will be used later on:

<?php $translated_text = __( 'Recent news', 'btalegal_theme' ); ?>

You must go through the plugins and themes that you author and mark any text you want translated with the aforementioned functions. This is simply telling WordPress to fetch the localised version of the string from a resource file.

Generating the Translation Files with Loco Translate

There are various ways to generate these files but we have found Loco Translate to be very user-friendly. It is also a plugin, which makes it convenient as it makes you feel comfortable working in an environment you are already comfortable with.

Download Loco Translate

Use the Add New Plugin option in your WordPress site to search, install, and activate Loco Translate. Alternatively, head over to the author’s https://localise.biz/about and download, upload, and activate the plugin.

Translating your Plugin / Theme

From the WordPress Admin sidebar, access the Loco Translate section. You will see a list of all plugins and themes installed in your WordPress site. Find the one one you authored and click its name.

Creating a default template

At this stage, your plugin/theme does not have a template, so click on Create Template to have Loco Translate create a template for you:

The next screen will give you information about the template file (ends with the pot extension) that will be created. Click the Create Template button:

You now have a template you can edit.

Adding a Language

Click the New Language link, it will open the options you have for your translation. Select the language you are going to translate to and select System from the location setting:

Click on Start Translating to start translating to your language.

Translating

You should now see various panels. Most of them are self-explanatory but this image should make things easier in case the interface baffles you a bit:

To begin, select the text to be translated in the Source Text field and type it the translation field:

You may have noticed that these strings are the ones that you specified with the __() and _e() functions. When Loco Translate created the default template it went through all of your files and parsed out sections where you used those functions to generate the pot file.

Once you are done with the translations, click the Save button. Your plugin/theme po and mo files will be created:

Now when the WordPress site is switched to Spanish, the plugin will display the translatable strings in the corresponding language.

Note: If you make any modification to your theme’s file by adding/removing strings using the __() and _e() methods, you must hit that sync button so that the new strings will show up on your table: