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

Loads a plugin’s translated strings.

Contents

Description
Parameters
Return
Source
Hooks
Related
- Uses
- Used By
Changelog
User Contributed Notes
- Feedback
- Feedback

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

$domain string Required: Unique identifier for retrieving translated strings
$deprecated string|false Optional: Deprecated. Use the $plugin_rel_path parameter instead.

Default: false
$plugin_rel_path string|false Optional: Relative path to WP_PLUGIN_DIR where the .mo file resides.

Default: false

Return

bool True when textdomain is successfully loaded, false otherwise.

Source

File: wp-includes/l10n.php. View all references

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

View on Trac View on GitHub

Hooks

apply_filters( 'plugin_locale', string $locale, string $domain )

Filters a plugin’s locale.

Uses

Uses
Uses	Description
WP_Textdomain_Registry::set_custom_path() wp-includes/class-wp-textdomain-registry.php	Sets the custom path to the plugin’s/theme’s languages directory.
determine_locale() wp-includes/l10n.php	Determines the current locale desired for the request.
load_textdomain() wp-includes/l10n.php	Loads a .mo file into the text domain $domain.
_deprecated_argument() wp-includes/functions.php	Marks a function argument as deprecated and inform when it has been used.
apply_filters() wp-includes/plugin.php	Calls the callback functions that have been added to a filter hook.

Show 2 more uses Hide more uses

Used By

Used By
Used By	Description
_get_plugin_data_markup_translate() wp-admin/includes/plugin.php	Sanitizes plugin data, optionally adds markup, optionally translates.

Changelog

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

User Contributed Notes

Skip to note 1 content

You must log in to vote on the helpfulness of this noteVote results for this note: 21You must log in to vote on the helpfulness of this note

Contributed by Fahad Alduraibi — 7 years ago
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' ); 
}
```
Top ↑
Feedback
- I’ve found the after_setup_theme can work better. The default WordPress themes use this hook to load the theme textdomains and some plugin init actions require the translations to be in place and load before the default priority 10. — By joost de keijzer — 2 years ago
- Loading plugin textdomain on init hook doesn’t work for all the strings. For example, translations for admin menu items will not be loaded, while later strings will be translated. — By viknov — 7 months ago
- “The text domain name must use dashes and not underscores, be lower case, and have no spaces.” — By Gabriel Reguly — 1 week ago
Log in to add feedback
Skip to note 2 content

You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

Contributed by Pablo Pacheco — 4 years ago

Just a note,

load_plugin_textdomain() will try to load the mo file firstly from:
WP_LANG_DIR . ‘/plugins/’ . $mofile

Only if it is not able to it will load it from WP_PLUGIN_DIR folder

Log in to add feedback
Skip to note 3 content

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

Contributed by Gabriel Reguly — 1 week ago

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

Log in to add feedback
Skip to note 4 content

You must log in to vote on the helpfulness of this noteVote results for this note: -3You must log in to vote on the helpfulness of this note

Contributed by Binsaifullah — 3 years ago
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' );
```
Top ↑
Feedback
- See note by Fahad Alduraibi above: You should load plugin textdomains during the init action (and not plugins_loaded). — By Philipp Stracker — 3 years ago
Log in to add feedback

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