load_theme_textdomain( string $domain, string|false $path = false ): bool

Loads the theme’s translated strings.

Contents

Description

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.

Top ↑

Parameters

$domain string Required
Text domain. Unique identifier for retrieving translated strings.
$path string|false Optional
Path to the directory containing the .mo file.

Default: false

Top ↑

Return

bool True when textdomain is successfully loaded, false otherwise.

Top ↑

Source

File: wp-includes/l10n.php. View all references 

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

View on Trac View on GitHub

Top ↑

Hooks

Top ↑

Top ↑

Uses

Uses
Uses Description
WP_Textdomain_Registry::set_custom_path() wp-includes/class-wp-textdomain-registry.php

Sets the custom path to the plugin’s/theme’s languages directory.
determine_locale() wp-includes/l10n.php

Determines the current locale desired for the request.
get_template_directory() wp-includes/theme.php

Retrieves template directory path for the active theme.
load_textdomain() wp-includes/l10n.php

Loads a .mo file into the text domain $domain.
apply_filters() wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
Show 1 more use Hide more uses

Top ↑

Changelog

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

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 9You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    1st example
    The load_theme_textdomain() function should generally be called from within the after_setup_theme action hook.

    add_action('after_setup_theme', 'wpdocs_theme_setup');

/**
 * Load translations for wpdocs_theme
 */
function wpdocs_theme_setup(){
    load_theme_textdomain('wpdocs_theme', get_template_directory() . '/languages');
}

    The .mo files must use language-only filenames, like languages/de_DE.mo in your theme directory.

    Unlike plugin language files, a name like my_theme-de_DE.mo will NOT work. Although plugin language files allow you to specify the text-domain in the filename, this will NOT work with themes. Language files for themes should include the language shortcut ONLY.

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    2nd example
    you can use this example if you wish to switch theme language using a variable passed within the URL, for example to load the Tamazikht language, your URL would look like; www.example.com/?l=tz_MA, this will search for a .mo file with name tz_MA.mo in the language directory inside your theme.

    // CHANGE LOCAL LANGUAGE
// must be called before load_theme_textdomain()

add_filter( 'locale', 'wpdocs_theme_localized' );

/**
 * Switch to locale given as query parameter l, if present
 */
function wpdocs_theme_localized( $locale )
{
	if ( isset( $_GET['l'] ) )
	{
		return sanitize_key( $_GET['l'] );
	}

	return $locale;
}

// SET THEME LANGUAGES DIRECTORY
// Theme translations can be filed in the my_theme/languages/ directory
// Wordpress translations can be filed in the wp-content/languages/ directory
load_theme_textdomain( 'wpdocs_theme_textdomain', get_template_directory().'/languages' );

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