How To Translate Your WordPress Theme or Plugin

Translating your WordPress theme or plugin into different languages is a great way to increase its reach and adoption. However, it’s not as easy as simply dropping the text into a translation tool and publishing the results.

Translating your WordPress theme or plugin into different languages is a great way to increase its reach and adoption. However, it’s not as easy as simply dropping the text into a translation tool and publishing the results. In this article, we’ll walk you through some of the important considerations to make and the steps you need to complete to work around them.

Gettext/Portable Language Files

WordPress uses the PHP industry-standard of Portable Object (PO) files for multilingual websites to manage and maintain translation files. The files you need to be aware of are:

  • Portable Object Template (POT) — This is the file that you get when you extract texts from the application. Normally, you send this file to your translators.
  • Portable Object (PO) — This is the file that you receive back from the translators. It’s a text file that includes the original texts and the translations.
  • Machine Object (MO) — The MO file includes the exact same contents as the PO file. The two files differ in their format. While a PO file is a text file and is easy for humans to read, MO files are compiled and are easy for computers to read. Your web server will use the MO file to display the translations.

Gettext is an internationalization and localization system used for writing multilingual programs. Its main benefit is separating programming from translating.

The gettext function accepts a string in the original language and uses the string to lookup translations in another language. If it does not find a translation, it returns the original string provided.

WordPress provides a few helper functions for a developer to use when retrieving a translation of a string.

Retrieve the translation of $text:

__( string $text, string $domain = 'default' )

Display translated text:

_e( string $text, string $domain = 'default' )

Retrieve the translation of $text and escapes it for safe use in HTML output:

esc_html__( string $text, string $domain = 'default' )

Display translated text that has been escaped for safe use in HTML output:

esc_html_e( string $text, string $domain = 'default' )

Localization and Internationalization

Internationalization, sometimes written as i18n, refers to the design or development of an application or product in a way that makes it easy to localize it for specific target audiences. 

This process is ultimately achieved by wrapping strings in gettext functions making them translatable.

Localization, sometimes written as l10n, is the process of adapting your theme or application to meet the language requirements of a specific target audience, referred to as a locale. This, in simple terms, involves taking all translatable strings in a project and adding the respective translations to a different language for each.

When i18n is done well, users who speak a different language can then translate your theme to the language of their locale without changing the source code or how the theme functions. However, there are a few key considerations to make with internationalization in WordPress:

  • Loading a text domain for your theme. For example:

    load_theme_textdomain( 'understrap', get_template_directory() . '/languages' );

    The first argument defines the theme’s domain as the text for translation and must be a unique identifier. The second argument defines a folder to locate the language files. It’s ideal to hook this function into the WordPress “after_setup_theme” action.
  • Plurals and Singular. Some strings are displayed a singular or plural based on a supplied number, for cases like these, the _n() function is handy. This function accepts four arguments:
    • Singular
    • Plural
    • Count
    • Text domain

printf( esc_html( _n( 'You have %d comment.', 'You have %d comments.', $count, 'understrap'  ) ), $count );

  • Disambiguation by context. When translating from one language to another, it’s possible that the usage and grammar around a specific word changes depending on the target language. The word “Post” can be used as a verb (“Click here to post your comment”) or noun (“Edit this post”), In such cases the _x() function should be used. Similar to __(), it accepts a second argument — the context.

Translating Your WordPress Theme

To contribute translations to your theme, you will need to log in to your WordPress account.

A General Translation Editor (GTE) can moderate translations and a Locale Manager (LM) can appoint a user as Project Translation Editor (PTE) in the backend of the Rosetta site. There are two types of users who may request a review and/or PTE status:

  • The relevant plugin/theme author; and,
  • A translator

As a plugin/theme author whose project is on the plugin/theme directory, you can nominate existing active translators to become PTEs for your project.

  1. Visit the hosted theme on and on the sidebar under translations, click on “translate theme”

  2. From the list of locales displayed, select the specific local you want to contribute to. Be sure to follow the style guide provided by the WordPress Polyglot community for that locale.

  3. Once you have selected a local to translate, a list of all localized strings is displayed with corresponding translation status for that locale. For this example, I selected the French (France) locale. The legend at the bottom of the list provides more context about a string translation.

  4. To add a suggestion for the “Current password” string I need to double-click the string, input the corresponding French translation, and click suggest. The status of the string is then changed to “waiting” and will need to be approved by a Translation Editor for that locale or Project.

  5. As of the time of writing, translation editors are not automatically notified of new string translations and you need to reach out to them to request a translation review. Visit the documentation provided by your locale team to find out their preferred contact method. Once an editor reviews your suggestions, they will communicate any required changes and approve all valid suggestions.

If you are new to translating WordPress, they recommend reading through the translation handbook. It is a valuable resource with all the information you need to get started.

As the internet continues to drive a globalized economy, it is important to create tools that can cater to an increasing number of communities. Having an internationalized theme with localization enabled creates the potential for users across the globe to benefit from your product.