FAQ: Why do my script translations not get loaded from JSON files

See general information on JSON support in Loco Translate before reading this.

When a plugin or theme loads script translations it derives the name of a .json file from the .js file which uses them. Loco Translate must match these names exactly when it compiles JSON translation files. Any difference in these two names is a likely point of failure.

How can it go wrong?

Suppose a plugin (called "my-plugin") loads a JavaScript file using some code like this that points to the script's URL:

wp_enqueue_script( 'my-script', plugins_url('scripts/example.min.js', __FILE__) );

WordPress later removes the .min and hashes the file path to produce a JSON file called (for example) my-plugin-fr_FR-72e8c5e24e35642471d54763afbb6a54.json

As per our example on the earlier page Loco Translate must produce the exact same file path by finding references to "scripts/example.js" in the PO file against each string that the script uses. This is very error prone and things can go wrong on both sides.

1. If the file reference in the PO file is wrong, script translation will fail.
2. If the path used in the PHP code is wrong, script translation will fail.

1. Loco Translate is generating the wrong .json file name

This is possible. Check the PO file and look for the file references against the relevant strings. Switch the editor into "code" mode will show clickable file references above the source text. You can see from here if it references files that don't exist, or are somehow different.

Note in our example that a .min.js file is loaded, but just .js is used to compute the hash. This is correct but is the only path normalization that WordPress will perform. Likewise, it is the only normalization that Loco Translate will perform.

However, neither WordPress nor Loco Translate could arrive at scripts/example.js if the deployed script was compiled from files such as sources/widget/component.js, so ensure that such source references are not appearing in your PO files. This is likely a problem with string extraction, so contact the person who originally generated these references.

2. The script file loads but the path is wrong

Less likely, but it happens. Even if the .js file is loaded successfully this doesn't mean the path isn't "wrong".

For example: foo/bar.js and foo/baz/../bar.js point to the same file and your browser will load either of them, but they are not the same and will produce different JSON file names under the WordPress system. The simplest way to fix this would be to contact the author of the code that calls wp_enqueue_script and convince them it's a bug. Otherwise you're looking a regenerating PO files with matching references or writing a filter to modify them.