Using WordPress ‘pre_load_script_translations’ PHP filter

by

The ‘pre_load_script_translations’ WordPress PHP filter allows you to modify the translations of scripts before they are loaded.

This filter is called before the translations are loaded, which means you can modify the translations before they are used by the scripts.

Returning a non-null value allows to override the default logic, effectively short-circuiting the function.

Usage

function my_custom_pre_load_script_translations( $translations, $file, $handle, $domain ) {
    // Your custom logic here
    return $translations;
}
add_filter( 'pre_load_script_translations', 'my_custom_pre_load_script_translations', 10, 4 );

Parameters

  • $translations (string|false|null) – JSON-encoded translation data. Default null.
  • $file (string|false) – Path to the translation file to load. False if there isn’t one.
  • $handle (string) – Name of the script to register a translation domain to.
  • $domain (string) – The text domain.

Examples

Load custom translations Load custom translations for a specific script and text domain.

function load_custom_translations( $translations, $file, $handle, $domain ) {
    if ( 'my-script' === $handle && 'my-text-domain' === $domain ) {
        $translations = json_encode( array( 'key' => 'translated value' ) );
    }
    return $translations;
}
add_filter( 'pre_load_script_translations', 'load_custom_translations', 10, 4 );

This code checks if the script handle is ‘my-script’ and the text domain is ‘my-text-domain’. If so, it sets custom translations by encoding an array of key-value pairs into a JSON string.

Skip translations for a specific script

Prevent translations from being loaded for a specific script.

function skip_script_translations( $translations, $file, $handle, $domain ) {
    if ( 'skip-this-script' === $handle ) {
        return false;
    }
    return $translations;
}
add_filter( 'pre_load_script_translations', 'skip_script_translations', 10, 4 );

This code checks if the script handle is ‘skip-this-script’. If so, it returns false to prevent translations from being loaded.

Load translations from a different file

Load translations from a different file for a specific script and text domain.

Code example:

function load_alternative_translations( $translations, $file, $handle, $domain ) {
    if ( 'my-script' === $handle && 'my-text-domain' === $domain ) {
        $file = '/path/to/alternative/translations.mo';
        $translations = load_textdomain( $domain, $file );
    }
    return $translations;
}
add_filter( 'pre_load_script_translations', 'load_alternative_translations', 10, 4 );

This code checks if the script handle is ‘my-script’ and the text domain is ‘my-text-domain’. If so, it sets a new file path for the translations and loads them using load_textdomain().

Fallback translations for a missing file

Load fallback translations when the translation file is missing.

Code example:

function load_fallback_translations( $translations, $file, $handle, $domain ) {
    if ( false === $file ) {
        $translations = json_encode( array( 'fallback_key' => 'fallback value' ) );
    }
    return $translations;
}
add_filter( 'pre_load_script_translations', 'load_fallback_translations', 10, 4 );

This code checks if the translation file is missing (when $file is false). If so, it sets fallback translations by encoding an array of key-value pairs into a JSON string.

Modify translations

Modify the translations before they are loaded.

Code example:

function modify_script_translations( $translations, $file, $handle, $domain ) {
if ( 'my-script' === $handle && 'my-text-domain' === $domain ) {
$decoded_translations = json_decode( $translations, true );
$decoded_translations['key'] = 'modified value';
$translations = json_encode( $decoded_translations );
}
return $translations;
}
add_filter( 'pre_load_script_translations', 'modify_script_translations', 10, 4 );

This code checks if the script handle is ‘my-script’ and the text domain is ‘my-text-domain’. If so, it decodes the existing translations, modifies a specific translation key’s value, and re-encodes the modified translations back to a JSON string.