Make Your Plugin or Theme Translatable with I18n

WordPress allows you to translate your sites, themes, plugins, and everything into any language whatsoever. It’s part of what makes it such a global and accessible CMS.

To be able to translate WordPress sites, you as a developer need to write high-quality code to make your themes and plugins translatable.

Today, I am going to talk about how to write WordPress code to help make it translatable via i18n and l10n. Not only this, but I have also prepared a boilerplate which you can use to auto generate .pot files for translation both via WP-POT CLI + NPM Scripts or Gulp. But first, let’s talk a little about translation.

I18n in WordPress

Internationalization is the process where you write code that is ready to translate. It’s abbreviated as i18n, because there are 18 letters between “i” and “n”.

This is how you use it.

#1 Add Text Domain: First of all, you need to add the text domain.

#2 Load Language Files: Load the language file using one of the WordPress functions: load_plugin_textdomain(), load_theme_textdomain(), or load_child_theme_textdomain()

#3 Generate a Pot File: We will discuss this in the article below.

WordPress l10n in a nutshell

l10n is similar. It’s abbreviated as l10n because there are 10 letters between “l” and “n”. This is done by translators.

#1 POT file: Use pot (Portable Objects Template) files for string translation.

#2 Translate POT Files: On translation, translators translate the msgstr string in the POT file and save this as a PO file using the proper locale.

#3 Generate MO files: Then MO Files are generated from PO Files.

WordPress and Gettext

WordPress uses the gettext libraries and tools for i18n. Gettext is an old and respectable piece of software, widely used in the open-source world.

Here is how it works in a few sentences:

Developers wrap translatable strings in special gettext functions.
Special tools parse the source code files and extract the translatable strings into POT (Portable Objects Template) files.
In the WordPress world, POT files are often fed to GlotPress, which is a collaboration tool for translators.
Translators translate and the result is a PO file (POT file, but with translations inside).
PO files are compiled to binary MO files, which give faster access to the strings at run-time.

I18n Code for WordPress

To write translatable i18n code you can refer this Codex page. Though, I am going to summarize it a little.

Text Domain

First of all, you need to define the tex-domain for your WordPress theme or plugin and then define it in the theme or plugin header. E.g.

<?php
/**
 * Plugin Name: WPAutoPot Dummy Plugin
 * Text Domain: WPAutoPot
 * Author: AhmadAwais
 */

As you can see, I have defined WPAutoPot as my text domain for this dummy plugin.

Translatable Strings

There are a number of ways through which you can translate strings. Most of the times you can use the __() function with first parameter as your string and second as your text domain. For example:

<?php
// Translatable Strings.
$first = __( 'First String with __()', 'WPAutoPot' );

If your string needs to be echo’d you can simply use the _e() function.

<?php
// Make sure the function is unique.
if ( ! function_exists( 'wpautopot_function' ) ) {
	/**
	 * Random function that outputs translated string.
	 *
	 * @since 1.0.0
	 */
	function wpautopot_function() {
		_e( 'Second String with __e()', 'WPAutoPot' );
	} // End fucntion wpautopot_function().
} // End if().

There are several other companion functions, which you can find in this infographic by Carrie Dills.

By Carrie Dils — you can also watch her course on WordPress and Internationalization.

Auto Generating .POT Translation Files

Now let’s get into how you can auto generate the .pot translation files for you themes/plugins that translators can use to translate.

To make it easier for you to follow, I have built a boilerplate package called WPAutoPot to auto generate pot files via NPM Scripts or Gulp. Let’s get cracking.

WPAutoPot — Getting Set up

Make sure you have node installed. If not download and install node.

STEP #1: Install NodeJS & NPM

After installing NodeJS you can verify the install of both NodeJS and Node Package Manager by typing the following commands. This step needs to be followed only once i.e. if you don’t have NodeJS installed. No need to repeat it ever again.

node -v
# v7.10.0

npm -v
# 4.2.0

Step #2. Download `package.json`

Download the package.json file inside the root folder of your WordPress plugin or WordPress theme If you have cURL installed then you can run the following command to download it in one go (just make sure you open the root folder of your WordPress plugin or WordPress theme and download the package.json file in it).

curl -L 'https://git.io/WPAutoPot' -o package.json

STEP #3: Configure NPM Scripts and Install WP-POT-CLI

Now, if you want to use NPM Scripts then you need to do the following:

Install the WP POT CLI — just run npm install --global wp-pot-cli in your terminal.
Configure the NPM script called pot — If you open the package.json file you can find it under scripts.

"scripts": {
    "pot": "wp-pot --src '**/*.php' --dest-file 'languages/WPAutoPot.pot' --package 'WPAutoPot' --domain 'WPAutoPot' --last-translator 'Ahmad Awais <[email protected]>' --team 'Team <[email protected]>' --bug-report 'https://your-domain.com/contact'"
}

In the pot script, you need to change

–src ‘**/*.php’ (Source files)
–dest-file ‘languages/WPAutoPot.pot’ (Destination file)
–package ‘WPAutoPot’ (Package name)
–domain ‘WPAutoPot’ (Domain to retrieve the translated text)
–last-translator ‘Ahmad Awais [email protected]‘ (Name and email address of the last translator E.g. John Doe [email protected])
–team ‘Team [email protected]‘ (Name and email address of the translation team E.g. Team [email protected])
–bug-report ‘https://your-domain.com/contact‘ (Header with URL for reporting translation bugs)

NOTE: That currently this little WP plugin has following file structure

    ├── languages
    |  └── WPAutoPot.pot
    ├── package.json
    ├── gulpfile.js
    └── plugin.php

STEP #4: Run NPM Scripts

All that’s left now is for you to run the NPM script in the root folder of your WP project — where you downloaded the package.json file.

NOTE: Before you run, make sure there is a languages directory. Otherwise running the script will display an error.

# Compile POT file.
npm run pot

STEP #5: Compile via Gulp — Installing Node Dependencies

If you want to use Gulp to compile the pot files, then use the following steps otherwise jump to the last step.

We are in the root folder of our WordPress plugin or WordPress theme at the moment, let’s install the Node Dependencies. In the terminal run this command and wait for it to download all the NodeJS dependencies. It’s a one time process and can take about a minute depending on the internet speed of your connection.

# For MAC OS X run the following command with super user
sudo npm install

# For Linux run the following command
npm install

STEP #6: Download, Configure & Run Gulp

First of all, download the gulpfile.js file in the root folder.

curl -L 'https://git.io/WPAutoPotGulp' -o gulpfile.js

Now that you have gulpfile.js downloaded in the root, you can open it up and configure the info at the top where it says //— START Editing Project Variables. —//. till it says //— STOP Editing Project Variables. —//. (these lines)These are the similar project variables described in the Step #3.

All you have to do now is run gulp in your command line terminal and your translated POT file will get generated.

# Run gulp to compile .pot file.
gulp

STEP #7: Share

There are no more steps. Just share it with your friends. Or Click to Tweet about it.

Your Turn

Now it’s your turn to auto generate the pot files for i18n and l10n. Let me know your thoughts on this. If you have any issues, make sure you report them on GitHub. Pull Requests are more than welcomed.