云策 WordPress 开发者社区

函数文档

unload_textdomain()

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

概述

unload_textdomain() 函数用于卸载指定文本域的翻译数据，支持通过参数控制是否可重新加载，并提供了相关的 Hook 供开发者干预卸载过程。

关键要点

  • 函数接受两个参数：$domain（必需，文本域标识符）和 $reloadable（可选，布尔值，默认为 false，表示是否可即时重新加载）。
  • 返回布尔值，指示文本域是否成功卸载。
  • 内部使用全局变量 $l10n 和 $l10n_unloaded 管理翻译状态，并调用 WP_Translation_Controller 进行卸载操作。
  • 提供了两个 Hook：apply_filters('override_unload_textdomain', ...) 用于覆盖卸载行为，do_action('unload_textdomain', ...) 在卸载前触发。
  • 从 WordPress 6.1.0 版本开始引入了 $reloadable 参数，增强了灵活性。

代码示例

// 示例：使用 override_unload_textdomain 过滤器阻止特定文本域卸载
add_filter( 'override_unload_textdomain', 'myplugin_override_unload_textdomain' );
function myplugin_override_unload_textdomain( $override, $domain ) {
    if ( $domain === 'my-domain' ) {
        // 阻止 WordPress 卸载此文本域
        $override = true;
    }
    return $override;
}

// 示例：使用 unload_textdomain 动作在卸载前执行自定义代码
add_action( 'unload_textdomain', 'myplugin_unload_textdomain' );
function myplugin_unload_textdomain( $domain ) {
    // 在此添加处理文本域卸载的代码
}

注意事项

  • 当 $reloadable 为 true 时，文本域不会实际卸载，以支持多语言环境下的即时重新加载。
  • 如果文本域是 NOOP_Translations 实例，卸载操作会返回 false 并移除相关条目。
  • 开发者应谨慎使用 override_unload_textdomain 过滤器，以避免影响其他插件或核心功能。
📄 原文内容

Unloads translations for a text domain.

Parameters

$domainstringrequired
Text domain. Unique identifier for retrieving translated strings.
$reloadablebooloptional
Whether the text domain can be loaded just-in-time again.

Default:false

Return

bool Whether textdomain was unloaded.

Source

function unload_textdomain( $domain, $reloadable = false ) {
	global $l10n, $l10n_unloaded;

	$l10n_unloaded = (array) $l10n_unloaded;

	/**
	 * Filters whether to override the text domain unloading.
	 *
	 * @since 3.0.0
	 * @since 6.1.0 Added the `$reloadable` parameter.
	 *
	 * @param bool   $override   Whether to override the text domain unloading. Default false.
	 * @param string $domain     Text domain. Unique identifier for retrieving translated strings.
	 * @param bool   $reloadable Whether the text domain can be loaded just-in-time again.
	 */
	$plugin_override = apply_filters( 'override_unload_textdomain', false, $domain, $reloadable );

	if ( $plugin_override ) {
		if ( ! $reloadable ) {
			$l10n_unloaded[ $domain ] = true;
		}

		return true;
	}

	/**
	 * Fires before the text domain is unloaded.
	 *
	 * @since 3.0.0
	 * @since 6.1.0 Added the `$reloadable` parameter.
	 *
	 * @param string $domain     Text domain. Unique identifier for retrieving translated strings.
	 * @param bool   $reloadable Whether the text domain can be loaded just-in-time again.
	 */
	do_action( 'unload_textdomain', $domain, $reloadable );

	// Since multiple locales are supported, reloadable text domains don't actually need to be unloaded.
	if ( ! $reloadable ) {
		WP_Translation_Controller::get_instance()->unload_textdomain( $domain );
	}

	if ( isset( $l10n[ $domain ] ) ) {
		if ( $l10n[ $domain ] instanceof NOOP_Translations ) {
			unset( $l10n[ $domain ] );

			return false;
		}

		unset( $l10n[ $domain ] );

		if ( ! $reloadable ) {
			$l10n_unloaded[ $domain ] = true;
		}

		return true;
	}

	return false;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘override_unload_textdomain’, bool $override, string $domain, bool $reloadable )

Filters whether to override the text domain unloading.

do_action( ‘unload_textdomain’, string $domain, bool $reloadable )

Fires before the text domain is unloaded.

Uses Description
WP_Translation_Controller::get_instance()wp-includes/l10n/class-wp-translation-controller.php

Utility method to retrieve the main instance of the class.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.

Show 1 moreShow less

Used by Description
WP_Locale_Switcher::load_translations()wp-includes/class-wp-locale-switcher.php

Load translations for a given locale.
load_default_textdomain()wp-includes/l10n.php

Loads default translated strings based on locale.
wp_timezone_choice()wp-includes/functions.php

Gives a nicely-formatted list of timezone strings.

Changelog

Version Description
6.1.0 Added the $reloadable parameter.
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 2 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

    In case you need to prevent a text domain from unloading, the override_unload_textdomain filter is called before attempting to unload the text domain.

    add_filter( 'override_unload_textdomain', 'myplugin_override_unload_textdomain' );
function myplugin_override_unload_textdomain( $override, $domain ) {
	if ( $domain === 'my-domain' ) {
		// Prevents WordPress from unloading this text domain
		$override = true;
	}
	return $override;
}

    Immediately before unloading a text domain, the unload_textdomain action is called to notify WordPress that the text domain is being unloaded.

    add_action( 'unload_textdomain', 'myplugin_unload_textdomain' );
function myplugin_unload_textdomain( $domain ) {
	// add code here to handle the unloading the text domain
}