The WordPress plugin directory serves users in over 200 countries. If your plugin is only available in English, you’re excluding a significant portion of your potential market. Internationalization (i18n) — preparing your plugin for translation — is one of the highest-ROI investments you can make as a plugin developer.
WordPress has a mature internationalization system that makes it straightforward to prepare your plugin for translation into any language. The system uses gettext, a widely adopted translation framework, and works with tools like Poedit and GlotPress.
The Core Functions: __(), _e(), and Friends
WordPress provides several functions for internationalization. The most basic is __(), which returns a translated string. Its counterpart _e() echoes the translated string directly. Use __() when you need to capture the translated string for a variable, and _e() when you’re outputting it directly in HTML.
For strings that include placeholders, use sprintf() with the translated string as the format argument. WordPress also provides _n() for singular/plural handling, _x() for strings that need context (like “post” as a verb vs. a noun), and _nx() for context-aware plural forms.
Text Domains: How WordPress Identifies Your Plugin’s Strings
Every plugin that uses internationalization needs a unique text domain. This is a string that identifies your plugin’s translations in the WordPress system. The text domain should match your plugin’s slug exactly, and it’s defined in your plugin’s header comment.
Load the text domain in your plugin’s initialization using load_plugin_textdomain(). This function tells WordPress where to find your translation files. The standard location is your plugin’s /languages/ directory.
Creating Translation Files
Translation files use the .po (Portable Object) and .mo (Machine Object) formats. The .po file is human-readable and contains the original strings with their translations. The .mo file is a compiled binary that WordPress reads for performance.
Generate the initial .pot (Portable Object Template) file using a tool like WP-CLI’s i18n command or Poedit. The .pot file contains all the translatable strings from your plugin. Translators use the .pot file as a template to create .po files for each language.
Name your files using the standard format: {text-domain}-{locale}.po. For Italian, that’s my-plugin-it_IT.po. Once the .po file is translated, compile it to .mo format using msgfmt or Poedit’s save function.
Best Practices for Translatable Strings
Writing strings that translate well requires some discipline. Here are the most important practices:
- Use full sentences rather than concatenated fragments. Translators need the full context to produce accurate translations.
- Avoid HTML inside translatable strings. If you need HTML in a translated string, use sprintf() to insert the HTML as a variable.
- Don’t split sentences across multiple __() calls. Each call is translated independently, and sentence structure varies between languages.
- Include translator comments for ambiguous strings. Use a PHP comment starting with “translators:” above the __() call to provide context.
- Use placeholders for numbers, names, and dynamic values. Translators need to see the full sentence structure to produce natural translations.
- Hardcode the text domain in every internationalization call. Don’t use a variable for the text domain — it breaks translation tools’ ability to extract your strings.
JavaScript Internationalization
If your plugin uses JavaScript (for Gutenberg blocks, admin interfaces, or frontend interactivity), you need to internationalize those strings too. WordPress provides the wp-i18n package for JavaScript, which mirrors the PHP internationalization functions.
Use the __() and _n() functions from @wordpress/i18n in your JavaScript code. Set up the script translations using wp_set_script_translations() in PHP, which tells WordPress to load the translation files for your script.
Using the WordPress.org Translation Platform
If your plugin is on the WordPress.org plugin directory, you can leverage the community translation platform. Translators around the world can contribute translations for your plugin through translate.wordpress.org.
To enable community translations, ensure your plugin has a .pot file and your text domain is correctly set up. The WordPress.org system will automatically detect your plugin and make it available for translation. Community translations are automatically packaged with plugin updates.
The Bottom Line
Internationalization is not difficult, but it requires consistent discipline. Use the WordPress internationalization functions for every string that could appear in the user interface. Generate your .pot file regularly. Test your plugin with a translation language to catch hardcoded strings you might have missed.
The effort pays off when your plugin reaches users who don’t speak English. Many of the most successful WordPress plugins have translations in 20+ languages, and those translations are often contributed by the community rather than the developer. Make it easy for translators to contribute, and they will.