WordPress Translation Functions Reference

Last updated: March 4, 2026

Complete reference for WordPress internationalization functions.

Basic Translation Functions

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

Complete reference for WordPress internationalization functions.

php
$translated = __( 'Hello World', 'my-plugin' );

Complete reference for WordPress internationalization functions.

  • $text (string) – Text to translate
  • $domain (string) – Text domain identifier

Retrieves the translation of a string.

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

Parameters:

php
_e( 'Hello World', 'my-plugin' );

Returns: string – Translated text or original if no translation

_x( $text, $context, $domain = 'default' )

Displays the translation of a string (echoes output).

php
// Same English word, different meanings
$verb = _x( 'Post', 'verb', 'my-plugin' );      // "Publish"
$noun = _x( 'Post', 'noun', 'my-plugin' );      // "Article"

Note: Use echo __() if you need to capture the output.

  • $text (string) – Text to translate
  • $context (string) – Context information for translators
  • $domain (string) – Text domain

_ex( $text, $context, $domain = 'default' )

Retrieves translation with gettext context for disambiguation.

php
_ex( 'Read', 'past participle', 'my-plugin' );

Escaped Translation Functions

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

Parameters:

php
echo '<p>' . esc_html__( 'User content here', 'my-plugin' ) . '</p>';

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

Displays translated string with gettext context.

php
<p><?php esc_html_e( 'Safe HTML output', 'my-plugin' ); ?></p>

esc_attr__( $text, $domain = 'default' )

Retrieves translation and escapes for safe HTML output.

php
echo '<input placeholder="' . esc_attr__( 'Enter name', 'my-plugin' ) . '">';

esc_attr_e( $text, $domain = 'default' )

Displays escaped translation for HTML output.

php
<input title="<?php esc_attr_e( 'Tooltip text', 'my-plugin' ); ?>">

esc_html_x( $text, $context, $domain = 'default' )

Retrieves translation escaped for use in HTML attributes.

php
echo esc_html_x( 'Draft', 'post status', 'my-plugin' );

esc_attr_x( $text, $context, $domain = 'default' )

Displays translation escaped for HTML attributes.

php
echo '<option value="draft">' . esc_attr_x( 'Draft', 'post status', 'my-plugin' ) . '</option>';

Plural Translation Functions

_n( $single, $plural, $number, $domain = 'default' )

Retrieves contextual translation escaped for HTML.

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

Retrieves contextual translation escaped for attributes.

  • $single (string) – Singular form
  • $plural (string) – Plural form
  • $number (int) – Number to determine which form to use
  • $domain (string) – Text domain

Translates singular or plural form based on count.

_nx( $single, $plural, $number, $context, $domain = 'default' )

Parameters:

php
printf(
    _nx( '%s group', '%s groups', $count, 'group of people', 'my-plugin' ),
    number_format_i18n( $count )
);

_n_noop( $singular, $plural, $domain = null )

Note: Different languages have different plural rules. Some have 3+ plural forms.

php
$messages = [
    'comment' => _n_noop( '%s comment', '%s comments', 'my-plugin' ),
    'post'    => _n_noop( '%s post', '%s posts', 'my-plugin' ),
];

// Later, when count is known:
printf( translate_nooped_plural( $messages['comment'], $count, 'my-plugin' ), $count );

Translates plural form with gettext context.

_nx_noop( $singular, $plural, $context, $domain = null )

Registers plural strings without translating. For delayed translation.

php
$labels = [
    'people'  => _nx_noop( '%s group', '%s groups', 'group of people', 'my-plugin' ),
    'animals' => _nx_noop( '%s group', '%s groups', 'group of animals', 'my-plugin' ),
];

translate_nooped_plural( $nooped_plural, $count, $domain = 'default' )

Returns: array with singular, plural, context, and domain keys

php
$message = _n_noop( '%s item', '%s items', 'my-plugin' );
$translated = translate_nooped_plural( $message, $count, 'my-plugin' );

Text Domain Loading Functions

load_textdomain( $domain, $mofile, $locale = null )

Registers contextual plural strings without translating.

php
load_textdomain( 'my-plugin', '/path/to/my-plugin-de_DE.mo' );

Translates a nooped plural when the count is known.

  • $domain (string) – Text domain
  • $mofile (string) – Path to MO file
  • $locale (string|null) – Locale, defaults to current

Loads a .mo or .l10n.php file into a text domain.

load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false )

Parameters:

php
// In plugin main file
add_action( 'init', function() {
    load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );
});

Returns: bool – True on success

load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' )

Loads plugin translations. Registers path for just-in-time loading (since WP 6.7).

php
load_muplugin_textdomain( 'my-mu-plugin', 'my-mu-plugin/languages' );

load_theme_textdomain( $domain, $path = false )

Note: Since WP 4.6, WordPress first checks wp-content/languages/plugins/ before the plugin’s directory.

php
// In functions.php
add_action( 'after_setup_theme', function() {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
});

load_child_theme_textdomain( $domain, $path = false )

Loads must-use plugin translations.

php
load_child_theme_textdomain( 'my-child-theme', get_stylesheet_directory() . '/languages' );

load_default_textdomain( $locale = null )

Loads theme translations.

php
load_default_textdomain( 'fr_FR' );

Loads child theme translations.

unload_textdomain( $domain, $reloadable = false )

Loads WordPress core translations.

