load_plugin_textdomain() │ WP 1.5.0

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

The .mo file should be named: TRANSLATION_DOMAIN-LOCALE.mo, where the locale is the language code (see get_locale()). For example, if TRANSLATION_DOMAIN=my-plugin and Russian is selected (LOCALE=ru_RU), 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. If your plugin needs translations earlier, you should reconsider the logic of initializing the plugin or those parts of the code where translations are required.

If translations are loaded earlier, for example on the plugins_loaded event, it might be too early and could interfere with other plugins that work with translations, properly connecting to the load_textdomain() function and performing necessary actions. Therefore, it is recommended to delay loading until the init event.

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

As of version 6.7.0, it is required to call it on the init hook or later.

To load a theme translation, use load_theme_textdomain().

Uses: load_textdomain()

No Hooks.

Returns

true|false. Returns false if the .mo file does not exist at the specified path. Otherwise, the function returns true.

Usage

load_plugin_textdomain( $domain, $deprecated, $plugin_rel_path );
$domain(string) (required)
A unique identifier for retrieving the translation string.
$deprecated(string)
Deprecated argument, used up to version 2.7. A path similar to ABSPATH, to the .mo file.
Default: false
$plugin_rel_path(string)

The path to the .mo file directory relative to WP_PLUGIN_DIR.

If the path is not specified, the root plugins directory WP_PLUGIN_DIR will be used. Thus, the file path 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 6.7.1

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