Working with POT files in Loco Translate
Not to be confused with WordPress templates (which are PHP files) a POT file is basically a PO file without any translations in it. If you're not familiar with the Gettext workflow, here's the basic gist of what a POT file is for:
- The author writes some PHP code containing translatable strings (source text);
- The author generates a POT file that tells translation software what strings are available;
- Translators create new language files from the template so they have the right strings;
- If the author updates the template, translators can sync their files to reflect any changes.
Do I need a template?
You may think step 2 above is a little redundant. Why not just create translation files directly from the source code? Loco Translate can do that, but we recommend against it in most situations:
Reliability
Without a template there's no guarantee that string extraction will work properly. Authors are free to write code however they like, even if it means other software can't understand it. If they've provided a template themselves then this is a non-issue.Speed
Scanning source code for translatable strings can be slow. You won't notice the difference with small bundles, but with thousands of lines of code across many source files you really will. Reading even a large POT file is very fast.Memory
Scanning particularly large source files can use a lot of memory. If you have a strict memory limit on a shared server, you may find it needs more than you've got. See FAQ on memory crashes.Authority
A POT file is the author's way of telling you what is officially translatable - no arguments. They may have made changes to the source code, but until those changes are finalized and a new template is provided, the template is the canonical source of the available strings.Convention
It's a Gettext convention to have a template file. WordPress doesn't require it, but most Gettext software won't work without one. For the sake of best practice, we recommend authors ship an up-to-date POT file with every release of their bundle. It's just kind to translators.
What if there is no template?
Authors are under no obligation to provide a template and very often don't. WordPress no longer ship translation templates in the core code base or with their themes. In the absence of a template file your options are:
- Create translation files directly from source code. (not recommended)
- Generate a template from source code. (if you know what you're doing)
- Ask the author to provide a template. (best, but usually slowest option)
- Select an existing translation file to act as a template. (recommended when possible)
Should I create a template?
In many cases generating a template file is simple. Themes and simple plugins that follow WordPress standards are generally extractable quickly and without error. However, some products are more complicated. Plugins may have very large files, use JavaScript heavily, or ship with some kind of framework that has its own translations. There are many pitfalls, so generally we don't recommend extracting strings unless you're the author.
If you decide to create a template from someone else's code (or sync directly from source) then it's quite likely you'll run into difficulty at some point. Please note that we do not provide help with source code, and that includes debugging a third party theme or plugin to find why source strings aren't being extracted.
For more on this topic see Extracting translatable strings from source code.
Selecting an alternative template
Often authors use unconventional names for templates and you may find it's hiding in plain sight. If you see a file named "default.po" or "en_US.po" then it's quite likely the author intended this to be used as the template. Loco won't automatically use files that don't follow convention, but you can configure any file to be used.
Even without an official template like this, Loco Translate can use any PO file as a stand-in template. Either configure it as above, or find it in the dashboard and click "Copy". There's an example of doing this in our guide to Customizing Translations and also in the FAQ about Missing templates.
Using an existing translation file is a particularly good approach if you have community translations installed and simply wish to override some strings. If a PO file comes from the WordPress translation community then it's likely to be reliable as an up-to-date template. We recommend you always do this for editing the WordPress core translations, and do so when you can for plugins and themes.
Should I edit or sync the template?
Loco Translate allows you to manually edit templates, and also sync them with the source code when the available strings have changed. If you're not the bundle author you should avoid doing both of these things.
- Adding strings to the POT file will not make them translatable. The author must also add the strings into their code.
- Syncing POT files with the source code is something we recommend against unless you're the author.
If you decide to edit or sync the author's template, be aware that you may be overwriting strings the author intended to be translatable. We can't offer any help if you break functionality by modifying the author's files.
For more on syncing templates see the Sync function.
How do you know if a template is up to date?
It's not uncommon for authors to publish new versions of their source code without updating their provided template. Opening the template in the Loco Translate editor and clicking "Sync" isn't guaranteed to work. This makes it very hard to know if the template is accurate.
You can spot-check the accuracy of a file by opening its "Source" tab and clicking on one of the file references that accompanies each string. The highlighted line of code that pops up should contain the exact string on the exact line it was extracted from. If it doesn't line up, then the file is not up to date with the code.
If you find strings in the template that aren't on your site (or vice versa) then report this is a bug to the author.
Should I sync my translations with the template?
If a template is provided - and you trust it - then yes.
You only need to do this when the template has been modified. This generally means after a WordPress update. Loco Translate will warn you if a PO file is out of date and prompt you to click Sync.
Clicking Sync from the editor will add any new strings and remove any old ones. Nothing at this point is saved until you click Save, so it's perfectly safe to sync a file out of curiosity. You can always discard any changes that occur.
For more on this topic see the Sync function.