php
unload_textdomain( 'my-plugin' );

Note: Called automatically by WordPress. Rarely needed manually.

  • $domain (string) – Text domain to unload
  • $reloadable (bool) – If true, allows just-in-time reloading

load_script_textdomain( $handle, $domain = 'default', $path = '' )

Unloads translations for a text domain.

php
wp_register_script( 'my-script', plugin_url( '/js/app.js', __FILE__ ) );
wp_set_script_translations( 'my-script', 'my-plugin', plugin_dir_path( __FILE__ ) . 'languages' );

Parameters:

Locale Functions

get_locale()

Loads translations for a registered script.

php
$locale = get_locale(); // e.g., 'en_US', 'de_DE', 'fr_FR'

get_user_locale( $user = 0 )

Returns: string|false – JSON-encoded translations or false

php
$locale = get_user_locale();           // Current user
$locale = get_user_locale( 42 );       // User ID 42
$locale = get_user_locale( $user );    // WP_User object

Returns the current site locale.

determine_locale()

Returns a user’s locale preference.

php
$locale = determine_locale();

Falls back to get_locale() if user has no preference.

  • Admin area → user locale
  • Login page → wp_lang parameter/cookie
  • Frontend → site locale
  • Installing → language parameter

switch_to_locale( $locale )

Determines the best locale for the current request.

php
switch_to_locale( 'de_DE' );
echo __( 'Hello', 'my-plugin' ); // German translation
restore_previous_locale();

switch_to_user_locale( $user_id )

Considers:

php
switch_to_user_locale( $user_id );
$message = __( 'Welcome back!', 'my-plugin' );
restore_previous_locale();

restore_previous_locale()

Temporarily switches to a different locale.

php
switch_to_locale( 'fr_FR' );
// ... French output ...
restore_previous_locale(); // Back to previous

Switches to a specific user’s locale.

restore_current_locale()

Restores the previous locale after a switch.

php
switch_to_locale( 'de_DE' );
switch_to_locale( 'fr_FR' );
restore_current_locale(); // Back to original, not de_DE

is_locale_switched()

Returns: string|false – Restored locale or false

php
if ( is_locale_switched() ) {
    // Currently in a switched locale context
}

Utility Functions

is_rtl()

Restores the original locale, clearing the switch stack.

php
if ( is_rtl() ) {
    wp_enqueue_style( 'my-rtl-styles', 'rtl.css' );
}

is_textdomain_loaded( $domain )

Checks if the locale has been switched.

php
if ( ! is_textdomain_loaded( 'my-plugin' ) ) {
    load_plugin_textdomain( 'my-plugin' );
}

has_translation( $singular, $textdomain = 'default', $locale = null )

Checks if the current locale is right-to-left.

php
if ( has_translation( 'Welcome', 'my-plugin' ) ) {
    echo __( 'Welcome', 'my-plugin' );
} else {
    echo 'Welcome'; // Fallback
}

get_translations_for_domain( $domain )

Checks if translations are loaded for a domain.

php
$translations = get_translations_for_domain( 'my-plugin' );
$all_entries = $translations->entries;

Checks if a translation exists for a string. Since WP 6.7.

get_available_languages( $dir = null )

Returns the Translations object for a domain.

php
$languages = get_available_languages();
// ['de_DE', 'fr_FR', 'es_ES', ...]

wp_get_installed_translations( $type )

Returns: Translations|NOOP_Translations

php
$translations = wp_get_installed_translations( 'plugins' );
// ['my-plugin' => ['de_DE' => [...headers...], 'fr_FR' => [...]]]

Gets all available languages based on translation files.

  • $type (string) – ‘plugins’, ‘themes’, or ‘core’

Gets installed translations for plugins, themes, or core.

php
wp_dropdown_languages( [
    'id'       => 'locale',
    'name'     => 'locale',
    'selected' => get_locale(),
] );

wp_get_list_item_separator()

Parameters:

php
$items = ['apples', 'oranges', 'bananas'];
echo implode( wp_get_list_item_separator(), $items );
// English: "apples, oranges, bananas"

translate_user_role( $name, $domain = 'default' )

Renders a language selector dropdown.

php
$role_name = translate_user_role( 'Administrator' );

Number/Date Formatting

number_format_i18n( $number, $decimals = 0 )

Gets the locale-aware list separator.

php
echo number_format_i18n( 1234567.89, 2 );
// English: "1,234,567.89"
// German:  "1.234.567,89"

date_i18n( $format, $timestamp = false, $gmt = false )

Translates a user role name.

php
echo date_i18n( 'F j, Y' );
// English: "January 15, 2024"
// French:  "15 janvier 2024"

Internal Functions

translate( $text, $domain = 'default' )

Formats a number using locale-appropriate separators.

translate_with_gettext_context( $text, $context, $domain = 'default' )

Formats a date using locale-translated month/day names.

_load_textdomain_just_in_time( $domain )

Core translation function. Use __() instead.

before_last_bar( $text )

Core contextual translation. Use _x() instead.

More in L10N

WP_Locale Class Reference

Stores translated locale-specific data including weekdays, months, date formats, and text direction. File: wp-includes/class-wp-locale.php Since:…

WP_Locale Class Reference

Stores translated locale-specific data including weekdays, months, date formats, and text direction. File: wp-includes/class-wp-locale.php Since:…

All WordPress Core Docs View all L10N
View on GitHub