Back to Community
Home / Community / Plugin → Loco translate

Troubleshooting JavaScript Translation Issues in Loco Translate

25 threads Sep 9, 2025 Plugin → Loco translate

Content

Translating JavaScript strings in WordPress plugins and themes is a common task, but it can sometimes lead to confusion when translations don't appear on the frontend. This guide will help you diagnose and resolve the most frequent issues related to JavaScript translation files in Loco Translate.

Why JavaScript Translations Are Different

Unlike PHP strings, which are translated using .po and .mo files, JavaScript strings require an additional step. WordPress uses a system of JSON-based translation files that are loaded via the wp_set_script_translations() function. Loco Translate can generate these .json files, but several factors can prevent them from working correctly.

Common Problems and Their Solutions

1. JSON Files Are Not Generated or Have the Wrong Name

Symptoms: Your PHP translations work, but JavaScript strings remain in the original language. You might not see any .json files in your language folder, or their names might not match what WordPress expects.

Why it happens: The naming convention for JSON files is strict. WordPress expects a filename in the format {text-domain}-{locale}-{md5}.json. However, Loco Translate generates the filename based on the source .po file's name. If your theme or plugin follows the old convention of not including the text domain in the .po filename, the generated .json file will also be missing it, causing a mismatch.

Solution: Manually check the name of the generated .json file. If it is missing the text domain (e.g., de_DE-md5.json), you may need to rename it to include the domain (e.g., mytextdomain-de_DE-md5.json).

2. The MD5 Hash in the Filename Is Incorrect

Symptoms: JSON files are present but are not being loaded by WordPress.

Why it happens: The MD5 hash in the filename is generated from the path to the source JavaScript file. If your development workflow uses a build process (e.g., Webpack) that changes the file path from source to production, the hash generated by Loco Translate (based on the source path) will differ from the hash WordPress calculates (based on the production path).

Solution: This is a known limitation. The Loco Translate team has acknowledged that the plugin uses file references from the .po file to generate the hash, and if those paths are wrong, the resulting hash will be too. You may need to manually rename the .json files to match the hash WordPress expects or adjust your build process so the source paths match the production paths.

3. File Extraction Settings Are Misconfigured

Symptoms: Strings from your .js files are not being found during the sync process.

Why it happens: By default, Loco Translate may not scan all JavaScript file types, or it may be scanning unnecessary directories like node_modules, which can slow the process down immensely.

Solution:

  • Ensure you have enabled JavaScript scanning in Loco Translate → Settings → File Extensions.
  • If you use custom file extensions for JavaScript (like .tag), add them to the "Scan JavaScript files with extensions" setting. Note: A user-reported workaround suggests there may be a hardcoded check for .js files in the plugin's code, so this may not work perfectly for all custom extensions.
  • To prevent slow scans, add node_modules to your bundle's excluded paths in the Advanced configuration tab.

4. The JSON File Is Not Being Loaded by WordPress

Symptoms: Everything seems correct, but translations still don't load.

Why it happens: The issue might not be with the file itself but with how it's being enqueued in WordPress.

Solution: Triple-check your script enqueueing code. You must:

  1. Set wp-i18n as a dependency for your script.
  2. Call wp_set_script_translations() with the correct script handle, text domain, and path.
  3. Use the correct i18n functions in your JavaScript code (e.g., __() from @wordpress/i18n).
You can use your browser's developer tools to check the Network tab and see if WordPress is attempting to load the JSON file and if the request is successful.

Conclusion

JavaScript translation issues often boil down to a mismatch between what Loco Translate generates and what WordPress expects to find. The most reliable approach is to methodically check the JSON filename, its MD5 hash, and your WordPress enqueue logic. While some workarounds involve manual file renaming, understanding the root cause is the key to a lasting solution.

Related Support Threads Support