FAQ: Why don't translations load from the custom folder?

Loco Translate offers a safe location for storing custom translation files. "Safe" in the sense that WordPress updates shouldn't delete or replace any files that you've saved there.

Important: WordPress 6.7 introduced a major problem for loading custom translation files when a part of your site has tried to use translations too early. If upgrading your site has suddenly broken your translations, this is almost certainly your problem. See the section below about early loading.

If WordPress isn't loading translations from this location, take the following steps to debug the problem.

1. Ensure Loco Translate is enabled

That's an easy one. The plugin must be installed and enabled for its custom location to work. If you don't want to enable it, you'll have to write your own code to load translations from non-standard locations.

Tip: Loco Translate 2.6.14 has improved custom file loading, if you have at least v6.6 of WordPress.

2. Check files are readable by PHP

Your custom files may exist, but they also need to be readable by the PHP process.

They're only likely to be unreadable if you uploaded or copied them manually, but if you recently migrated or restored a whole website then it's certainly a possibility. If you're not familiar with file system permissions, ask someone who is.

3. Check the standard locations

The next thing to do is check whether the same translations can be loaded from standard WordPress locations. For example: if the following custom path doesn't work:

wp-content/languages/loco/plugins/{domain}-{locale}.*

Move this file to the following (system) path and try again:

wp-content/languages/plugins/{domain}-{locale}.*

Tip: Use Loco Translate's "Relocate" function to move all dependent files together. Moving just the .mo file may not work.

wp-content/languages/plugins is the standard (unsafe) WordPress location for plugins. If it doesn't work either then you may have a problem unrelated to Loco Translate's file loader. (See Translations not showing instead). If this location does work, then proceed to check for the early loading problem...

4. Check if translations are requested too early

Authors should not attempt to use any translations until all plugins have initialized. If they do, they prevent other plugins (such as Loco Translate) from modifying the standard loading process. Loco Translate can't load your files if it's not running.

Tip: Since WordPress 6.7, the early loading problem raises a PHP notice. Check your error logs for a notice that reads: "Translation loading for the <code>foo</code> domain was triggered too early." See related FAQ.

You need WP_DEBUG enabled to see this notice. If you find it in your logs, note which text domain it comes from ("foo" in our example). Usually this will be the name of the theme or plugin, but you may have to dig into your plugins if you don't recognize it. Contact the developer and politely tell them your site relies on filters that they've invoked too soon.

Mostly likely the developers test their localizations with translations installed only in standard WordPress locations. That's to be expected, but they won't be aware of the problem unless you let them know.

Another change in WordPress 6.7 means that calling load_plugin_textdomain (or load_theme_textdomain) does nothing if the domain is already loaded. It doesn't check to see if it needs reloading from a different location. Hopefully WordPress 6.7.1 will include a fix of some kind, but actually the problem will still exist in your site and should be addressed properly.

Dead end?

If you've got this far, then the problem may be highly specific to your setup. Feel free to post your issue on the support forum, but please provide sufficient detail so we can reproduce it.

If you're permanently unable to use the custom folder, the only remaining solution is to protect files in the standard ("system") location and edit those instead. Disabling translation updates should make the files safe, see FAQ on disappearing files.