Make WordPress Themes Translation Ready
Firstly, you should understand i18n and l10n below.
What is i18n and l10n?
Internationalization and localization (commonly abbreviated as i18n and l10n respectively) are terms used to describe the effort to make WordPress (and other such projects) available in languages other than English for people from different locales, who have different dialects and local preferences.
The process of localizing software has two steps. The first step is when the developers provide a mechanism and method for the eventual translation of the program and its interface to suit local preferences and languages for users worldwide. This process is internationalization (i18n). WordPress developers have done this already, so in theory, WordPress can be used in any language.
The second step is the actual localization (l10n), the process by which the text on the page and other settings are translated and adapted to another language and culture, using the framework prescribed by the developers of the software. WordPress has already been localized into many languages.
Understanding the Localization Framework
Firstly, let’s look at the types of files we’ll be working with so we can understand what’s involved in localizing a theme.
WordPress uses the GNU gettext localization framework for translation and there are three types of files used in the framework:
POT (Portable Object Template) files:
The first step in the translation process is using a program to search through the WordPress source code to pick out text passed into a __() or __e() function, generating a POT file. This file will contain all the text available for translation.
PO (Portable Object) files:
The second step involves translating the text in a POT file into the target language, saving both English and translator messages in a PO file. PO files are identical to POT files in every aspect except for their purpose.
MO (Machine Object) files:
In the last step, the PO file is converted into a machine readable format.
The Text Domain
The first thing you need to do is define your text domain.
What’s a text domain? A text domain is a way of marking translations that belong together. It makes language files much more portable, modular and readable.
Naming text domains is a simple matter because the naming of your plugin/theme dictates what it is. The text domain should match the slug of your wordpress themes, which is usually the name of the folder it is contained in.
For the upcoming Twenty Fifteen theme the name of the theme is, of course, Twenty Fifteen. The slug – which is the name of the folder – is “twentyfifteen.” Since the text domain must be the same as the slug, the text domain is also “twentyfifteen.”
The first place you’ll need to show your text domain is the initial comment block of your wordpress themes. This is used to define basic properties of your plugin like author name, plugin name, theme tags and so on. Make sure to add a “Text Domain” property as well. Here’s Twenty Fifteen’s comment block in its style.css file.
/* Theme Name: Twenty Fifteen Theme URI: wordpress Author: the WordPress team Author URI: wordpress Description: Our default theme is clean, blog-focused, and designed for clarity. Twenty Fifteen's simple, straightforward typography is readable on a wide variety of screen sizes, and suitable for multiple languages. We designed it using a mobile-first approach, meaning your content takes center-stage, regardless of whether your visitors arrive by smartphone, tablet, laptop, or desktop computer. Version: 0.1 License: GNU General Public License v2 or later License URI: Tags: black, blue, gray, pink, purple, white, yellow, dark, light, two-columns, left-sidebar, fixed-layout, responsive-layout, accessibility-ready, custom-background, custom-colors, custom-header, custom-menu, editor-style, featured-images, microformats, post-formats, rtl-language-support, sticky-post, threaded-comments, translation-ready Text Domain: twentyfifteen This theme, like WordPress, is licensed under the GPL. Use it to make something cool, have fun, and share what you've learned with others. */
Include the load_theme_textdomain Function
In order to prep your wordpress themes for localization, you need to include the following function in your theme’s functions.php file.
load_theme_textdomain( 'yourtheme', templatepath.'/languages' );
Change “yourtheme” to the name of your theme and “templatepath” to the location in your wordpress themes folder where you want to save your translation files. I would recommend creating a “Languages” folder in your theme directory and saving your files there.
Localize Your WordPress Themes
The next step is editing the text strings in each of your theme files and turning them into functions so they are translatable. To do this, you just need to wrap them in a__() function call.If your code echoes the string to the browser, use the _e() function instead.
__() and _e() are functionally the same; they translate whatever text is in the parentheses. __() returns the translated text, whereas _e() echoes the translated text out.
Create a POT File
Now that your theme files are ready, the next step is to create a POT file. POT files are often created by theme authors and delivered along with wordpress themes so translators can translate files using Poedit.
There are a few steps involved here. For this tutorial we’ll use Poedit, an easy to use open source program available for Mac OS X, Windows and UNIX/Linux.
- Install Poedit.
- Open Poedit and go to File > New Catalog.
- Fill in your project’s information in the Translation properties tab of the Catalog Properties window.
- Next, go to the Sources paths tab where you’ll need to enter the path for the folder Poedit will use to search for source files containing translatable text. Earlier in this tutorial I recommended creating a “Languages” folder in your theme directory and saving your files there. So in this instance the base path would be “../”
- Click on the Sources keywords tab. Here, we need to define the functions we used to localize the text in our theme files, __() and _e().
- After you click “OK” you’ll be asked to name and save your POT file. By default, Poedit will want to save your file as a .po file but since the two file types are identical you can get around this by simply choosing to save the .po file as a .pot file. Name your file after you theme, give it a .pot extension and save it in a folder named “Languages” in your theme directory.
- When you click “OK” Poedit will scan the folders you specified in the Sources paths tab and will list the localized text in your theme’s files.
- Last step – save your POT file.
Now your theme is translation ready!
If you want to translate your theme, check out Translate Translation-ready WordPress Themes.
