Configuring a bundle in Loco Translate
If you have trouble translating a theme or plugin, you may need to give Loco some hints about how the author has set things up. WordPress doesn't tell developers exactly how to set up translations, so there's a very wide variety of ways they could have gone about it.
Loco Translate bundle definitions can be used to declare various non-standard configurations including multiple text domains. Developers may prefer to visualise this concept as XML. The rest of this page refers to configuring a bundle via form fields.
Configuration settings
Under the "Advanced" tab you'll see a form with various settings that tell Loco how a bundle has been set up for translation.
Project name
This name is just for display purposes and will normally be the same as the bundle name. It's editable because you may have multiple projects within the same bundle. We'll get to that later.
Text Domain
This piece of information is critical. If the bundle doesn't declare its text domain Loco won't know some basic things; (like what names to give new files, or what strings can be extracted for translation). If you don't know what to put in here, ask the author. Don't guess that a theme called "foo" will have a text domain called "foo"; this is often not the case. If this value is wrong, your translations simply won't work.
File prefix
The file prefix (or "slug") is for developers to split text domains into multiple files. If you're not doing that (and you usually won't be) then enter the exact same value as the text domain. A blank field won't fall back to the text domain, so don't leave this empty unless you have a specific reason for doing so.
Template file
The template containing translatable strings is normally a file named "languages/<TextDomain>.pot", but developers use a wide variety of naming conventions and it's not always possible to guess which file is the right one. If you don't know where this file is, ask the author. The author may not have provided one, but we won't cover that situation here.
Template lock
The "Locked" property states that translators are not permitted to update the template file. It's normally the responsibility of the developer to ship an up-to-date template file with every bundle release. Translators shouldn't have to worry about the highly technical aspects of generating templates.
Domain path
This is normally a single folder inside the bundle where translation files for the project are found. Although this value is optional, it's very important in finding which translation files are part of the same set.
The exclude list can be used to avoid searching subfolders, or hide individual files that aren't part of the set.
Source file paths
This is only required if you plan to extract strings directly from the source code. That task should normally be left to the bundle developer, but if the author hasn't provided a template file you may have to do it yourself.
The exclude list is useful for speeding up scanning of large projects. If there are folders that will never contain translatable PHP files, then add the paths here to save some leg work.
Blocked paths
This is a list of locations that will be excluded across all projects in the bundle. It's useful for adding folders you never want to search for anything, such as "vendor" or "node_modules".
Note that Loco automatically blocks all "dot files" so ".git" and ".svn" will never be scanned.
Filesystem paths
Some important things to note about all the fields above that take file or folder paths:
- Paths should be relative to the bundle root. e.g. don't enter
"/languages", it must be"languages"; - You must enter the full relative path. Entering
"baz"will not match"foo/baz"; - Wildcards and glob patterns are NOT supported. Entering
"*.po"won't work; - Absolute paths will work, but aren't recommended. If you need to reference files outside the bundle, you can use
"../"; - Don't enter global/system paths like
"wp-content/languages/themes". Loco Translate observes these locations automatically;
Translation subsets
The "Add set" button at the bottom of the configuration form divides the bundle into a further subset of source strings. This allows your codebase to be split into more than one template file, and hence more than one set of translation files that reference it.
Take care with overlapping definitions because Loco doesn't prevent two sets from containing the same file. Good use of include and exclude paths can easily avoid these kind of problems.
For a good example of a complex multi-set bundle, take a look at the WordPress core bundle. Under the Loco Translate side bar menu, click "WordPress" and then its "Advanced" tab.
You will see for example that files included in "network-admin" are explicitly excluded from "admin", because otherwise they would overlap and the same strings would be extracted twice.
In most situations every set will be in a different Text Domain, but this is not a requirement and is why the slug parameter exists. Note that the WordPress "default" domain is split into three separate files using three different file prefixes. Themes and plugins don't generally behave this way, but the options are there if you need them.
XML config files
At the bottom of the configuration form you can download the saved configuration as an XML file.
See the XML schema for full details of this file format.