In this article by Yannick Lefebvre, the author of WordPress Plugin Development Cookbook, we will learn about plugin localization through the following topics:

• Changing the WordPress language configuration
• Adapting default user settings for translation
• Making admin page code ready for translation
• Modifying shortcode output for translation
• Translating text strings using Poedit
• Loading a language file in the plugin initialization

Introduction

WordPress is a worldwide phenomenon, with users embracing the platform all around the globe. To create a more specific experience for users in different locales, WordPress offers the ability to translate all of its user and visitor-facing content, resulting in numerous localizations becoming available for download online. Like most other functionalities in the platform, internationalization is also available to plugin developers through a set of easy-to-use functions. The main difference being that plugin translations are typically included with the extension, instead of being downloaded separately as is the case with WordPress.

To prepare their plugin to be localized, developers must use special internationalization functions when dealing with text elements. Once this structure is in place, any user can create localizations by themselves for languages that they know and submit them back to the plugin author for inclusion in a future update to the extension.

This article explains how to prepare a plugin to be translated and shows how to use the Poedit tool to create a new language file for a simple plugin.

Changing the WordPress language configuration

The first step to translating a plugin is to configure WordPress to a different language setting other than English. This will automatically trigger mechanisms in the platform to look for alternate language content for any internationalized string.

In this recipe we will set the site to French.

Getting ready

You should have access to a WordPress development environment.

How to do it…

1. Navigate to the root of your WordPress installation.
2. Open the file called wp-config.php in a code editor.
3. Change the line that declares the site language from define(‘WPLANG’, ”); to define(‘WPLANG’, ‘fr_FR’);.
4. Save and close the configuration file.

How it works…

Whenever WordPress renders a page for visitors or site administrators, it executes the contents of the wp-config.php file, which declares a number of site-wide constants. One of these constants is the site language. By default, this constant has no value, indicating that WordPress should display all content in U.S. English. If defined, the system tries to find a translation file under the wp-content/languages or wp-includes/languages directories of the site to locate translation strings for the target language. In this case, it will try to find a file called fr_FR.mo. While it will not actually find this file in a default installation, setting this configuration option will facilitate the creation and testing of a plugin translation file in later recipes.

To learn more about translation files and find out where to download them from, visit the WordPress Codex available at http://codex.wordpress.org/WordPress_in_ Your_Language.

Adapting default user settings for translation

As mentioned in the introduction, plugin code needs to be specifically written to allow text items to be translated. This work starts in the plugin’s activation routine, where default plugin option values are set, to find alternate values when a language other than English is specified in the site’s configuration file.

This recipe shows how to assign a translated string to a plugin’s default options array on initialization.

Getting ready

You should have already followed the Changing the WordPress language configuration recipe to have a specified translation language for the site.

How to do it…

1. Navigate to the WordPress plugin directory of your development installation.
2. Create a new directory called hello-world.
3. Navigate to the directory and create a text file called hello-world.php.
4. Open the new file in a code editor and add an appropriate header at the top of the plugin file, naming the plugin Hello World.
5. Add the following line of code before the plugin’s closing ?> PHP command to register a function to be called when the plugin is activated:

code 1

6. Insert the following block of code to provide an implementation for the hw_set_default_options_array function:

code 2

7. Save and close the plugin file.
8. Navigate to the Plugins management page and activate the Hello World plugin.
9. Using phpMyAdmin or the NetBeans IDE, find the options table entry where the option_name field has a value of hw_options to see the newly-created option.

How it works…

The __ function (that’s two underscores) is a WordPress utility function that tries to find a translation for the text that it receives in its first argument, within the text domain specified in the second argument. A text domain is essentially a subsection of the global translation table that is managed by WordPress. In this example, the text to be translated is the string Hello World, for which the system tries to find a translation in the hw_hello_world domain. Since this domain is not available at this time, the function returns the original string that it received as its first parameter. The plugin code assigns the value it receives to the default configuration array.

It should be noted that the __ function is actually an alias for the translate function. While both functions have the same functionality, using __ makes the code shorter when it contains a lot of text elements to be translated.

While it may be tempting for developers to use a variable or constant in the first parameter of the __ function if they need to display the same text multiple times, this should not be done as it will cause problems with the translation lookup mechanism.

See also

Changing the WordPress language configuration recipe