unload_textdomain() │ WP 3.0.0

Выгружает (удаляет, отменяет) подключенный файл перевода.

Файлы перевода подключаются функцией load_textdomain() и производными от нее: load_plugin_textdomain(), load_theme_textdomain().

unload_textdomain() не удаляет сам файл, а просто выгружает информацию для перевода из глобальной переменной $l10n.

Хуки из функции

override_unload_textdomain

unload_textdomain

Возвращает

true|false. Логические: true или false.

Использование

unload_textdomain( $domain );

$domain(строка) (обязательный): Ярлык (идентификатор) загруженного файла перевода, который нужно выгрузить. Этот ярлык указывается в первом параметре при подключении файла, в функциях load_textdomain() и производных от нее.
$reloadable(true/false) (WP 6.1): Можно ли снова загрузить файл перевода.
По умолчанию: false

Примеры

#1 Отменим перевод плагина

Допустим, у нас есть плагин и в нем подключается файл перевода с помощью load_plugin_textdomain('books' ...). А нам не нужен перевод этого плагина. Тогда мы можем отключить перевод, выгрузив подключенные данные перевода.

Файлы перевода обычно подключаются к хуку plugins_loaded который срабатывает раньше чем init. Поэтому воспользуемся хуком init, чтобы отключить ранее подключенные данные для перевода:

add_action('init', 'my_unload_textdomain');
function my_unload_textdomain(){
	unload_textdomain('books');
}

#2 Отменим перевод WordPress

Допустим нам не нужно переводить админку сайта, мы и так там все знаем и не хотим лишний раз нагружать сервер. Но вот перевод плагинов нам нужен, поэтому мы не можем просто поставить английский язык в настройках, ведь тогда и плагины будут на англ.

Выход тут такой, отключить перевод WordPress в коде. Для этого добавим такой код в файл темы functions.php:

add_action('init', 'my_unload_textdomain');
function my_unload_textdomain(){
	// default - ярлык перевода WP
	// twentyfifteen - ярлык перевода темы WP
	unload_textdomain('default');
}

#3 Предотвращение выгрузки текстового домена

Хук override_unload_textdomain:

В случае, если вам нужно предотвратить выгрузку текстового домена, фильтр 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( 'my-domain' ) не сработает - перевод останется на месте. Но отметка о этой выгрузке будет добавлена в глобальную $l10n_unloaded[ $domain ] переменную, как будто он был выгружен.

Хук unload_textdomain:

Непосредственно перед выгрузкой текстового домена вызывается действие unload_textdomain, чтобы уведомить WordPress о том, что текстовый домен выгружается.

add_action( 'unload_textdomain', 'myplugin_unload_textdomain' );

function myplugin_unload_textdomain( $domain ) {
	// добавьте код здесь для обработки выгрузки текстового домена
}

Заметки

Global. MO[]. $l10n An array of all currently loaded text domains.
Global. MO[]. $l10n_unloaded An array of all text domains that have been unloaded again.

Список изменений

С версии 3.0.0	Введена.
С версии 6.1.0	Added the `$reloadable` parameter.

Код `unload_textdomain() unload textdomain` ^{WP 6.9}

wp-includes/l10n.php

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