load_textdomain() │ WP 1.5.0

Connects the specified translation file.

The function parses the specified .mo or .l10n.php file and adds the data from it to the WordPress translation data - to the global variable $l10n:

If the specified domain already exists in the data, the loaded localization strings will be merged with the existing ones (merged into a single array).

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.

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

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

For more details read here.

Other functions for registering translations:

Uses: WP_Textdomain_Registry::set()
Used By: load_muplugin_textdomain(), load_plugin_textdomain(), load_theme_textdomain()
Hooks from the function

Returns

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

Usage

load_textdomain( $domain, $mofile, $locale );
$domain(string) (required)
A unique identifier that can be used to reference the translation string later.
$mofile(string) (required)
The absolute path to the .mo file (home/example.com/wp-content/plugins/my-plugin.mo).
$locale(string) (WP 6.1)
The locale.
Default: null (current locale)

Examples

0

#1 Line translation in WordPress

In this example, translate the string __( 'book', 'mydomain' ). It is assumed that a .mo file has already been created and has the data to translate this string:

// here the .mo file must be in the `lang` folder, which is in 
// the folder that contains the file in which this (string - code) is called.
// Connect the existing .mo file (file name: ru_RU.mo or other, depending on the locale)
add_action( 'plugins_loaded', 'load_my_textdomain' );

function load_my_textdomain(){
	$mo_file_path = dirname(__FILE__) . '/lang/'. determine_locale() . '.mo';

	load_textdomain( 'mydomain', $mo_file_path );
}

For WP versions earlier than 5.0, use get_locale() instead of determine_locale().

Now in the theme we use:

<?php _e( 'book', 'mydomain' ); ?>

The "βιβλίο" will come out for Greek locale.

0

#2 Load translation which is different from the current user locale.

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

// else, check the plugin language folder.
if ( ! $loaded ) { 
	$domain_path = path_join( WP_PLUGIN_DIR, "{$plugin}/languages" );
	load_textdomain( $plugin, path_join( $domain_path, $mofile ) );
}

Notes

  • Global. MO[]. $l10n An array of all currently loaded text domains.
  • Global. MO[]. $l10n_unloaded An array of all text domains that have been unloaded again.
  • Global. WP_Textdomain_Registry. $wp_textdomain_registry WordPress Textdomain Registry.

Changelog

Since 1.5.0 Introduced.
Since 6.1.0 Added the $locale parameter.

load_textdomain() code WP 7.0

wp-includes/l10n.php 
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;

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

	/**
	 * 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 ( ! $locale ) {
		$locale = determine_locale();
	}

	$i18n_controller = WP_Translation_Controller::get_instance();

	// Ensures the correct locale is set as the current one, in case it was filtered.
	$i18n_controller->set_locale( $locale );

	/**
	 * Filters the preferred file format for translation files.
	 *
	 * Can be used to disable the use of PHP files for translations.
	 *
	 * @since 6.5.0
	 *
	 * @param string $preferred_format Preferred file format. Possible values: 'php', 'mo'. Default: 'php'.
	 * @param string $domain           The text domain.
	 */
	$preferred_format = apply_filters( 'translation_file_format', 'php', $domain );
	if ( ! in_array( $preferred_format, array( 'php', 'mo' ), true ) ) {
		$preferred_format = 'php';
	}

	$translation_files = array();

	if ( 'mo' !== $preferred_format ) {
		$translation_files[] = substr_replace( $mofile, ".l10n.$preferred_format", - strlen( '.mo' ) );
	}

	$translation_files[] = $mofile;

	foreach ( $translation_files as $file ) {
		/**
		 * Filters the file path for loading translations for the given text domain.
		 *
		 * Similar to the {@see 'load_textdomain_mofile'} filter with the difference that
		 * the file path could be for an MO or PHP file.
		 *
		 * @since 6.5.0
		 * @since 6.6.0 Added the `$locale` parameter.
		 *
		 * @param string $file   Path to the translation file to load.
		 * @param string $domain The text domain.
		 * @param string $locale The locale.
		 */
		$file = (string) apply_filters( 'load_translation_file', $file, $domain, $locale );

		$success = $i18n_controller->load_file( $file, $domain, $locale );

		if ( $success ) {
			if ( isset( $l10n[ $domain ] ) && $l10n[ $domain ] instanceof MO ) {
				$i18n_controller->load_file( $l10n[ $domain ]->get_filename(), $domain, $locale );
			}

			// Unset NOOP_Translations reference in get_translations_for_domain().
			unset( $l10n[ $domain ] );

			$l10n[ $domain ] = new WP_Translations( $i18n_controller, $domain );

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

			return true;
		}
	}

	return false;
}

textdomain (mo po files)

localize (l10n i18n Internationalization localization)

Localization