How to Translate WordPress Themes and Plugins

kevin 6 views

Along with the development of WordPress and community’s use of different languages, the demand for language localization is inevitable. Today we’re going to show you how to write code properly while developing WordPress plugin and theme.

What is Translation (Localization)?

Localization is a process by which hard coded content in English is translated into another language. English is a standard language commonly regarded as source one to be translated into target language.

For example, on home page, there are many categories such as “Recent News”, “Gallery”, “Testimonials”. These titles are usually set; yet they should be translated into other languages if their target customers are Japaneses, Germans or Vietnameses.

Another fundamental reason is that the higher localization of plugins/themes, the more users are drawn to them. We refer to it as the “availability of localization” of a product.

Ways to Translate Themes/Plugins in WordPress

The most universal and basic way is using Loco Translate plugin. You can search for guide to Loco Translate on Google.

Another way is developers actively provide the availability of translation in your themes/plugins. Let’s find out more about this approach!

Guide to Translate Themes/ Plugins in WordPress for Developers

Basic things you need to know:

  • You should change words into an argument in functions supported by PHP and WordPress instead of hardcoding. For example:
<h2 class="testimonials__title">Testimonials</h2>

Will be rewritten as:

<h2 class="testimonials__title"><?php _e('Testimonials', 'codetot'); ?></h2>
  • WordPress uses gettext library to produce translations. Although PHP has already some functions, you should use those provided by WordPress to ensure the best quality.

Starting Installation

Setting up Text Domain

In your theme, set up style.css file with textdomain attribute being slug name of the theme.

Take style.css file of Twenty Seventeen theme as an example.

This Text Domain is important as it will be used in three locations i.e.:

  • style.css file as mentioned above.
  • A required value of translation functions.
  • A value of the following function:
load_theme_textdomain()or load_child_theme_textdomain()

Loading Text Domain

The translation of WordPress is usually saved as .po and .mo files. It can be called by using load_theme_textdomain() and load_child_theme_textdomain() functions (if you are using Child Theme).

Certainly, the files from either of these folders below will be downloaded:


From version 4.6 onwards, WordPress automatically checks /languages/ folder in wp-content for translations via (if you have a theme which is being released on That means plugin translated via does not require load_plugin_textdomain() anymore.

If you don’t want to add a load_plugin_textdomain() call to your plugin, you have to set the Requires at least: field in your readme.txt to 4.6.

For example, the code when you want to load the translation into the theme in functions.php file is as below:

function codetot_load_theme_textdomain() {
load_theme_textdomain( 'codetot', get_template_directory() . '/languages' );
add_action( 'after_setup_theme', 'codetot_load_theme_textdomain' );

Translating Simple Values

Translate simple words and word phrases:

// This has not output yet, this is set string $title = __()
__('Testimonials', 'codetot')
// This has echoed, for example <h2><?php _e(); ?></h2>
_e('Connect with us', 'codetot')
// This is for singular / plural
_n( 'One post', '%s posts', $count, 'codetot' )

List of Translation Functions Applicable for WordPress

Simple translation functions

  • __()
  • _e()
  • _x()
  • _ex()
  • _n()
  • _nx()
  • _n_noop()
  • _nx_noop()
  • translate_nooped_plural()

Translation functions including escape (filtering tags like HTML)

  • esc_html__()
  • esc_html_e()
  • esc_html_x()
  • esc_attr__()
  • esc_attr_e()
  • esc_attr_x()

Translation functions for date and number only

  • number_format_i18n()
  • date_i18n()

Ways of Translating Advanced WordPress Themes

Beside splitting hardcoded strings as mentioned in the simple example above, you may encounter cases of dynamic value located in the translation paragraph.

For example:

<?php echo 'Author: $author'; ?>

Then you should use the functions like printf and sprintf:

<?php printf(
/* translators: %s: Name of an author */
__( 'Author: %s.', 'codetot' ),
); ?>

The comment part above (Name of an author) will appear during translation process on or in Loco Translate.

If you have more than one dynamic value, you can write as below:

<?php printf(
/* translators: 1: Category Name 2: Tags */
__( 'Category: %1$s, with tagged: %2$s.', 'codetot' ),
); ?>

Dealing with Translations Containing Plurals.

Imagine that we have to use plurals, for example a post has one or many tags. You use _n to write for these cases:

'%s comment',
'%s comments',
number_format_i18n($comment_total )

As you can see from the function, there are two translatable values for both singular and plural forms. You should pay great attention to this in English.

Dealing with Translation Values Requiring Escape

Escape can be simply understood as values containing characters that need removing otherwise they may result in code errors due to unusual ones accidentally added by users or being attacked.

Examples are as below:

<a title="<?php esc_attr_e( 'Skip to content', 'codetot' ); ?>" class="screen-reader-text skip-link" href="#content" >
<?php _e( 'Skip to content', 'codetot' ); ?>
<label for="nav-menu">
<?php esc_html_e( 'Select Menu:', 'codetot' ); ?>

Things to Note When Translating WordPress Themes/ Plugins

  1. Whatever market themes are made for, you should keep original themes/ plugins in English because it helps you translate safely and have the best chance of avoiding mistakes.
  2. Text language of IT generally needs to be short, concise and easy to understand. Do not use slangs or too clear expressions that may make it hard for users to understand.
  3. Use entire paragraph since word order in many languages is different from that in English.
  4. Split paragraphs properly, i.e. not too long or too short.
  5. Do not add whitespace at the beginning or at the end of the paragraph that needs translating.
  6. Check word size since it varies from one language to another.
  7. Minimize the addition of special characters or unusual structures that causes troubles for translator.
  8. Do not put HTML markup into translated string.
  9. Do not leave URLs for translation, unless they could have a version in another language.
  10. Add the variables as placeholders to the string as in some languages the placeholders change position, for example:
__( 'Search results for: %s', 'my-theme' ),

11. Translate entire sentence with custom values instead of splitting the sentence, for example:

__( 'Your city is %1$s, and your zip code is %2$s.', 'codetot' ),

The above is easier than this below:

__( 'Your city is ', 'codetot' ) . $city . __( ', and your zip code is ', 'codetot' ) . $zipcode;

12. Try to make good use of similar words and limit adding unusual characters to reduce the possibility of translation. One example of incorrect way is as follows

_e('Recent Posts', 'codetot')

_e('Recent Posts:', 'codetot')


The post has provided you with the details about how to translate WordPress themes and plugins. We hope it helps you do your job easier in some ways.

Get Notified of New Articles

30,000+ people are already subscribed to MakiPlace blog. Leave your email to get our weekly newsletter.

Send this to a friend