BugWP logo BugWP
Back to Community
Home / Community / Plugin → Loco translate

Why Your Loco Translate Custom Translations Aren't Working: A Troubleshooting Guide

37 threads Sep 16, 2025 Plugin → Loco translate

Content

If you've used Loco Translate to create custom translation files only to find that WordPress isn't loading them, you're not alone. This is one of the most common issues users encounter. This guide will explain why this happens and walk you through the most effective solutions.

The Core Problem: WordPress's Translation Loading Order

WordPress loads translation files in a specific hierarchy. It prioritizes files in certain locations, and if it finds a translation in a higher-priority location, it will use that and ignore your custom file. This is often the root cause of the issue.

The typical loading order is:

  1. WordPress.org Language Packs (if the theme/plugin is from the official directory)
  2. System folder (wp-content/languages/)
  3. Custom folder (wp-content/languages/loco/)
  4. Author folder (inside the theme/plugin's own /languages/ directory)

As you can see, your custom files in the 'Author' location have the lowest priority. If an update adds a community translation to the System folder or a language pack is installed, it will override your work.

Common Scenarios and Their Solutions

1. Theme or Plugin Update Overwrote Your Files

Why it happens: You saved your .po and .mo files in the theme or plugin's own /languages/ folder (the "Author" location). When the software updated, it deleted that entire folder and replaced it with a new one, wiping out your translations.

The solution: Never save translations in the Author location for this exact reason. Always use the "Custom" location (wp-content/languages/loco/). This folder is safe from updates. If your files were lost, you may need to re-create them in the Custom location.

2. A Community Translation is Overriding Yours

Why it happens: WordPress automatically downloads language packs for themes and plugins from WordPress.org. These packs are saved in the System folder (wp-content/languages/plugins/ or wp-content/languages/themes/), which has a higher priority than your Custom folder.

The solution: You have two options:

  • Option A (Recommended): Keep your translations in the Custom folder. The System translations will load first for any strings they contain, and your Custom files will fill in the gaps for any missing or different translations. This is the intended behavior.
  • Option B: If you must have complete control and want to disable the community translation entirely, you can delete the corresponding .po and .mo files from the System folder. Be aware they may be re-downloaded by WordPress in the future.

3. The "Sync" Function Isn't Finding New Strings

Why it happens: The Sync operation compares your translation file against a Template file (.pot). If your template is missing the new strings from your source code, Sync has nothing to compare against.

The solution: Ensure your bundle is configured with the correct Template file. You may need to re-generate the .pot template from your source code to pull in all the newest strings before running Sync on your translation file.

4. Translations Using _x() Aren't Appearing

Why it happens: The _x() function includes a "context" parameter. In your .po file, these strings will have a special context field. If the context in the code doesn't perfectly match the context in the translation file, the translation will not be used.

The solution: In the Loco Translate editor, make sure you are viewing and translating the correct contextualized string. It will appear differently from a standard string without context.

Final Checklist

  • ✅ Are your custom translation files saved in the Custom location (wp-content/languages/loco/)?
  • ✅ Have you checked the System folder for conflicting language packs?
  • ✅ Have you regenerated your POT template and synced your PO file after adding new strings to your code?
  • ✅ Are you correctly translating contextualized strings (with _x())?

Understanding WordPress's translation hierarchy is the key to resolving most issues with Loco Translate. By saving your files in the correct, safe location and knowing what might override them, you can take full control of your website's translations.

Related Support Threads Support