WordPress Internationalization: How to Translate WordPress Themes and Plugins

Preparing Your WordPress Theme or Plugin for Translation

Before you can translate anything, you need to set up your code correctly. This means defining a text domain, wrapping all user-facing strings in gettext functions, and generating a POT file. 

None of this is complicated, but the details matter. A mismatched text domain or an unwrapped string means that text will never appear in your translated output.

Every theme or plugin needs a text domain. It’s a unique identifier that tells WordPress which translation files belong to your project, and it should match your plugin or theme slug exactly.

Declare it in your plugin’s main file header:

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

Or in your theme’s style.css:

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

The domain path tells WordPress where your translation files live relative to the plugin or theme root. The /languages directory is the standard.

Any string you want to make translatable needs to be wrapped in one of WordPress’s gettext functions. At runtime, these functions look up the correct translation and fall back to the original string if no translation is found.

Basic Strings

Use __() when you need to return a string. For HTML output (which is almost always the case), use the escaped variants:

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

WordPress coding standards recommend echo esc_html__() over _e() because it makes output escaping explicit. It’s a good habit to apply consistently.

Strings with Variables

If you concatenate a variable directly into a string, translators only see the fragments, not the full sentence. That makes it impossible to translate correctly, especially in languages where word order is different. Instead, use printf() or sprintf() with a placeholder, and add a translator comment so they know what %s represents:

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

Plural Forms

In English, plurals are simple: one comment, two comments. Other languages aren’t that straightforward. Some have multiple plural forms depending on the number. Use _n() to handle this correctly no matter which language your plugin is translated into:

printf(
    esc_html( _n(
        '%s comment',
        '%s comments',
        $count,
        'my-plugin'
    ) ),
    number_format_i18n( $count )
);

printf(
    esc_html( _n(
        '%s comment',
        '%s comments',
        $count,
        'my-plugin'
    ) ),
    number_format_i18n( $count )
);

Strings That Need Context

Some words mean different things depending on where they appear. Use _x() to give translators the context they need to get the translation right:

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

WordPress provides the wp-i18n package so you can use the same gettext functions in JavaScript that you use in PHP. When registering your script, declare wp-i18n as a dependency:

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

Then in your JavaScript file:

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

If you’re using a bundler like Webpack, use @wordpress/babel-plugin-makepot to extract translatable strings from your bundle as part of your build process.

Once you wrap your strings, you need to generate a POT (Portable Object Template) file. This is the source file that PTC (or any translator) works from. It contains all your translatable strings but no translations yet.

Run this command from your plugin or theme’s root directory:

wp i18n make-pot . languages/my-plugin.pot

wp i18n make-pot . languages/my-plugin.pot

WP-CLI scans your PHP, JavaScript, and block.json files for gettext calls and compiles them into a single POT file. If you’re using Composer, you can add this as a Composer script so the command stays consistent across your team and doesn’t require a global WP-CLI install.

The full wp i18n suite includes everything else you’ll need later in the workflow: