Overview of the Gettext functionality of Loco Translate

If you're not familiar with localizing WordPress or working with Gettext files, you should start by reading the basic introduction to what this plugin does.

Below is a high level overview of what the plugin does from a technical standpoint. 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.

Gettext workflow

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, compiling MO files and merging new sources. 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.

Organizing bundles

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. Often this is equivalent to a single text domain, but it doesn't have to be. Themes and plugins often have multiple text domains, despite this not being a WordPress convention.

Files within each bundle are grouped together into sets. Each set comprises a template file (POT), pairs of localized PO/MO files, and optionally any number of JSON files (added in WordPress 5). A set is often equivalent to a text domain, but splitting text domains into multiple sets is supported. For example, WordPress's "default" domain is split into four sets.

• FAQ: What's a Bundle?
• Setting up bundles

Extracting strings

For theme and plugin developers, Loco Translate can start at the beginning with string extraction from your code base. This can be done from within WordPress admin, so no need to run anything from the command line unless you prefer to.

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 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.

• Working with POT files
• Extracting templates from source code
• loco extract command

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 (and optionally JSON files). If the bundle is set up correctly the MO file will be saved to the correct location from where WordPress will load it.

• Creating a new PO file (msginit)
• Using the translation editor
• Compiling JSON translation files

Merging translation files

Translators are warned when their PO files no longer match the template. This occurs after a POT file has been updated (either manually, or after a WordPress upgrade). PO files are not automatically merged. The solution is to update the source strings via the "Sync" button in the editor toolbar.

The sync operation adds new strings and deletes obsolete ones, but fuzzy matching is supported. When a modified source string is similar enough, the existing translation is retained.

• Updating PO files from POT (msgmerge)
• Fuzzy matching tolerance
• loco sync command