A translator corrects a German message in a PO editor and uploads the file, yet WordPress continues to show the old sentence. The editable catalog changed, but its binary MO file was never rebuilt, so the site still loads the previous translation.
Compilation is only one part of the fix. Before replacing anything, confirm the active locale, text domain, source filename, destination filename, and directory that WordPress actually loads. Then compile the catalog and verify a known string in a clean request.
What it means
A PO file is a human-readable gettext catalog containing source messages, translations, context, headers, and plural rules. An MO file is the compiled binary catalog that WordPress can load at runtime. Compiling a valid PO file produces the corresponding MO file; it does not discover missing strings or decide which locale, text domain, or directory the application uses.
- The PO file remains the maintained source; the MO file should be a reproducible build artifact.
- The filename and location must match the way the plugin, theme, or WordPress core loads translations.
- A successful compiler exit does not prove that WordPress selected the new catalog.
A realistic WordPress example
A plugin uses the example-plugintext domain and loads German from an MO file in its language directory. A translator updates the corresponding PO catalog, but the deployed MO file still contains the previous message.
The team validates the catalog, compiles it to the exact expected filename, and checks a known singular and plural message in a clean German request. They also confirm whether the next plugin update or deployment will overwrite that directory before treating the replacement as permanent.
Why it matters and when to use it
Compile after an approved translation change, a repaired catalog, or a reproducible language build that needs a new runtime artifact. Recompiling is appropriate only when the PO source is valid and the missing or stale text comes from the catalog WordPress should load.
If the source string is absent, the text domain is wrong, the locale does not match, or WordPress loads another path, a new MO file will not solve the underlying problem. Separating catalog content from loading behavior prevents repeated builds of the wrong file.
A straightforward route for beginners
- Back up the current PO and MO files and note their hashes, ownership, permissions, and location.
- Confirm the active WordPress locale, plugin or theme text domain, filenames, and load directory.
- Validate catalog headers, UTF-8 encoding, plural forms, and message syntax.
- Compile only the approved PO file with a supported gettext or WP-CLI workflow and an explicit destination.
- Check that the MO file exists, is non-empty, and has the expected ownership and permissions.
- Load known singular and plural messages in a clean front-end or administrator request using the intended locale.
The advanced route
Make the build reproducible. Record the compiler version, input hash, output hash, command, locale, text domain, and destination. A clean build should produce the same accepted MO file from the same PO input.
- Trace parser warnings to the exact message instead of publishing a partially compiled catalog.
- Change one harmless test translation, rebuild, and verify that only the expected runtime message changes; then restore the approved source.
- Inspect the code or loading hook that determines the language directory rather than assuming the newest file wins.
- Check whether a plugin update, language pack, container rebuild, or deployment step will replace the destination.
- If caching obscures the result, clear only the relevant runtime or application cache and repeat the named string test.
Risks, common mistakes, backup, and rollback
Malformed PO syntax can produce no output or an incomplete catalog. A correct MO file can still be ineffective when it has the wrong locale suffix, text domain, directory, ownership, or permissions. Writing into a plugin directory may also create a short-lived fix that disappears at the next update.
Do not edit MO bytes directly or discard the source catalog. If parsing fails, characters break, unrelated translations regress, or WordPress loads the wrong file, restore the previous PO and MO pair. Confirm the restored sample strings before removing the failed artifact or changing the build process.
How AIOWS helps:
AIOWS Language Compiler
AIOWS Language Compiler provides a managed workflow for inspecting supported WordPress language sources and producing the compiled file used at runtime. Start with the exact PO source, locale, text domain, current MO file, destination, ownership, and a recoverable copy of both files. Keeping those details together makes the replacement reviewable.
Select only the approved catalog and review any parse or catalog errors before compilation. Do not mix files from another plugin, theme, locale, or release. After the build, confirm that the generated MO file exists at the expected destination, has a plausible size and timestamp, and retains the permissions needed by the site.
The decisive check happens in WordPress, not in the compiler status. Open a clean request in the intended locale and inspect a named translated string, including a plural form when the catalog uses one. If the new text is absent, verify which text domain and path WordPress loaded before compiling again. A successful build proves that a file was produced; it does not prove that the application selected it.
Language Compiler cannot write missing translations, repair an incorrect text domain in plugin code, or prevent an update from replacing a file stored in an update-managed directory. If the runtime test fails, restore the previous PO and MO pair and remove only the newly generated artifact. Record the source and output hashes, locale, domain, destination, compiler result, displayed string, and update-safe storage decision.
Related AIOWS articles
- WordPress Plugin Translations Not Showing: Causes and Fixes
- How to Scan and Manage WordPress Language Files
- How to Configure Cache for a Multilingual WordPress Site
Conclusion and recommended route
Treat the PO file as maintained source and the MO file as a reproducible runtime artifact. Verify the locale, text domain, path, syntax, and overwrite policy before compiling, then test a known singular and plural string in WordPress. Keep the previous pair until the new catalog survives both a clean request and the next normal deployment.
