Guide

What WordPress i18n Is and Why It Matters: Here’s Everything You Need to Know!

Merve Alsan
Written by
Merve Alsan
Merve Alsan
Written by
Merve Alsan
Reviewed
Reviewed by
What WordPress i18n Is and Why It Matters: Here’s Everything You Need to Know!

For the unaware, WordPress is at the core of nearly 43 percent of the world’s websites. Also, the Content Management System (CMS) is available in 205 different locales. As the platform is a global entity, localization is important. The WordPress i18n process is key to this.

The ‘lift pitch’ for i18n is that it’s a way to prepare your theme and plugin code for translation. From there, you can apply accurate translations to other languages, align with other cultures and locales, and reap the benefits.

For this post, we’re going to discuss WordPress i18n in more detail, and show you how to apply it. While you’ll want to have some coding knowledge, we’ll also discuss the steps in detail – along with what WordPress i18n is (and does).

What i18n Stands For

A product of a bygone age, ‘leet speak’ is kind of alive and well in web development circles. While you won’t see much of “l33t” and “n00b”, you will see lots of numeronyms: a11y where the discussion is on accessibility, for example.

In fact, i18n is another numeronym. It stands for “internationalization”, and consists of the first and last letter combined with a number denoting how many other letters are in between. You’ll also find that localization has its own numeronym: l10n. There are other numeronyms too, such as globalization (g11n), Europeanization (e13n), and many more.

Here, we’re going to look specifically at internationalization. The official brief from the World Wide Web Consortium (W3C) notes that this is where the design and development enables simple localization for users of various cultures, locales, languages, and more.

It’s important to note that internationalization is only a first step in the translation process. From there, you’ll carry out localization using a suitable translation solution.

The Basics of the i18n Localization Process

For the i18n process itself, there are a number of steps the WordPress developer will take before they hand off to the translator. In a nutshell, the localization process goes as follows:

  • Add a ‘text domain’ tag to your page headers.
  • Load a language file using some dedicated WordPress functions.
  • ‘Mark up’ strings of text using ‘gettext’ functions (we’ll talk about this in a few moments).
  • Generate a Portable Object Template (POT) file for your theme or plugin, and include it.
  • You may want to create a Cascading StyleSheets (CSS) file for Right-To-Left (RTL) speech.

The translator will take the .pot file and use it to carry out the localization, so it’s an important part of the procedure.

A Brief Primer On the gettext Tool

For the unaware, POT files are an example of those you generate using the GNU gettext tool. This is technology and software from the 1980s that still offers immense value for those conducting i18n today.

Knowing exactly what this is isn’t necessary to carry out WordPress i18n, but it’s useful to understand what it does in a general sense, and what it generates. Consider gettext as a framework that helps WordPress produce multilingual messages.

You’ll often see a number of files associated with gettext:

  • POT files. This is the template for your i18n efforts, and is what the translator uses to kickstart their portion of the process.
  • Portable Object (PO) files. For all intents and purposes, there is no real difference between POT and PO files. During translation, the PO file will contain text strings in both the native and translated languages.
  • Machine Object (MO) files. Consider MO files the WordPress code-friendly version of a PO file. This will live inside the theme or plugin directory of your installation and will serve the translations when WordPress needs them.

With all of this in mind, you can almost begin the i18n process. First, it’s good to prepare your WordPress site for the work ahead.

Before You Begin to Carry Out the WordPress i18n Process

As with any project relating to WordPress core files, you’ll want to make sure your installation is ‘clean’ before you begin. You’ll also want to make sure you can roll back any changes you make, in case the worst scenario happens and you need to restore.

As such, there are two almost non-negotiable ‘pre-steps’ before the i18n process:

  • Backup your site in full. This should be a given because a full backup is the only way to protect your site if you need to start over again.
  • Conduct a plugin audit. It’s a good idea to take a look at all of the plugins your site has, and consider two questions: Is there an update available, and do I need the plugin?

For the latter, we advise you to update the plugins you want to keep, and to delete those surplus to requirements.

Once again, we’re going to be working within your WordPress core files, so you’ll want to have knowledge of how these work, and their contents. Some of the concepts we’ll talk about in the tutorial won’t necessarily have an explanation, although the steps themselves will.

With all of these points complete, you can begin to work on the i18n process.

How to Carry Out the WordPress i18n Process With Your Themes and Plugins

Over the next couple of sections, we’ll show you how to conduct WordPress i18n with your themes and plugins. While each section may be code-heavy and technical in places, we’re going to explain everything as thoroughly as possible, and link to any further resources you may need.

We’ll start with how to internationalize your themes.

How to Make a Translation-Ready WordPress Theme

The first step is to update the theme’s header to include a text domain and domain path. In short:

  • The text domain helps WordPress understand which strings ‘belong’ to the theme. This must match your theme (and plugin’s) slug.
  • The domain path is the folder within your theme’s files where the translation files will ‘live’. The /languages/ directory is the typical and default name, but you could use something else if you need to.

Doing this is a case of adding a few words to the theme’s header file:

/*
   Theme Name: My Custom Theme
   Author: Weglot Translate
   Text Domain: my-theme
   Domain Path: /languages/
*/

Next, you need to load that text domain using an ‘action’ and a ‘function’:

add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup() {
load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
}

This suite of code needs to live in your theme’s functions.php file, rather than that of your site. Once you do this, you can begin to perform a ‘string audit’. This requires you to wrap all of the text strings within your theme in translation functions. There are two functions you’ll use often:

  • __(). This includes a double underscore (or ‘dunder’) and returns a translated string.
  • _e(). This echoes (or prints) the translated string as presented.

These functions require two arguments: the text string, and text domain. For example:

