override_load_textdomain │ filter-hook │ WP 2.9.0

Allows you to override loading the translation .mo file for a specified text domain.

This filter lets developers completely replace the standard translation loading procedure. If the filter returns true, WordPress does not load the translation file itself and assumes that it has already been loaded.

The filter is useful for custom translation loading logic, such as using cached versions of translation files or completely preventing translations from loading for particular domains.

Usage

add_filter( 'override_load_textdomain', 'wp_kama_override_load_textdomain_filter', 10, 4 );

/**
 * Function for `override_load_textdomain` filter-hook.
 * 
 * @param bool        $override Whether to override the .mo file loading.
 * @param string      $domain   Text domain. Unique identifier for retrieving translated strings.
 * @param string      $mofile   Path to the MO file.
 * @param string|null $locale   Locale.
 *
 * @return bool
 */
function wp_kama_override_load_textdomain_filter( $override, $domain, $mofile, $locale ){
	// filter...
	return $override;
}

$override(bool)

Whether to override loading the .mo file.
Default: false

$domain(string)

Text domain for which the translation is being loaded.

$mofile(string)

Full path to the .mo file.

$locale(string|null)

Locale for which the translation is being loaded. Added in version 6.2.0.

Examples

#1 Load a custom .mo file from an alternative path

Replace the standard .mo file path with a custom one:

add_filter( 'override_load_textdomain', 'load_custom_mo_file', 10, 4 );

function load_custom_mo_file( $override, $domain, $mofile, $locale ) {
	if ( 'my-plugin' === $domain ) {
		$custom_mofile = WP_CONTENT_DIR . "/custom-languages/{$domain}-{$locale}.mo";

		if ( file_exists( $custom_mofile ) ) {
			load_textdomain( $domain, $custom_mofile );

			return true;
		}
	}

	return $override;
}

#2 Use cached translations to improve performance

Load translations from the cache when they are available:

add_filter( 'override_load_textdomain', 'load_cached_translations', 10, 4 );

function load_cached_translations( $override, $domain, $mofile, $locale ) {
	$cache_key = "translations_{$domain}_{$locale}";
	$cached_translations = get_transient( $cache_key );

	if ( false !== $cached_translations ) {
		$mo = new MO();
		$mo->import_from_reader( new POMO_StringReader( $cached_translations ) );
		$GLOBALS['l10n'][ $domain ] = & $mo;

		return true;
	}

	return $override;
}

This example assumes that the translations were previously stored in the cache with set_transient().

#3 Disable translation loading for particular domains

This example completely disables translation loading for the specified domains:

add_filter( 'override_load_textdomain', 'disable_translations_for_domains', 10, 4 );
function disable_translations_for_domains( $override, $domain, $mofile, $locale ) {
	$disabled_domains = [ 'my-plugin', 'my-theme' ];

	if ( in_array( $domain, $disabled_domains, true ) ) {
		return true;
	}

	return $override;
}