A plugin appears fully translated in its PO file, yet one WordPress site still shows an English label while another site on the same server shows German. The files exist, but the failing request uses a different locale and loads another text domain before the custom catalog is available.
Start with one untranslated message and follow the complete runtime lookup: source text, context, domain, locale, catalog filename, directory, and load time. That evidence shows whether the problem is a missing translation, a stale build, a naming mismatch, or a separate JavaScript catalog.
What it means
A plugin translation appears only when WordPress requests a message with the same source string, context, text domain, locale, and plural form found in a loaded catalog. The compiled file must also use the expected name and location.
PHP gettext strings normally come from MO files. JavaScript translations may require domain-specific JSON catalogs registered for the relevant script. A translated entry in a PO editor therefore proves neither that the runtime artifact was rebuilt nor that WordPress loaded it.
A realistic WordPress example
A plugin label is translated in the German PO file and appears correctly on the public site. The same label remains English in the administrator area for one user. That account has a different user locale, and the plugin package does not contain the matching catalog for that locale.
Instead of recompiling the existing German file, the team captures the exact source message and request locale, confirms the plugin text domain, and checks the candidate language directories. A separate JavaScript label is traced to its JSON catalog rather than treated as an MO problem.
Why it matters and when to use it
Use this method when a plugin translation is missing, stale, or inconsistent between the front end, administrator screens, users, or sites. A single-message trace prevents broad file replacements that happen to change one view while leaving the real mismatch unresolved.
Rebuild a catalog only when its source and runtime artifact demonstrably disagree. If the plugin changed the original source string, update the translation from an authoritative template or translator decision; do not invent a close-looking entry and expect gettext to match it.
A straightforward route for beginners
- Copy the exact untranslated text and note the page, screen, plugin version, current user, and active locale.
- Confirm the source string, context, plural form, and text domain in the current plugin code.
- Check whether the message is rendered by PHP or JavaScript.
- List the standard plugin, global language, custom, and vendor-managed paths that can supply the catalog.
- Compare filenames, timestamps, hashes, and update ownership before changing a file.
- After the repair, test the exact message and an unaffected translation in a fresh front-end or administrator request.
The advanced route
Build a lookup trace for one missing PHP message and one missing JavaScript message. Record the source text, context, domain, locale, generated filename, candidate directories, selected catalog, and the point at which the plugin registers translations.
- Compare the site locale with the current user locale because administrator screens can legitimately use another language.
- For PHP, verify the loaded MO file and the timing of the text-domain registration.
- For JavaScript, confirm the script handle, domain, locale, and expected JSON catalog.
- Recompile the correct PO source only after syntax validation, then clear only caches that can retain the previous code or catalog.
- Test a singular message, a plural message, the affected screen, and each required locale after the change.
Risks, common mistakes, backup, and rollback
Changing the text domain to match a convenient filename can break every other translation. Editing a downloaded language pack in place creates a temporary fix that an automatic update may erase. Older catalogs in higher-priority directories can also mask a correct replacement.
Preserve the current candidate files before editing. Roll back if unrelated strings regress, characters break, the wrong locale loads, or the change survives only in one warmed process. Restore the previous files, clear only the relevant runtime cache, and retest the original message plus an unaffected control string.
How AIOWS helps:
AIOWS Language Compiler
AIOWS Language Compiler helps inspect supported WordPress language sources and rebuild the runtime catalog when a PO-to-MO mismatch is the confirmed cause. Begin with the exact untranslated message, locale, text domain, PO source, current MO file, candidate directories, and a recoverable copy of every file that might take precedence.
Select only the catalog associated with the affected plugin, theme, locale, and release. Review parse problems before compilation, then generate the MO file at the intended destination. Check its existence, size, timestamp, ownership, and permissions, but do not stop at a successful compiler result.
Open a clean WordPress request in the affected locale and inspect the named message. Test a plural form and one unaffected translation as controls. If the missing text comes from JavaScript, trace the required JSON catalog separately; rebuilding an MO file will not repair a script translation that WordPress never registered.
Language Compiler cannot add an absent source translation, correct a wrong text domain in plugin code, or make an update-managed directory safe for permanent customization. If the change fails or causes another translation to regress, restore the previous language files and remove only the new artifact. Record the message, domain, locale, source and loaded paths, hashes, build result, displayed string, and update ownership.
Related AIOWS articles
- How to Compile WordPress PO Files into MO Files
- How to Scan and Manage WordPress Language Files
- How to Configure Cache for a Multilingual WordPress Site
Conclusion and recommended route
Follow one missing message through its source string, context, domain, locale, catalog, path, and load timing. Rebuild or relocate only the file proven to own that lookup, and test PHP and JavaScript translations separately. Store custom work where the update model will not replace it.
