apply_filters( ‘load_script_textdomain_relative_path’, string|false $relative, string $src, bool $is_module )

User Contributed Notes

1. Skip to note 2 content

   Rodrigo Vieira Eufrasio da Silva 4 weeks ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

   This filter exists to solve one specific problem: script translations silently breaking when the script’s src is served from a different host than your WordPress install — most commonly a CDN subdomain (e.g. https://cdn.example.com/my-plugin/build/index.js instead of https://example.com/wp-content/plugins/my-plugin/build/index.js).

   Looking at _load_script_textdomain_from_src() (which fires this filter), $relative is computed by comparing the script’s host/path against content_url(), plugins_url(), and site_url() in turn. If none of those hosts match — which happens whenever assets are proxied or served from a CDN with its own domain — $relative is left as false, and translations for that script silently fail to load (no error, the script just renders untranslated).

   This filter runs right before that failure would happen, letting you supply the correct relative path yourself:

   add_filter( 'load_script_textdomain_relative_path', function ( $relative, $src, $is_module ) {
       // Only handle scripts actually served from our CDN.
       if ( ! str_starts_with( $src, 'https://cdn.example.com/my-plugin/' ) ) {
           return $relative;
       }
   
       // Rebuild the relative path as if it were served from the plugin's
       // real location (relative to WP_LANG_DIR/plugins/my-plugin/).
       return str_replace( 'https://cdn.example.com/my-plugin/', '', $src );
   }, 10, 3 );

   A few things worth knowing:
   – $relative must end up being a string for translations to load at all — returning false (or anything non-string) means “give up”, which is also useful if you want to explicitly disable translation lookup for specific external scripts instead of triggering warnings.
   – The $is_module parameter (added in WP 7.0) lets you apply different rewriting logic for script modules (registered via wp_register_script_module()) vs classic scripts, since both share this same resolution function.
   – The final filename is built as md5($relative) + '.json' — so $relative doesn’t need to be a real filesystem path, it just needs to be a STABLE, predictable string that you use consistently when naming your .json translation files (via wp i18n make-json).