Technical overview of the "Loco Translate" WordPress plugin
If you're not familiar with localizing WordPress or working with Gettext files, you may want to read the beginner's guide instead.
This short guide is a high level overview of what the plugin does. The intended audience is developers or translators familiar with Gettext. This is not a guide to using the various functions of Loco Translate, for that see the manual.
Loco Translate's primary purpose is facilitating the Gettext translation workflow directly in your WordPress admin area.
WordPress has no need for PO and POT files, and no way to edit them. It is only interested in loading compiled MO files. Loco Translate fills this gap by providing an end-to-end workflow for extracting strings, editing PO files, and compiling MO files. This process is quite technical by its very nature, but Loco Translate tries to be as faithful as possible to Gettext conventions while being as user-friendly as possible for WordPress translators.
Loco Translate organizes all the translation files on your system into bundles of core, theme and plugin types.
"Bundle" is our term for all the translatable strings that belong to a single WordPress component. Related files within each bundle are grouped together into sets. Each set comprises a template file (POT) and any number of translation files that reference it (PO/MO). Usually each set will correspond to a whole text domain, but splitting text domains into multiple templates is also supported.
See FAQ: What's a Bundle?
For bundle developers, Loco Translate can start at the beginning with string extraction from your codebase within WordPress itself.
Clicking "Create template" will automatically extract the strings for a given Text Domain. Unlike the
xgettext command line program, Loco can target specific text domains in your code.
This means your codebase can reference other domains (such as the useful WordPress
"default" domain) without polluting your POT files. This can also highlight errors in your code. For example: A missing string suggests a badly formed function call was written for displaying it.
See our user guide to working with POT files.
Translating PO files
Loco Translate's built-in editor provides user friendly editing of PO files. Translators are protected from the nuanced syntax of PO string encoding. Just type plain text and the correct format will be saved.
Every time you save a PO file, Loco Translate also compiles a binary MO file. If the bundle is set up correctly the MO file will be saved to the correct location from where WordPress will load it.
See our user guide to the translation editor.
Editing POT files
Although it's against the usual Gettext workflow, Loco Translate allows POT files to be manually edited. This feature exists for developers who are manually maintaining templates files rather than extracting strings from sources. An example use case for this would be managing strings that are dynamically generated at runtime and therefore not referenced in code at all.
See our user guide to editing POT files.
Merging translation files
After a POT file has been updated, translators are warned that their PO files no longer match the template. The solution is to merge the changes via a "Sync" button in the editor toolbar.
The same function can be run on POT files to update them after the source code has changed.
Loco Translate doesn't [yet] have fuzzy matching capabilities, So the sync operation simply adds new strings and deletes obsolete ones. More sophisticated options for this process are in the pipeline.