load_textdomain( string $domain, string $mofile, string $locale = null ): bool

Loads a .mo file into the text domain $domain.

Description

If the text domain already exists, the translations will be merged. If both sets have the same string, the translation from the original value will be taken.

On success, the .mo file will be placed in the $l10n global by $domain and will be a MO object.

Parameters

$domainstringrequired
Text domain. Unique identifier for retrieving translated strings.
$mofilestringrequired
Path to the .mo file.
$localestringoptional
Locale. Default is the current locale.

Default:null

Return

bool True on success, false on failure.

Source

function load_textdomain( $domain, $mofile, $locale = null ) {
	/** @var WP_Textdomain_Registry $wp_textdomain_registry */
	global $l10n, $l10n_unloaded, $wp_textdomain_registry;

	$l10n_unloaded = (array) $l10n_unloaded;

	/**
	 * Filters whether to short-circuit loading .mo file.
	 *
	 * Returning a non-null value from the filter will effectively short-circuit
	 * the loading, returning the passed value instead.
	 *
	 * @since 6.3.0
	 *
	 * @param bool|null   $loaded The result of loading a .mo file. Default null.
	 * @param string      $domain Text domain. Unique identifier for retrieving translated strings.
	 * @param string      $mofile Path to the MO file.
	 * @param string|null $locale Locale.
	 */
	$loaded = apply_filters( 'pre_load_textdomain', null, $domain, $mofile, $locale );
	if ( null !== $loaded ) {
		if ( true === $loaded ) {
			unset( $l10n_unloaded[ $domain ] );
		}

		return $loaded;
	}

	/**
	 * Filters whether to override the .mo file loading.
	 *
	 * @since 2.9.0
	 * @since 6.2.0 Added the `$locale` parameter.
	 *
	 * @param bool        $override Whether to override the .mo file loading. Default false.
	 * @param string      $domain   Text domain. Unique identifier for retrieving translated strings.
	 * @param string      $mofile   Path to the MO file.
	 * @param string|null $locale   Locale.
	 */
	$plugin_override = apply_filters( 'override_load_textdomain', false, $domain, $mofile, $locale );

	if ( true === (bool) $plugin_override ) {
		unset( $l10n_unloaded[ $domain ] );

		return true;
	}

	/**
	 * Fires before the MO translation file is loaded.
	 *
	 * @since 2.9.0
	 *
	 * @param string $domain Text domain. Unique identifier for retrieving translated strings.
	 * @param string $mofile Path to the .mo file.
	 */
	do_action( 'load_textdomain', $domain, $mofile );

	/**
	 * Filters MO file path for loading translations for a specific text domain.
	 *
	 * @since 2.9.0
	 *
	 * @param string $mofile Path to the MO file.
	 * @param string $domain Text domain. Unique identifier for retrieving translated strings.
	 */
	$mofile = apply_filters( 'load_textdomain_mofile', $mofile, $domain );

	if ( ! is_readable( $mofile ) ) {
		return false;
	}

	if ( ! $locale ) {
		$locale = determine_locale();
	}

	$mo = new MO();
	if ( ! $mo->import_from_file( $mofile ) ) {
		$wp_textdomain_registry->set( $domain, $locale, false );

		return false;
	}

	if ( isset( $l10n[ $domain ] ) ) {
		$mo->merge_with( $l10n[ $domain ] );
	}

	unset( $l10n_unloaded[ $domain ] );

	$l10n[ $domain ] = &$mo;

	$wp_textdomain_registry->set( $domain, $locale, dirname( $mofile ) );

	return true;
}

Hooks

do_action( ‘load_textdomain’, string $domain, string $mofile )

Fires before the MO translation file is loaded.

apply_filters( ‘load_textdomain_mofile’, string $mofile, string $domain )

Filters MO file path for loading translations for a specific text domain.

apply_filters( ‘override_load_textdomain’, bool $override, string $domain, string $mofile, string|null $locale )

Filters whether to override the .mo file loading.

apply_filters( ‘pre_load_textdomain’, bool|null $loaded, string $domain, string $mofile, string|null $locale )

Filters whether to short-circuit loading .mo file.

Changelog

VersionDescription
6.1.0Added the $locale parameter.
1.5.0Introduced.

User Contributed Notes

  1. Skip to note 4 content

    There are situations where one requires a plugin translation locale to be loaded which is different from the current user locale.

    For example, in multilingual websites, creating a translation of a post/widget may require some translations to be loaded for a given plugin text domain. The user locale (dashboard locale) is loaded by default, so it is important to unload that if it has been loaded already and seek the translation file to load for the text domain for the requested locale,

    if ( is_textdomain_loaded( $plugin ) ) {
    	unload_textdomain( $plugin );
    }
    $mofile = sprintf( '%s-%s.mo', $plugin, $locale );
    //check the installation language path first.
    $domain_path = path_join( WP_LANG_DIR, 'plugins' );
    $loaded = load_textdomain( $plugin, path_join( $domain_path, $mofile ) );
    
    if ( ! $loaded ) { //else, check the plugin language folder.
    	$domain_path = path_join( WP_PLUGIN_DIR, "{$plugin}/languages" );
    	load_textdomain( $plugin, path_join( $domain_path, $mofile ) );
    }

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