wordpress-i18n

WordPress Internationalization (i18n) & Localization (l10n)

This skill covers making WordPress plugins and themes translatable, generating translation files, and handling JavaScript translations.

Core Concepts

Term	Meaning
i18n	Internationalization — preparing code for translation
l10n	Localization — translating strings for a specific locale
Text domain	Unique identifier matching your plugin/theme slug
POT file	Portable Object Template — source strings catalog
PO file	Portable Object — translated strings for one locale
MO file	Machine Object — compiled PO for runtime use
JSON	JavaScript translation files (WP 5.0+)

PHP Translation Functions

Basic Functions

// Return translated string (most common)
$label = __( 'Settings', 'myplugin' );

// Echo translated string
_e( 'Save Changes', 'myplugin' );

// Singular/plural
$message = sprintf(
    /* translators: %d: number of items */
    _n( '%d item found', '%d items found', $count, 'myplugin' ),
    $count
);

// Context-disambiguated (same English string, different meaning)
$label = _x( 'Post', 'noun — a blog post', 'myplugin' );
_ex( 'Post', 'verb — to publish', 'myplugin' );

// Singular/plural with context
$label = _nx( '%d item', '%d items', $count, 'cart items', 'myplugin' );

Escaping + Translation Combos

Always use these when outputting translated strings in HTML:

// Escape for HTML body
echo esc_html__( 'Untrusted translated text', 'myplugin' );
esc_html_e( 'Untrusted translated text', 'myplugin' );

// Escape for HTML attributes
echo esc_attr__( 'Button label', 'myplugin' );
esc_attr_e( 'Button label', 'myplugin' );

// Rich HTML — use wp_kses on translated strings containing markup
printf(
    wp_kses(
        /* translators: %s: settings page URL */
        __( 'Configure <a href="%s">settings</a>.', 'myplugin' ),
        [ 'a' => [ 'href' => [] ] ]
    ),
    esc_url( $settings_url )
);

Function Reference