load_textdomain()
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:
$l10n[ $domain ] = & $mo;
If the specified domain already exists in the data, the imported localization strings will be merged with the existing ones (combined into a single array).
The translation file must be loaded before it is used. Therefore, load_textdomain() is typically called during the plugins_loaded event.
To translate any string in WordPress, the string must have a translation, and to have it, the translation data must be loaded, among which will be the translation of the required string.
To load translation data, specifically to load the .mo
or .l10n.php
translation file into the global localization data, you can use:
- load_textdomain() - this function.
- load_theme_textdomain() - a wrapper for this function.
- load_child_theme_textdomain() - a wrapper for this function.
- load_plugin_textdomain() - a wrapper for this function.
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 later to reference the translation string.
- $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
#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.
#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. |