Using WordPress ‘pre_load_script_translations’ PHP filter

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

On this pageJump to a section

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.