unload_textdomain() │ WP 3.0.0

Unloads (removes, cancels) the connected translation file.

Translation files are connected using the function load_textdomain() and its derivatives: load_plugin_textdomain(), load_theme_textdomain().

unload_textdomain() does not delete the file itself, but simply unloads the translation information from the global variable $l10n.

Hooks from the function

Returns

true|false. Boolean: true or false.

Usage

unload_textdomain( $domain );
$domain(string) (required)
The slug (identifier) of the loaded translation file to be unloaded. This slug is specified in the first parameter when connecting the file, in the functions load_textdomain() and its derivatives.
$reloadable(true/false) (WP 6.1)
Whether the translation file can be loaded again.
Default: false

Examples

0

#1 Cancel translation of the plugin

Suppose we have a plugin and it includes a translation file with load_plugin_textdomain('books' ...). And we don't need the translation of this plugin. Then we can disable the translation by unloading the connected translation data.

Translation files are usually connected to the hook plugins_loaded which is triggered before init. So let's use the init hook to disable the previously connected data for translation:

add_action( 'init', 'my_unload_textdomain' );

function my_unload_textdomain(){
	unload_textdomain('books');
}
0

#2 Cancel the translation of WordPress

Let's say we do not need to translate the admin panel, we already know everything and do not want to overload the server. But the translation of plugins we need, so we can not just put the English language in the settings, because then the plugins will be in English.

The solution here is to disable the translation of WordPress in the code. To do this, add following code to the theme functions.php file:

add_action( 'init', 'my_unload_textdomain' );

function my_unload_textdomain(){
	// default - WP translation textdomain
	unload_textdomain( 'default' );

	// twentyfifteen - WP theme translation textdomain
	unload_textdomain( 'twentyfifteen' );
}
0

#3 Prevent a text domain from unloading

Hook override_unload_textdomain:

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

After this code is installed any unload_textdomain( 'my-domain' ) won't work - translation will stay where it was. But the mark of this unloading will be added to global $l10n_unloaded[ $domain ] variable as if it has been unloaded.

Hook unload_textdomain:

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
}

Notes

  • 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.

Changelog

Since 3.0.0 Introduced.
Since 6.1.0 Added the $reloadable parameter.

unload_textdomain() code WP 6.9.1

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

textdomain (mo po files)

localize (l10n i18n Internationalization localization)

Localization