Hybrid Core is a translation-friendly theme framework. It even takes care of a few steps of the process for you, so you don’t have to do them when creating a WordPress theme.
As a theme developer, you should always make your theme easy to translate. The majority of the Internet doesn’t even use English, so by not not making your theme translatable, you’re doing a huge disservice to your theme users and limiting the number of theme downloads you’ll actually get.
What is i18n?
is just an abbreviation for the term “internationalization.” Really, who wants to type out that lengthy word all the time? We developers like to make things a bit easier than that.
Internationalizing a theme means wrapping text strings with special
gettext functions for translation. You don’t have to know any other languages. You simply wrap text with one of several special functions.
Many people mistakenly refer to “internationalization” as “localization.” These two are not the same thing. In simple terms, internationalization refers to marking something as translatable. Localization refers to the actual process of translation via whatever mechanism is in place by the software. So, theme/plugin developers “internationalize” their themes/plugins. WordPress provides the mechanism to “localize” them.
Marking strings for translation
To internationalize your theme, you only need to wrap your text strings in special functions that WordPress provides. Which function you use will be different depending on the scenario. I highly recommend reading i18n for WordPress Developers on the Codex, which will cover this in more detail. This tutorial will just provide a basic overview.
The two most common internationalization functions are
__(). Let’s take a look at the former:
_e( $text, $textdomain );
There are two parameters that you must input:
- This is the actual text that you want to allow translation of.
- This is a unique string that you use for all of your text on the site. Think of it as a unique “key” only for your theme. It should match your theme folder name exactly.
_e() function prints text directly to the screen. So, if you had the text “Welcome to my site!”, you’d write the code like in the following line.
_e( 'Welcome to my site!', 'themename' );
__() function is similar except that it returns the translated text rather than printing it. This is usually useful when you’re assigning the string to a variable.
$text = __( 'Welcome to my site!', 'themename' );
There are other special cases where you need to use different functions, so be sure to read the documentation linked above.
When building a theme off the Hybrid Core framework, you need your textdomain to match your theme folder name exactly. Hybrid Core needs this so that it can appropriately load the correct translation files as well as work some other black magic behind the scenes. Plus, it’s just plain smart to use your theme folder name as the textdomain.
Suppose you were building a theme called “Magical Wonderland.” Your theme folder name would be
magical-wonderland. That means your textdomain would be the same.
So, when you use functions like
__() (shown above), they should be used like so:
_e( 'Your text string', 'magical-wonderland' );
Creating translation files
Hybrid Core expects theme translation files to be within the theme’s
/languages folder. So, if you haven’t already done so, create a special folder to hold translations in your theme.
Generating translation files is a bit outside the scope of this particular tutorial. You should read the WordPress documentation on how to do this.
The big thing you need to do here is make sure your translation files begin with your textdomain. So, if you were creating default
en_EN.mo files, these should be prefixed with your theme textdomain (see above section). So, these files would be
What does Hybrid Core do for you?
Well, you may be wondering what Hybrid Core actually does if you have to go through all the work of marking up your text strings. The following is a list of the features it offers.
- Loads translation files placed within your theme’s
- Loads translation files from child themes. A child theme can also hold the parent theme’s translation so that it’s not lost on upgrade of the parent theme.
- Loads an
en_EN.phpfunctions file (or any specific language file) if it exists. This file works just like a theme’s
functions.phpexcept that it’s only loaded for specific languages.
- Allows you to translate the framework’s text strings within your theme translation file and use these translations if they exist.