Geek Mods

If your website is in the commercial theme or plugin space, it is very significant that you know how to localize themes and plugins because it is expected that your site should support multiple languages. The main purpose of this article is to help you understand what “Localization” really means, its importance and the steps needed to localize your project.

Understanding Localization

When localizing WordPress projects, most probably the difficult part is actually being able to understand how to do it. However, you don’t need to be a rocket scientist to be able to localize your WordPress project. One thing that you need to keep in mind before starting your first step is to fully understand its vitality and why developers should take the time to do it.

Definition of Localization

Localization – it is simply the process of by which you prepare your theme for translation. This only means that no matter what the language was used to develop your work, future developers and users won’t have the trouble of translating the project for whatever language is required. On the other hand, localization doesn’t really require that you provide the translations yourself, there are just some few simple steps needed for future translators to do so.

Importance of Localization

A few years ago, it is believed that localization is only needed to be done if the target market for your website is somewhat different with your native language, but nowadays that is not the case. We should all be thankful for the Internet, because of this innovative technology we are now able to converse, communicate and collaborate with people from every part of this globe. The possible and potential audience for any project is broader than it has ever been before.

Another significant factor is that WordPress powers a huge number of modern websites. This is one reason why you should think about your project locally. Localizing commercial themes and plugins is still negotiable, if the platform you’re using uses a variety of languages, this includes WordPress it would also mean that that platform provides a simple and clean way of localizing a theme.

How to Localize

Localizing a theme is more of understanding the major functions in the WordPress API than the actual process of creating the text. Before taking a closer look at an example, it is important that you’ll be able to define a few significant functions and terms.

Localization Key, this is considered as a domain, context or the unique identifier for your strings.

__($text, $key) – this is a function that returns a translated string. It does not echo, display or print the string. This function is often used when there is a need to perform another operation on the translated string. It also accepts two arguments: the string to translate and the localization key.

_e($text, $key) – this is a function that echoes the translated string. This is perfect when you need to retrieve a translated value and display it in your theme or in your plugin.

These are two functions that tell WordPress where to locate your translations:

- load_theme_textdomain($domain, $translation_directory) and

- load_plugin_textdomain($domain, $translation_directory)

Each of these functions acts and serves the same purpose though one is for themes and one is for plugins.

Localizing Your Project

This is how a standard piece of markup looks like:

<h1>My WordPress Blog</h1>
<h2>Just one of the best sites on the Internet</h2>

This paragraph is only the best paragraph that exists in all of the WordPress blogs on the Internet. Read it and enjoy.

There is nothing really amazing about it as it looks like a standard piece of HTML. Granted that this is a very simple example, this is actually what’s required to be able to localize a theme.

To be able to localize the text above, you need to determine the unique identifier that you need to use to localize your text. For this, we’ll be using “GeekMods” and since all of the above text is being displayed on the screen, you’ll have to use the __e() function.

The localized code should be:

<h1><!--?php _e('My WordPress Blog', 'tutsplus'); ?--></h1>
<h2><!--?php _e('Just one of the best sites on the Internet', 'tutsplus'); ?--></h2>

<!--?php _e('This paragraph is only the best paragraph that exists in all of the WordPress blogs on the Internet. Read it and enjoy.', 'tutsplus'); ?-->

For the text that needs to be translated before being displayed on the screen, you won’t have to worry because it is not much different. Here’s how you can localize sidebars.

Processing Translated Text

First step: Setup the sidebar

register_sidebar(
	array(
		'name' => 'Custom Sidebar',
		'id' => 'sidebar'
	)
);

For reference, we’ll be using the register_sidebar function that is available in the WordPress API. Take note that the name of the sidebar is provided on the Widgets page. As such, we need to localize it. However, an array doesn’t accept a string that is being echoed because it only accepts a string value.

For cases like this, we’ll use the __() function:

register_sidebar(
	array(
		'name' => __('Custom Sidebar', 'tutsplus'),
		'id' => 'sidebar'
	)
);

Isn’t it easy?

Another important thing that you need to keep in mind is that localization should only apply to static text. The developer has no responsibility to provide localization of any page content and post content.

Theme and Plugin Preparation for Localization

Once you’re done with your theme and you have properly addressed the text that needs to be localized, you have to let the theme or the plugin find the localizing files. It is vital to take an even closer look at this particular step. Using a ‘lang’ directory in the root of the theme or plugin directory to store the localization files is highly recommended.

Keep in mind that the load_theme_text_domain and the load_plugin_text_domain functions from earlier comes in the view. If you’re working with a theme, you need to define a custom function that is called in the after_theme_setup hook:

function custom_theme_setup() {

} // end custom_theme_setup
add_action('after_theme_setup', 'custom_theme_setup'):

The next step is that you need to tell the function on where to locate the translations, for you to do this you need to add the following lines into your theme:

function custom_theme_setup() {

	// Retrieve the directory for the localization files
	$lang_dir = get_template_directory() . '/lang');

	// Set the theme's text domain using the unique identifier from above
	load_theme_textdomain('tutsplus', $lang_dir);

} // end custom_theme_setup
add_action('after_theme_setup', 'custom_theme_setup'):

Quite simple isn’t it? It’s not really much different for the plugins, same with the themes. You can place your plugin localization files in a ‘lang’ subdirectory. The first thing that you need to do is tell the WordPress where the localization files are located.

Assuming that your files are located in the ‘lang’ directory:

load_plugin_textdomain('tutsplus', false, dirname(plugin_basename(__FILE__)) . '/lang/');

In the second parameter where we have specified ‘false’ is necessary. However, it corresponds to a deprecated function in WordPress.

Then finally, you need to determine where the call the load_plugin_textdomain function. If you’re writing a Widget, you can place this function call in the constructor:

class My_Custom_Widget {

	function My_Custom_Widget() {
		load_plugin_textdomain('tutsplus', false, dirname(plugin_basename(__FILE__)) . '/lang/');
	} // end constructor

} // end My_Custom_Widget

If you’re writing a vanilla plugin there are different ways that you can tell WordPress where the translation files are located. However, you need to have the flexibility to hook into the after_theme_setup function. The same as the code above, you can place this in your plugin:

function custom_plugin_setup() {
	load_plugin_textdomain('tutsplus', false, dirname(plugin_basename(__FILE__)) . '/lang/');
} // end custom_theme_setup
add_action('after_theme_setup', 'custom_plugin_setup'):

After all these, your WordPress themes and plugins are ready for localization.

Two More Considerations

At this point, you can completely consider that your localization task is done. However it is always good to know what is needed to take your work and move forward from there.

Here are two of the most outstanding tasks that translators will normally carry out to translate your theme:

- Translate The Text. Translators will then process your theme through a translation application like: POEdit that is responsible for generating files that are stored in your ‘lang’ directory which the WordPress will locate the files.

- Updates to WP-Config.php. Translators at this point will have to instruct WordPress to enable localization and specify which language they are using. You can read more about it in the Codex.

In contrast with other development platforms that are available, WordPress makes it amazingly easy to localize your project. However, the most challenging part of process to understand the main functions needed to prepare your strings for localization.

Another important thing is that refactoring an existing project takes up too much time. In the context of WordPress it may be dreary but it is relatively easy and convenient to do.