__()
$welcome = __( ‘Hello! Welcome to the dashboard!’, ‘my-theme’ );
_e( ‘Hello again!’, ‘my-theme’ );

While the ins and outs of the various translation functions are beyond the scope of this article, the WordPress Theme Developers’ Handbook has almost every piece of information you need to do the job.


At this point, you can create a POT file. There are lots of solutions to do this, but WordPress recommends Poedit – a free and open-source solution.

Once you download and install Poedit, head to File > New within the toolbar:

Creating a new file on Poedit

Next, create a new catalog. You can click the Extract from sources link in the main screen:

Extract sources on Poedit

Then, fill in the fields for the project name, language team, and primary language on the Translation Properties tab:

Translation properties tab on Poedit

If the file is new, you’ll want to save it here (the file name should be the same as your theme’s slug). Next, select the Sources Paths tab, and locate the /languages/ folder on your computer:

Sources path on Poedit

The final Sources Keywords tab will be a list of the translation functions you’ve used in your theme:

Sources keywords on Poedit

You’ll want to add them here, although it might be tough to find out the right keywords. As a start, you can use the following list:

__
_e
_x
_ex
_n
_nx
_n_noop
_nx_noop
translate_nooped_plural
number_format_i18n
date_i18n
esc_html__
esc_html__
esc_html_x
esc_attr__
esc_attr_e
esc_attr_x

Once you click to confirm, save your changes, and check out your new files: you’ll see MO and PO files on your computer. If you duplicate the PO file, you can add the POT extension, and from here, you can move onto localization.

How to Make a Translation-Ready WordPress Plugin

Your initial task here is similar to a theme: first, update the plugin’s text domain and domain path fields in the header:

/*
   Plugin Name: My Custom Plugin
   Plugin URI: https://weglot.com
   Description: A custom plugin to showcase translation and i18n.
   Author: Weglot Translate
   Version: 1.0
   Author URI: https://weglot.com
   Text Domain: my-plugin
   Domain Path: /languages/
*/

We’d recommend creating a /languages/ folder for the domain path and setting this as the domain path. From there, you can load the text domain for the plugin, but this time you can add the following function to your code, rather than through functions.php:

load_plugin_textdomain( $domain, $abs_rel_path, $plugin_rel_path );

However, this only lets WordPress know there is a translation file available. To load it, you’ll want to wrap the function in an action:

add_action( 'plugins_loaded', 'plugin_load_td' );function plugin_load_td() {
load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
}

Much of the string audit will be similar to theme i18n. The final step is to generate a POT file using the same process as before; the generated file will end up in the current working directory

What the Limitations of WordPress i18n Are


By now, you’ll understand how amazing WordPress i18n can be. It’s great if you develop themes or plugins and want to make them ready to translate. However, like all great things, there are some drawbacks too.

For example, if a plugin contains user-generated content, this won’t be a part of the i18n translation.

The i18n process will enable translations for static elements you code, such as button text. However, if the user wants to enter a specific phrase for a field, create unique labels, and other ‘client-side’ elements, you won’t be able to account for these. In fact, you could, but it’s a complex task and beyond the scope of a post like this.

Also, if you’re not a developer, i18n won’t help you translate your site. For this, you’ll need a plugin, and you might want to skip onto the next section for a suitable option.

It’s also worth noting that while translation plugins can help in many ways, a site will need an average of five plugins to be multilingual in full. In contrast, a solution such as Weglot is quick to work, able to detect all of the translatable parts of a site, and is compatible with almost any theme and plugin. This is regardless of whether those themes and plugins are ready to translate.

What’s more, Weglot uses the theme, plugin, and main content elements from the front HTML page and makes those translatable. As such, there are no .pot and .po files, and the gettext method isn’t necessary either.

How Weglot Supports WordPress i18n

In technical terms, we’re now going to discuss the localization of your content – the direct translation process.

A good translation strategy isn’t easy. It’s hard work and requires lots of planning to make sure your content reaches different cultures, locales, and languages in the right way. This isn’t only about the translated text in your content body. You’ll also want to consider all of the following:

  • The pretty permalinks you use.
  • Post and page metadata.
  • Media, such as images, videos, GIFs, icons, and more – including the associated metadata also.

If you use e-commerce, there are a wealth of considerations here too. For example, you’ll want to make sure that your checkout screen offers a full translation of every element – especially your currency and tax fields:

Nikon camera - French version

What’s more, shipping information is a key aspect to translate in full and to a high quality. You’ll want customers to have no excuse for clicking the Buy button, regardless of the language you use.

Nikon product checkout page

Weglot carries out a lot of the heavy lifting on your behalf. It’s a valuable ally for your WordPress i18n efforts because it detects every aspect of your site that you can translate. From there, it will carry out a first layer of machine translation for you:

Translation list on a WordPress website

This might be enough for your needs, but Weglot can help you go a step further. You’re able to bring in professional translations, edit the existing translations, and much more. This gives you all of the flexibility you need to carry out a full localization of your site.

Conclusion

WordPress is available almost everywhere in the world. As such, internationalized themes and plugins will help when translating them for other languages. WordPress i18n is a vital cog in the wheel for developers who work with the platform.

If you can internationalize your theme to help users create translations without modifying the source code, you’re in a great position. However, just because you apply i18n concepts doesn’t mean your theme or plugin is translated.

To carry out this step, you’ll want to rely on a solution such as Weglot. It’s compatible with lots of different platforms and technologies and works fantastic with WordPress. Once you complete the i18n portion of your workflow, you can turn to Weglot to generate accurate and easy to implement translations in almost any language.

To find out for yourself, Weglot offers a 10-day free trial with no obligation to buy.

In this guide, we're going to look into:

Explore more about working with Weglot

Try for free