During The Prime Hacking Hours

Summary

This pluging provides several functions and aims to reduce the amount of typing you need while you, a theme and/or plugin writer, inserts localization code using `_e()' and `__()' functions.

These functions could bother you while you write your themes or plugins since you need to add additional the argument `textdomain’ to all of them, one by one.

Once you bring the functions the plugin provides into your toolbox, they will really help you.

FYI, while this plugin is provided under the GPL license, you are free to use it not as a plugin but just a php file; bundle the l10n-helper.php file with your theme/plugin file set and include it by `require_once' or other similar function as you prefer.

Installation

• Download the plugin zip file.
• Expand into `wp-content/plugins/’ directory.
• Activate it in the admin panel.

Usage Examples

In a theme file…

<?php __theme('my-theme'); ?>

<?php get_header(); ?>
 <div id="content" class="narrowcolumn">
 <?php if (have_posts()) : ?>
  <?php while (have_posts()) : the_post(); ?>
   <div class="post" id="post-<?php the_ID(); ?>">
   <h2><a href="<?php the_permalink() ?>" rel="bookmark" 
    title="<?php __pf('Permanent Link to %s', get_the_title(); ?>">
...

<?php __r(); ?>

In a plugin file…

<?php
...
add_action('plugins_loaded', 'myplugin_init');
add_action('admin_footer', 'myplugin_adminfooter');

function myplugin_init()
{
    __plugin('myplugin', dirname(__FILE__));
    __r();
}

function myplugin_adminfooter()
{
    __s('myplugin');

    echo '<p>';
    __e('Did you know? ');
    echo myplugin_get_random_tips();
    echo '</p>';

    __r();
}
...

Functions

__s($textdomain)

Begin a text domain block.
$textdomain: a text domain string used by translation functions within the following block.

It begins a text domain block.
A `Block’ in this context is a range between __s() and __r(). The translation functions (__e(), ___(), etc.) in a block will use the text domain specified by __s().
Blocks can be nested. As calling __r() it recalls the previous text domain and sets as the current one.
Do not forget to call __r() for a __s() to end a text domain block.

__r()

End the current text domain block.

It ends the current text domain block. After calling __r(), the previous text domain context is recalled and set as the current.
A text domain block begins by __s(), __plugin() or __theme(). (The latters call __s() implicitly.)
Once you begins a text domain block with those functions, do not forget to call __r().

__plugin($domain, $mo_dir)

Load a translation file for a plugin and begin a text domain block.
$domain: a text domain string used by translation functions
$mo_dir: path to the directory where your plugin and translation files are stored.

Load a translation file(*.mo) for the current locale for your plugin, then start a text domain block.(The function calls __s() inside.)
The translation files must be stored in the same directory as your plugin and the translation file name must be formatted as TEXTDOMAIN-LL_CC.mo, where TEXTDOMAIN is the text domain name for your plugin, and LL_CC is the name of their locale. (e.g. my_sample_PlugIn-fr_FR.mo, my_sample_PlugIn-it.mo)
Since this function calls __s() implicitly, do not forget to call __r() at the end of a text domain block.

__theme($domain)

Load a translation file for a theme and begin a text domain block.
$domain: a text domain string used by translation functions.

Load a translation file(*.mo) for the current locale for the current theme, then starts a text domain block.(The function calls __s() inside.)
The translation files must be stored in the same directory as your plugin and the translation file name must be formatted as LL_CC.mo, where LL_CC is the name of their locale. (e.g. fr_FR.mo, it.mo)
Since this function calls __s() implicitly, do not forget to call __r() at the end of a text domain block.

___($text)

Get a translated string. $text: A text to be translated.
return: A translated string.

Translates text for the current text domain/current locale using a translation file(*.mo).
If no translation is found, it returns the text without modification.

__e($text)

Echo a translated string.
$text: A text to be translated.

Translates text for the current text domain/current locale using a translation file(*.mo), then prints it on the screen.
If no translation is found, it echoes the text passed.

__pf($fmt, $…)

Echo a translated string with formatting.
$fmt: A formatting text to be translated.
$…: Variable-length arguments used with formatting.

It translates the text like ___() then formats and prints the fetched string using the PHP general function printf().
(sample usage: __pf('Hello, %1$s %2$s', $first_name, $last_name); )
For the format specification, please refer to the sprintf() function manual.
If no translation is found, it passes the text to printf() directly.

__f($fmt, $arg1, $arg2, …)

Get a translated string with formatting.
$fmt: A formatting text to be translated.
$…: Variable-length arguments used with formatting.
return: A translated and formatted string.

It translates the text like ___() then format the fetched string using the PHP general function sprintf().
(sample usage: $text = __f('Hello, %1$s %2$s', $first_name, $last_name); )
For the format specification, please refer to the sprintf() function manual.
If no translation is found,, it passes the text to sprintf() directly.

l10n_helper__check_on_shutdown()

Validation for debug purpose

At the end of the blog page generation sequence, it checks the calling pair of __s()/__plugin()/__theme() and __r().
If it detects more or less calling of __r(), it logs information only if in the debug mode.
`Debug Mode’ in this context is in the condition of $debug is evaluated as true.
To set, you can insert the line $debug = true; in the top ofwp-config.php.
The log file will be placed in the same directory of wp-config.php, named l10n-helper.log.

Usage Patterns

Themes

In theme files, the most simple and robust way is to use __theme() at the top of each .php file and __r() at the bottom of each ones.

<?php __theme('my-theme'); ?>
...
<?php __r(); ?>

To be awere of performance issues – __theme() performs most work the first time it is called in a blog page generation sequence. Later calls only do the same work as __s() but takes a little more cpu time. Therefore, the most efficient use is to use __theme() only in header.php and __s() in other files.

(your_theme/header.php)

<?php __theme('my-theme'); ?>
... call __e()/___()/__pf()/__f() ...
<?php __r(); ?>

(your_theme/*.php)

<?php __s('my-theme'); ?>
...
<?php __r(); ?>

Plugins

Like themes, you can call a set of __plugin()/__r() wherever it needed, or call __plugin()/__r() once and then in following situation call a pair of __s()/__r(). Exactly the latter is more time effective.

[pattern a] call __plugin() evety time.

<?php 
function myplugin_do_something()
{
  ...
  __plugin('my_plugin_domain');
  ... call __e()/___()/__pf()/__f() ...
  if (some_condition) {
    __r();
    return;
  }
  ...
  __r();
}

[pattern b-1] call __plugin() once while the plugin initialization

<?php 
add_action('plugins_loaded', 'myplugin_init');
function myplugin_init()
{
  __plugin('my_plugin_domain');
  __r(); // required; `__plugin()' calls `__s()' inside
}

function myplugin_do_something()
{
  ...
  __s('my_plugin_domain');
  ...
  __r();
}

[pattern b-2] call __plugin() once at the first time requirement.

(May more efficient than b-1 because plugins may not work every time it is loaded. E.g. plugins made only for blog pages will be loaded for admin pages but won’t be called after that.)

<?php 

define('MY_PLUGIN_DOMAIN', 'my_plugin_domain');

function myplugin_do_something()
{
  ...
  global $l10n;
  if (!isset($l10n[MY_PLUGIN_DOMAIN])) {
    __plugin(MY_PLUGIN_DOMAIN);
  } else {
    __s(MY_PLUGIN_DOMAIN);
  }
  ...
  __r();
}

P.S. Nowadays servers are faster, and the cpu time penalties mentioned above are much smaller. So you can take either options as the results will not be very different.