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 sync translation files directly to your source code? Loco can do exactly that, but it's often a bad idea to rely on this:
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 fast.
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.
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.
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.
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 themselves no longer provide translation templates, because their own GlotPress software generates them as needed.
In the absence of a template file your options are:
- Sync directly to source.
- Generate your own template from source.
- Ask the author to provide a template. (best, but slowest option)
- Select an existing PO file to act as a template. (recommended when possible)
Should I create a template?
If you decide to create a template from someone else's code (or sync directly to source) then it's quite likely you'll run into difficulty at some point. We can't help you in this situation, but we can advise the author on making their next release more compatible.
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
"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. This is a particularly good approach if you have community translations installed and simply wish to override some with your own text. If a PO file comes from the WordPress translation community then it's likely to be reliable as an up-to-date template.
Should I edit or sync the template?
Loco Translate allows you to manually edit templates, and also sync them back to the source code from within the editor. 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 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.
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 supplied 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 to the template?
If a template is provided - and you trust it - then yes.
You only need to do this when the bundle's template has been modified. This generally means after a WordPress update. 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.
Note that Loco Translate doesn't currently have any complex merging or fuzzy matching features. This means that if
"Foo" changed to
"foo" it would be seen as a new string. The old translation would be removed and a new untranslated string would be added. More sophisticated merging is planned for future development.