load_theme_textdomain() │ WP 1.5.0

Load the theme's translated strings.

If the current locale exists as a .mo file in the theme's root directory, it will be included in the translated strings by the $domain.

The .mo files must be named based on the locale exactly.

Uses: load_textdomain()
Used By: load_child_theme_textdomain()
Hooks from the function

Return

true|false. True when textdomain is successfully loaded, false otherwise.

Usage

load_theme_textdomain( $domain, $path );
$domain(string) (required)
Text domain. Unique identifier for retrieving translated strings.
$path(string|false)
Path to the directory containing the .mo file.
Default: false

Examples

0

#1 How to call a function

The function is usually called during after_setup_theme event or you can directly stick it into functions.php theme's file:

add_action( 'after_setup_theme', 'my_theme_setup' );

function my_theme_setup(){
	load_theme_textdomain( 'my_theme', get_template_directory() . '/languages' );
}

First, WP will try to load the translation file from the /wp-content/language/themes - /wp-content/language/themes/my_theme-ru_RU.mo folder.

If there is no suitable mo file there, it will try to load it from the theme folder /wp-content/themes/my_theme/language/ru_RU.mo.

Here my_theme is the specified translation domain, and ru_RU is the current locale.

0

#2 Switching the translation language

This example can be used when you want to switch the language. The variable passed in the URL will be used to switch the language. For example, to switch to Russian, the URL will look like this: www.example.com/?lang=ru_RU. This will find the file ru_RU.mo, in the directory language in the theme directory:

// Changing the localization language
// must be called before calling load_theme_textdomain()
add_filter( 'locale', 'my_theme_localized' );

function my_theme_localized( $locale ){

	if ( ! isset( $_GET['lang'] ) ) {
		return preg_replace( '/[^a-z_]/i', '', $_GET['lang'] );
	}

	return $locale;
}

// Set the translation directory for theme
// translations of the theme should be located in the `.../my_theme/languages/` directory
// WordPress translations should be located in the `.../wp-content/languages` directory
add_action( 'after_setup_theme', 'my_theme_setup');

function my_theme_setup(){
	load_theme_textdomain( 'my_theme', get_template_directory() . '/languages' );
}

Notes

  • Global. WP_Textdomain_Registry. $wp_textdomain_registry WordPress Textdomain Registry.

Changelog

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

load_theme_textdomain() code WP 6.5.2

wp-includes/l10n.php 
function load_theme_textdomain( $domain, $path = false ) {
	/** @var WP_Textdomain_Registry $wp_textdomain_registry */
	global $wp_textdomain_registry;

	/**
	 * Filters a theme's locale.
	 *
	 * @since 3.0.0
	 *
	 * @param string $locale The theme's current locale.
	 * @param string $domain Text domain. Unique identifier for retrieving translated strings.
	 */
	$locale = apply_filters( 'theme_locale', determine_locale(), $domain );

	$mofile = $domain . '-' . $locale . '.mo';

	// Try to load from the languages directory first.
	if ( load_textdomain( $domain, WP_LANG_DIR . '/themes/' . $mofile, $locale ) ) {
		return true;
	}

	if ( ! $path ) {
		$path = get_template_directory();
	}

	$wp_textdomain_registry->set_custom_path( $domain, $path );

	return load_textdomain( $domain, $path . '/' . $locale . '.mo', $locale );
}

textdomain (mo po files)

localize (l10n i18n Internationalization localization)

Localization