云策 WordPress 开发者社区

函数文档

load_theme_textdomain()

查看官方原文 ↗
💡 云策文档标注

概述

load_theme_textdomain() 函数用于加载主题的翻译字符串，通过指定文本域和路径来包含对应的 .mo 文件。它支持自定义路径设置，并整合了即时加载机制以提高效率。

关键要点

  • 函数加载主题的翻译字符串，基于当前区域设置从指定路径查找 .mo 文件。
  • 参数 $domain 是必需的文本域标识符，$path 可选，默认为主题根目录。
  • 返回布尔值：成功加载返回 true，否则返回 false。
  • 从 WordPress 6.7 开始，翻译改为即时加载机制，需在 init 或之后调用。
  • 主题的 .mo 文件必须仅以语言代码命名（如 de_DE.mo），不支持包含文本域的文件名。

代码示例

add_action('after_setup_theme', 'wpdocs_theme_setup');

function wpdocs_theme_setup(){
    load_theme_textdomain('wpdocs_theme', get_template_directory() . '/languages');
}

注意事项

  • 建议在 after_setup_theme 钩子中调用 load_theme_textdomain() 以确保正确加载。
  • 主题语言文件应放置在 languages 目录下，文件名仅包含语言代码，如 de_DE.mo。
  • 从 WordPress 6.7 起，此函数需在 init 或之后调用，以适配即时加载机制。
📄 原文内容

Loads the theme’s translated strings.

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.

Parameters

$domainstringrequired
Text domain. Unique identifier for retrieving translated strings.
$pathstring|falseoptional
Path to the directory containing the .mo file.

Default:false

Return

bool True when textdomain is successfully loaded, false otherwise.

Source

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

View all references View on Trac View on GitHub

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.
get_template_directory()wp-includes/theme.php

Retrieves template directory path for the active theme.
Used by Description
load_child_theme_textdomain()wp-includes/l10n.php

Loads the child theme’s translated strings.
WP_Theme::load_textdomain()wp-includes/class-wp-theme.php

Loads the theme’s textdomain.

Changelog

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

User Contributed Notes

  1. Skip to note 4 content


    Codex


    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

    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.

  3. Skip to note 6 content


    Codex


    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

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