Internationalizing your WordPress theme makes it usable by people around the world. Over 50% of WordPress installations are in languages other than English. A translation-ready theme opens your work to a global audience and is required for publishing on WordPress.org. The process involves wrapping all text strings in i18n functions and generating translation template files.
This guide covers how to internationalize your WordPress theme for translation.
Text Domain
Every theme needs a text domain — a unique identifier for its translatable strings. Declare the text domain in style.css with the Text Domain header. Load the text domain in functions.php using load_theme_textdomain(). The text domain should match the theme’s slug. Choose it carefully and never change it after release — changing a text domain breaks all existing translations.
Use the text domain as the second parameter in all i18n functions throughout your theme.
PHP Strings
Wrap all user-facing PHP strings in i18n functions. Use __() for simple string translation and _e() when echoing directly. Use _x() and _ex() for strings that need context — like ‘post’ in editorial sense vs ‘post’ as in mail. Use _n() and _nx() for plural strings. Use esc_html__(), esc_html_e(), esc_attr__(), and esc_attr_e() for translated strings in HTML or attribute contexts.
Never translate strings that don’t appear to users — internal identifiers, debug messages, or log entries don’t need translation.
JavaScript Strings
For JavaScript code, use wp.i18n which provides __(), _n(), _x(), and sprintf() functions that work client-side. Enqueue the wp-i18n script as a dependency for your JavaScript files. WordPress extracts strings from your JavaScript during the build process using the @wordpress/i18n package. Use make-pot to generate translation files that include JavaScript strings.
For themes using the block editor, ensure your block translations are properly loaded with the block.json textdomain field.
Translation Files
Generate a POT (Portable Object Template) file containing all translatable strings from your theme. Use WP-CLI’s i18n make-pot command or a plugin like Loco Translate. The POT file is your translation template — translators create .po files from it for each language. Compile .po files to .mo files for WordPress to read.
Include the POT file in your theme’s languages directory. Submit your theme to translate.wordpress.org for community translations.
RTL Support
Right-to-left (RTL) languages like Arabic and Hebrew need special CSS. WordPress automatically loads rtl.css if it exists in your theme directory. Create rtl.css that reverses your layout for RTL languages. Use CSS logical properties like margin-inline-start instead of margin-left for automatic RTL support. Test your theme with an RTL language to verify the layout works correctly.
Il punto fondamentale
Theme internationalization makes your work accessible globally. Set up your text domain, wrap all user-facing strings in i18n functions, handle JavaScript strings with wp.i18n, generate translation files, and add RTL support. Internationalization is required for WordPress.org themes and opens your theme to a worldwide audience.
