load_plugin_textdomain() │ WP 1.5.0

Connects the .mo translation file from the specified folder. Does not work with MU plugins.

.mo file must be named: DOMAIN_TRANSLATION-LOCALE.mo, where locale is the language code (see get_locale()). For example, if DOMAIN_TRANSLATION=my-plugin and the Russian language is selected (LOCALE=ru_RU), then the files should be named: my-plugin-ru_RU.mo and my-plugin-ru_RU.po.

It is recommended to call the function on the init hook, but it can also be called earlier on the muplugins_loaded, plugins_loaded hooks.

Since WP 6.7.0, translations are not loaded immediately but are registered for loading at the appropriate time (if it has not yet occurred).

If the function is called BEFORE the init hook, the translation will still be loaded on the init hook.

For more details see here.

Since version 4.6, the function first attempts to load the .mo file from the WP_LANG_DIR/plugins/ folder, usually this is /wp-content/language/plugins.

Use load_theme_textdomain() to connect the theme translation.

Uses: load_textdomain()

No Hooks.

Returns

true|false. Will return false if the .mo file does not exist at the specified path. In other cases, the function will return true.

Usage

load_plugin_textdomain( $domain, $deprecated, $plugin_rel_path );
$domain(string) (required)
Unique identifier for retrieving the translation string.
$deprecated(string)
Deprecated argument, works until version 2.7. Path similar to ABSPATH, to the .mo file.
Default: false
$plugin_rel_path(string)

Path to the directory of the .mo file relative to WP_PLUGIN_DIR.

If the path is not specified, it will be the root directory of plugins WP_PLUGIN_DIR. That is, the path to the file will be: WP_PLUGIN_DIR/domain-ru_RU.mo

Default: false

Examples

0

#1 Registering a translation file for the plugin

It is assumed that this code will be located in the main plugin file or in a file that is in the plugin's root directory. If this is not the case, __FILE__ must be replaced by the appropriate path.

Translation file must lie in the directory of the plugin and must be named: my-plugin-ru_RU.mo.

add_action( 'plugins_loaded', 'myplugin_init' );
function myplugin_init(){
	load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) );
}
0

#2 If we want to put the translation file .mo in the languages subfolder: 

add_action( 'plugins_loaded', 'myplugin_init' );

function myplugin_init() {
	 load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
}
0

#3 Register a translation file for the MU plugin

WP has a special function load_muplugin_textdomain().

Notes

  • Global. WP_Textdomain_Registry. $wp_textdomain_registry WordPress Textdomain Registry.
  • Global. Array<String,. WP_Translations|NOOP_Translations> $l10n An array of all currently loaded text domains.

Changelog

Since 1.5.0 Introduced.
Since 4.6.0 The function now tries to load the .mo file from the languages directory first.
Since 6.7.0 Translations are no longer immediately loaded, but handed off to the just-in-time loading mechanism.

load_plugin_textdomain() code WP 7.0

wp-includes/l10n.php 
function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false ) {
	/** @var WP_Textdomain_Registry $wp_textdomain_registry */
	/** @var array<string, WP_Translations|NOOP_Translations> $l10n */
	global $wp_textdomain_registry, $l10n;

	if ( ! is_string( $domain ) ) {
		return false;
	}

	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 );

	// If just-in-time loading was triggered before, reset the entry so it can be tried again.
	if ( isset( $l10n[ $domain ] ) && $l10n[ $domain ] instanceof NOOP_Translations ) {
		unset( $l10n[ $domain ] );
	}

	return true;
}

textdomain (mo po files)

localize (l10n i18n Internationalization localization)

Localization