load_theme_textdomain() │ WP 1.5.0

Loads the theme translation file (.mo) into memory for further processing.

The .mo file must be located in the root directory of the theme and have the name LOCALE.mo, for example: ru_RU.mo.

Since version 4.6, the function first attempts to load the .mo file DOMAIN_TRANSLATION-LOCALE.mo from the folder /wp-content/language/themes. An example of such a file name: twentyeleven-ru_RU.mo.

The function should be called during the hook after_setup_theme.

To load the plugin translation, use load_plugin_textdomain().

Internationalization (i18n) and localization (l10n) means adapting computer programs to different languages.

  • l10n is an abbreviation for localization.
  • i18n is an abbreviation for internationalization. 18 is the number of letters between the initial i and the final n.
Uses: load_textdomain()
Used By: load_child_theme_textdomain()

No Hooks.

Returns

true|false. Boolean. true - if the translation file was loaded, false - if it failed to load.

Usage

load_theme_textdomain( $domain, $path );
$domain(string) (required)
A unique identifier that can later be referred to in translation functions: __(), _e() specifically for this translation string.
$path(string)
The path to the directory where the .mo file is located (without a trailing slash). By default, the path to the theme directory is specified: get_template_directory().
Default: false

Examples

0

#1 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' );
}
-1

#2 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.

Notes

  • Global. WP_Textdomain_Registry. $wp_textdomain_registry WordPress Textdomain Registry.
  • Global. Array<String,. WP_Translations|NOOP_Translations> $l10n An array of all currently loaded text domains.

Changelog

Since 1.5.0 Introduced.
Since 4.6.0 The function now tries to load the .mo file from the languages directory first.
Since 6.7.0 Translations are no longer immediately loaded, but handed off to the just-in-time loading mechanism.

load_theme_textdomain() code WP 6.8.3

wp-includes/l10n.php 
function load_theme_textdomain( $domain, $path = false ) {
	/** @var WP_Textdomain_Registry $wp_textdomain_registry */
	/** @var array<string, WP_Translations|NOOP_Translations> $l10n */
	global $wp_textdomain_registry, $l10n;

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

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

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

	// If just-in-time loading was triggered before, reset the entry so it can be tried again.
	if ( isset( $l10n[ $domain ] ) && $l10n[ $domain ] instanceof NOOP_Translations ) {
		unset( $l10n[ $domain ] );
	}

	return true;
}

textdomain (mo po files)

localize (l10n i18n Internationalization localization)

Localization