Internationalizing or Localizing Your Plugin

WordPress users exist across the United States, Russia, Japan, Germany, and all points in between. Therefore, the next person to download and use your plugin may not speak the same language you do. So if you wrote and distributed your plugin in English, it may be useless to the next person to download it if he only speaks German. However, the WordPress software has internationalization built into it, which means it can be localized, or translated, into different languages.

Using GetText Functions for Text Strings

WordPress provides you with two main localization functions: __ and _e. These functions use the GetText translation utility installed on your Web server. These two functions let you wrap plain text into strings of text to be translated. You need to account for two types of text strings in your plugin file:

• HTML: Example: <h1>Plugin Name</h1>

  To wrap HTML text strings within the GetText function call, you would wrap it using the _e function like this:

  <h1><?php _e('Plugin Name', 'plugin-name'), ?></h1>

  This tells PHP to echo (_e) or display the string of text on yoaur Web browser screen, but adds the benefit of using the GetText function, which allows for that string of text to be translated.

• PHP: Example: <?php comments_number('No Responses', ‘One Response’, ‘% Responses’ );?>

  To wrap PHP text strings with the GetText function, you would wrap it using the __ function, like this:

  <?php comments_number(__('No Responses',plugin-name),('One Response',
      'plugin-name'),( '% Responses', 'plugin-name') );?>

  Unlike the echo function(_e), the __ function is used when you need to add a string of text to an existing function call (in this case, comments_number()).

The second argument within the GetText string for the PHP text string example is plugin-name. This defines the domain of the text and tells GetText to return the translations only from the dictionary supplied with that domain name. This is the plugin text domain and most plugin authors use the name of their plugin (separated by hyphens) as the definer here. Use the text domain in your GetText functions toensure that GetText pulls the dictionary you supply instead of attempting to pull the text from the core WordPress language files, because some of the text you provide in your plugin is unique and, most likely, won't exist within the WordPress core language files.

In a plugin file, you define the text domain like this:

$my_translator_domain = PLUGIN-NAME;
$my_translator_is_setup = 0;
function fabfunc_setup(){
  global $my_translator_domain, $my_translator_is_setup;
  if($my_translator_is_setup) {
    return;
  }
  load_plugin_textdomain($my_translator_domain,
       PLUGINDIR.'/'.dirname(plugin_basename(__FILE__)),
       dirname(plugin_basename(__FILE__)));
}

These lines of code simply tell WordPress where your plugin file is located (the text domain), which, in turn, informs WordPress where your .pot, or translation file, is for your specific plugin.

Creating the POT file

After you create your plugin and include all text strings within the GetText functions of __ and _e, you need to create a .pot (portable object template) file, which contains translations for all the strings of text that you wrapped in the GetText functions. Typically, you create the .pot file in your own language, in a special format, thereby, allowing other translators to create their own .po (portable object), or an .mo (machine object) file in their language, using yours as the guide to translate by.

The .pot file is the original translation file and the .po file is a text file that includes your original text (from the .pot) along with their translation; or they can use an .mo file, which is basically the same as a .po file. However, while .po files are written in plain text meant to be human readable, .mo files are complied to make it easy for computers to read. Most Web servers will use .mo files to provide translations for .pot files.

The .pot file begins with a header section, which contains required information about what your translation is for. The .pot header section looks like this:

# LANGUAGE (LOCALE) translation for WordPress.
# Copyright (C) 20114 WordPress contributors.
# This file is distributed under the same license as the WordPress package.
# FIRST AUTHOR <[email protected]>, 2011.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: WordPress VERSION
"
"Report-Msgid-Bugs-To: 
"
"POT-Creation-Date: 2011-01-01 12:00-0600
"
"PO-Revision-Date: 2011-01-01 12:00-0600
"
"Last-Translator: YOUR FULL NAME <[email protected]>
"
"Language-Team: LANGUAGE <[email protected]>
"
"MIME-Version: 1.0
"
"Content-Type: text/plain; charset=CHARSET
"
"Content-Transfer-Encoding: 8bit
"

All the capitalized, italicized information in this code example are placeholders. Replace these terms with your own information.

The format of the .pot file is specific and needs to contain the following information:

• File Name: The name of the file in which the text string exists. For example, if the plugin file is wordpress-twitter-connect.php, you need to include that filename in this section.
• Line of code: The exact line number of the text string in question.
• msgid: The source of the message, or the exact string of text that you included within one of the GetText functions, either __ or _e.
• msgstr: A blank string where the translation (in the subsequent .pot files) is inserted.

For your default .pot file, to format a text string using the GetText function (<h1><?php _e(‘WordPress Twitter Connect’); ?></h1>), which exists on line two (2) in the wordpress-twitter-connect.php plugin file, you include three lines in the .pot file that look like this:

#: wordpress-twitter-connect.php:2
msgid: "WordPress Twitter Connect"
msgstr: ""

You need to go through all the text strings in your plugin file that you wrapped in the GetText functions and define them in the .pot file in the format provided. Now, if anyone wants to create a .po file for your plugin in a different language, he or she simply copies their language translation of your .pot file between the quotation marks for the msgstr: section for each text string included in the original .pot file.

All .pot and .po (or .mo) files need to be included in your plugin folder in order for the translations to be delivered to your Web site. Figure 6-3 shows the directory structure of the popular WordPress All In One SEO Pack plugin, you can see the original .pot file, along with the translated .mo files listed within the /wp-content/plugins/all-in-one-seo-pack/ plugin folder.

You, or other translators, can create unlimited .mo files for several different languages. Make sure that you name the language file according to the standardized naming conventions for the different languages. For example, the French .mo file for the wordpress-twitter-connect.php plugin is wordpress-twitter-connect-fr_FR.mo. The naming convention for the languages is language_COUNTRY.mo.

Figure 6-3: All In One SEO Pack plugin files with both .pot and .mo translation files.