Even though we used many WordPress Plugin Internationalization functions in the tutorial so far, we didn’t explain what they really do. In this chapter, we explore WordPress Plugin Internationalization and Localization techniques.

WordPress Plugin Handbook chapter - WordPress Plugin Internationalization explains the topic well, but for new developers it may be difficult to comprehend all that in one go and, more often than not, internationalization moves to TODO list.

Rather than the later refactoring, it is easy to internationalize the plugin from the start . In this chapter, we explain the essential concepts to kick start internationalization.

Internationalization is also known by its short form i18n (means there are 18 characters between i and n in internationalization) and similarly, Localization is abbreviated as l10n.

10.1. Internationalization

Text Domain

WordPress requires some mechanism to segregate the translations of your plugin when there are multiple plugins active. It uses Text Domain to distinguish between all loaded translations. Text Domain is unique string set in the header comment of the plugin main file and in the translation functions.

share-on-social/share-on-social.php

<?php

/**
 * Plugin Name: Share on Social 
 * Plugin URI: https://wordpress.org/plugins/share-on-social/ 
 * Description: Adds share locker to hide the content until user shares the blog on social network. Share is posted to user's wall. 
 * Version: 1.0.0 
 * Author: Maithilish 
 * Text Domain: sos-domain 
 * Author URI: http://www.codetab.org/about 
 * License: GPLv2
 */

For Share on Social Plugin, we use sos-domain as the text domain. But, it is recommended to use slug of the plugin as the text domain. If your plugin main file is my-plugin.php or it is contained in a folder called my-plugin the text domain should be my-plugin. The text domain must use dashes and not underscores.

Next we have to load the text domain as soon as plugin is loaded and in Share on Social, we do that in setup_sos_plugin() function.

share-on-social/share-on-social.php

function setup_sos_plugin () {
   
    load_plugin_textdomain( 'sos-domain', false, 'share-on-social/langs' );

The third argument to load_plugin_textdomain() is the path to dir that contains plugins language files. We will cover the language files later in Localization.

WordPress Internationalization Functions

For WordPress Plugin Internationalization, the plugin strings are enclosed in functions that returns translated strings instead of the original. Share on Social Plugin uses two WordPress Internationalization functions __( ) and _x( ).

The basic string translation function __() returns a translated string for the text domain.

share-on-social/admin/class-sos.php

    function get_table () {
        ....        
        $locker_id_label = __( 'Locker ID', 'sos-domain' );
        $shareon_label = __( 'Share on', 'sos-domain' );
        $share_target_label = __( 'Share <a href="https://codex.wordpress.org/Function_Reference/_x" target="_blank">Which URL]', 'sos-domain' );
        $page_label = __( 'Page', 'sos-domain' );
        $parent_label = __( 'Parent Page', 'sos-domain' );
        $site_label = __( 'Site', 'sos-domain' );
        $display_text_label = __( 'Display Text', 'sos-domain' );

For example, __( ‘Page’, ‘sos-domain’ ) returns string Página when Site language is set to Spanish provided language file for Spanish exists in share-on-social/langs directory. For default language or if, language file is not available then default string Page is returned.

The next function [_x( ) same as the __( ), but provides additional information to translators to assist them in proper translation.

share-on-social/admin/class-sos.php

public function create_post_type () {
   register_post_type( $this->post_type,
       array(
          'labels' => array(
               'name' => _x( 'Sos Lockers','post type general name', 'sos-domain' ),
               'singular_name' => _x( 'Sos Locker','post type singular name', 'sos-domain' ),
               'menu_name' => _x( 'Share on Social','admin menu', 'sos-domain' ),
     ....

For example, _x( ‘Buffalo’,‘sos-domain’ ) make it difficult know the context of Buffalo; a city or an animal, whereas _x( ‘Buffalo’,‘city name’, ‘sos-domain’ ) tells translators that it is a city name.

Refer How to Internationalize Your Plugin for other i18n functions.

In the next section, we explain the steps to prepare the language files for the plugin.