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 should not delete or replace any files that you've saved there.

If WordPress is not loading translations from this location, take the following steps to debug the problem.

Ensure Loco Translate is enabled

That's an easy one. The plugin must be installed and enabled for its custom location to work.

Check the standard locations

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

wp-content/languages/loco/themes/{domain}-{locale}.mo

Move this file to the following path and try again:

wp-content/languages/themes/{domain}-{locale}.mo

This is the standard (unsafe) WordPress location. If it doesn't work either then this FAQ is probably not the one you want. (See Translations not showing instead). If this location works, then the problem may be in the theme/plugin that loads the file.

Check the loading functions

Themes and plugins should ideally load their translation files using the correct WordPress functions. That means load_theme_textdomain for themes, and load_plugin_textdomain for plugins.

Some authors may call load_textdomain directly, but this may be an attempt to circumvent the standard loading process and their code should be examined more closely.

If the bundle author is trying to load translations without first calling one of these functions then Loco Translate will not be able to override loaded translations with your custom file. If you're not a developer, check with the author whether they use these standard functions, or if they rely on automatic text domain loading (described later in this page).

Check if translations are loaded too early

Even if the bundle calls the correct loading functions, it's not uncommon for authors to run their code too early. Authors should not load translations until all plugins have initialized. If they do, they prevent other plugins (such as Loco Translate) from modifying the standard loading process.

If you're familiar with WordPress hooks then check at what point the author's code starts to load its translation files. If it does so as soon as the file is included then this is probably the root of the problem.

Check for automatic text domain loading

If the bundle author is not calling one of the loading functions described earlier then WordPress will fall back to automatic (or "just in time") text domain loading. This also happens when a theme or plugin tries to use its translations before it's loaded them.

Loco Translate can still load your custom files in this situation, but only if the corresponding system translations are installed in the standard location. So try adding a "system" translation file for the same text domain and see if that fixes your problem. Loco Translate will ensure that your custom translations override, but if you're concerned about performance then you can leave the system file empty (i.e. 0% translated).

Dead end?

If you're 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.