16.1.6.2 Specifying where to find the ITS Rules

‘xgettext’ needs another file called "locating rules" to associate an ITS rule with an XML file. If the above ITS file is saved as messages.its, the locating rules file would look like:

<?xml version="1.0"?>
<locatingRules>
  <locatingRule name="Messages" pattern="*.xml">
    <documentRule localName="messages" target="messages.its"/>
  </locatingRule>
  <locatingRule name="Messages" pattern="*.msg" target="messages.its"/>
</locatingRules>

The locatingRule element must have a pattern attribute, which denotes either a literal file name or a wildcard pattern of the XML file⁷. The locatingRule element can have child documentRule element, which adds checks on the content of the XML file.

The first rule matches any file with the .xml file extension, but it only applies to XML files whose root element is ‘<messages>’.

The second rule indicates that the same ITS rules file are also applicable to any file with the .msg file extension. The optional name attribute of locatingRule allows to choose rules by name, typically with xgettext’s -L option.

The associated ITS rules file is indicated by the target attribute of locatingRule or documentRule. If it is specified in a documentRule element, the parent locatingRule shouldn’t have the target attribute.

Locating rules files must have the .loc file extension and obey the XML schema version 1.0 encoded by locating-rules.xsd10 or the XML schema version 1.1 encoded by locating-rules.xsd11. Both ITS rules files and locating rules files must be installed in the $prefix/share/gettext/its directory. Once those files are properly installed, xgettext can extract translatable strings from the matching XML files.

16.1.6.3 Two Use-cases of Translated Strings in XML

After strings have been extracted from an XML file to a POT file through xgettext and the translator has produced a PO file with translations, it can be used in two ways:

• The PO file (or the MO file generated from it) can be directly consumed by a program.
• Or the translated strings can be merged back to the original XML document. To do this use the msgfmt program with the option --xml. See Invoking the msgfmt Program, for more details about how one calls the ‘msgfmt’ program.

  During this merge from a PO file into an XML file, it may happen that more escaping of special characters for XML is needed than what msgfmt does by default. In this case, you can enforce more escaping either throuch an <escapeRule> ITS rule, or through an attribute gt:escape="yes" on the particular XML element.