load_plugin_textdomain( string $domain, string|false $deprecated = false, string|false $plugin_rel_path = false ): bool

Loads a plugin’s translated strings.

Description

If the path is not given then it will be the root of the plugin directory.

The .mo file should be named based on the text domain with a dash, and then the locale exactly.

Parameters

$domainstringrequired
Unique identifier for retrieving translated strings
$deprecatedstring|falseoptional
Deprecated. Use the $plugin_rel_path parameter instead.

Default:false

$plugin_rel_pathstring|falseoptional
Relative path to WP_PLUGIN_DIR where the .mo file resides.

Default:false

Return

bool True when textdomain is successfully loaded, false otherwise.

Source

function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false ) {
	/** @var WP_Textdomain_Registry $wp_textdomain_registry */
	global $wp_textdomain_registry;

	/**
	 * Filters a plugin's locale.
	 *
	 * @since 3.0.0
	 *
	 * @param string $locale The plugin's current locale.
	 * @param string $domain Text domain. Unique identifier for retrieving translated strings.
	 */
	$locale = apply_filters( 'plugin_locale', determine_locale(), $domain );

	$mofile = $domain . '-' . $locale . '.mo';

	// Try to load from the languages directory first.
	if ( load_textdomain( $domain, WP_LANG_DIR . '/plugins/' . $mofile, $locale ) ) {
		return true;
	}

	if ( false !== $plugin_rel_path ) {
		$path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/' );
	} elseif ( false !== $deprecated ) {
		_deprecated_argument( __FUNCTION__, '2.7.0' );
		$path = ABSPATH . trim( $deprecated, '/' );
	} else {
		$path = WP_PLUGIN_DIR;
	}

	$wp_textdomain_registry->set_custom_path( $domain, $path );

	return load_textdomain( $domain, $path . '/' . $mofile, $locale );
}

Hooks

apply_filters( ‘plugin_locale’, string $locale, string $domain )

Filters a plugin’s locale.

Changelog

VersionDescription
4.6.0The function now tries to load the .mo file from the languages directory first.
1.5.0Introduced.

User Contributed Notes

  1. Skip to note 5 content

    Loading the plugin translations should not be done during plugins_loaded action since that is too early and prevent other language related plugins from correctly hooking up with load_textdomain() function and doing whatever they want to do.
    Calling load_plugin_textdomain() should be delayed until init action.

    add_action( 'init', 'wpdocs_load_textdomain' );
     
    /**
     * Load plugin textdomain.
     */
    function wpdocs_load_textdomain() {
      load_plugin_textdomain( 'wpdocs_textdomain', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' ); 
    }
  2. Skip to note 7 content

    The text domain name must use dashes and not underscores, be lower case, and have no spaces.

    Source: https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/

    So use ‘wpdocs-textdomain’ instead of ‘wpdocs_textdomain’, e.g.

    load_plugin_textdomain( 'wpdocs-textdomain', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );

  3. Skip to note 8 content

    Plugin Text domain load

    function my_plugin_init() {
        load_plugin_textdomain( 'my-textdomain', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' ); 
    }
    add_action( 'plugins_loaded', 'my_plugin_init' );

You must log in before being able to contribute a note or feedback.