Paulund
2014-08-08 #wordpress

Change Language Locale From WordPress Plugin

WordPress has the ability to be fully translated, this can be done in both themes and plugins.

Translation Files

To get WordPress to translate all of the text it uses the GNU gettext system, which wraps all the text on the page in a lookup function call. This function will use the language translation file to lookup non-english words and display them in the required language. The files needed for gettext to translate the text are:

  • POT (Portable Object Template) Translation Files
  • PO (Portable Object) Translation Files
  • MO (Machine Object) Translation Files

POT Translation Files

POT Files are the main files that will be used to process the translation files when you use the __() function and the _e() function. POT Files form the basics of all the translation taken place on your Wordpress site.

PO Translation Files

Any translation that takes place will be stored in the PO file, with the english language and translated words. This is so they are cached for future translations.

MO Translation Files

The MO file will take the PO file and optimize it into a binary file (MO file). Compiling the translations into code makes it quicker to in retrieving translations in the future.

Translation Text In A Theme

There are two functions that Wordpress uses to translate words the __() function and the _e() function. The __() function is that takes an argument as text and will return the translated version.


__('Text To Translate');

Wordpress will attempt to translate this text and if it can it will return the text in the required language if it can't translate then it will just return Text To Translate. The _e() function is exactly the same as above but instead of just returning the text it will echo it to the screen. This is the function you should use inside your theme so Wordpress can echo the translated text on the screen.


_e('Text To Translate');

The way WordPress decides what language to display the text it uses a constant variable defined in the wp-config.php file, with the language code you want to display on your site. This gives admin users access to select what language they want to display the site in.


define ('WPLANG', '');

Changing Locale In A Plugin

But what do you do if you want to give the user the ability to switch what language they want to show, as the constant is set in the wp-config.php you can not redeclare this constant variable in a plugin. Therefore you need to change the locale at a different time in the application. WordPress will decide what the locale is using the function get_locale() in wp-includes/l10n.php file.


/**
 * Get the current locale.
 *
 * If the locale is set, then it will filter the locale in the 'locale' filter
 * hook and return the value.
 *
 * If the locale is not set already, then the WPLANG constant is used if it is
 * defined. Then it is filtered through the 'locale' filter hook and the value
 * for the locale global set and the locale is returned.
 *
 * The process to get the locale should only be done once, but the locale will
 * always be filtered using the 'locale' hook.
 *
 * @since 1.5.0
 *
 * @return string The locale of the blog or from the 'locale' hook.
 */
function get_locale() {
    global $locale;

    if ( isset( $locale ) )
        /**
         * Filter WordPress install's locale ID.
         *
         * @since 1.5.0
         *
         * @param string $locale The locale ID.
         */
        return apply_filters( 'locale', $locale );

    // WPLANG is defined in wp-config.
    if ( defined( 'WPLANG' ) )
        $locale = WPLANG;

    // If multisite, check options.
    if ( is_multisite() ) {
        // Don't check blog option when installing.
        if ( defined( 'WP_INSTALLING' ) || ( false === $ms_locale = get_option( 'WPLANG' ) ) )
            $ms_locale = get_site_option('WPLANG');

        if ( $ms_locale !== false )
            $locale = $ms_locale;
    }

    if ( empty( $locale ) )
        $locale = 'en_US';

    /** This filter is documented in wp-includes/l10n.php */
    return apply_filters( 'locale', $locale );
}

As you can see from this function it will run through the filter locale, therefore we can add a function to this filter inside a plugin and change the locale.


/**
 * Return the locale to en_GB
 */ 
function pu_change_language( $locale )
{
    return 'en_GB';
}
add_filter( 'locale', 'pu_change_language');