Extensions

The itst:match rule specifies an XPath selector that must match before other rules can be applied. When processing an its:rules element, ITS Tool looks at each itst:match child and evaluates its selector attribute. If at least one of them returns a non-empty node set, the rules are applied. Otherwise, processing stops.

For example, the built-in Mallard rules contain the following:

<itst:match selector="/mal:page"/>

The itst:match rule helps performance. For example, DocBook contains over 400 elements, and the built-in rules for DocBook contain over 150 descendant-or-self selectors. Using itst:match in the DocBook rules prevents those XPath expressions from being evaluated for non-DocBook documents.

The itst:contextRule rule and itst:context local attribute allow you to specify a context for a node to disambiguate it from other nodes with the same string value. This is managed in the PO file with msgctxt. Most modern PO file tools support msgctxt.

Many structured XML document formats provide ways to credit contributors. To credit translators properly, new elements need to be inserted into the translated document. ITS Tool provides the itst:credits rule for this. For example, here is the built-in rule for Mallard:

<itst:credits appendTo="/mal:page/mal:info">
  <mal:credit type="translator copyright">
    <mal:name><itst:value-of select="name"/></mal:name>
    <mal:email><itst:value-of select="email"/></mal:email>
    <mal:years><itst:value-of select="years"/></mal:years>
  </mal:credit>
</itst:credits>

The appendTo attribute selects an element that credits should be added to. If any element in the source document has been matched, ITS Tool will add a translator-credits message to the PO output:

msgctxt "_"
msgid "translator-credits"
msgstr ""

The translated value is expected to be a list of credits, with one credit per line. Each line is of the form

NAME <EMAIL>, YEARS

For each credit, ITS Tool will copy the contents of itst:credits into the target element, replacing each itst:value-of element with the corresponding value.

Some formats expect each year to be in its own element. You can also use itst:for-each to loop over the years. For example, here is a snippet of the built-in DocBook rule for credits:

<copyright>
  <itst:for-each select="years">
    <year><itst:value-of select="year"/></year>
  </itst:for-each>
  <holder><itst:value-of select="name"/></holder>
</copyright>

This assumes that the years are provided as a comma-separated list.

Deprecated in 2.0 Use the ITS 2.0 its#preservespace data category instead.

The itst:preserveSpaceRule rule specifies elements that should preserve whitespace, such as code blocks. The standard xml:space attribute can be used on individual elements. With DTDs, this can be applied implicitly as a #FIXED attribute. Modern schema languages, however, don’t modify the infoset. Adding a xml:space to each space-preserving element is cumbersome.

For example, the built-in Mallard ITS rules mark all code elements as space-preserving with the following rule:

<itst:preserveSpaceRule preserveSpace="yes" selector="//mal:code"/>

When an element is space-preserving, and when that element corresponds directly to a message, ITS Tool places the standard no-wrap marker on the message. Note that space-preserving nodes are currently only handled for elements that have their own message. Inline space-preserving nodes are not treated specially.

Deprecated in 2.0 Use the ITS 2.0 Locale Filter data category instead. The functionality of itst:dropRule can be accomplished by setting localeFilterList to an empty string, or by setting localeFilterType to "exclude" and localeFilterList to "*".

The itst:dropRule rule and itst:drop local attribute allow you to drop elements entirely from the translated output. No messages will be added to the PO file for these nodes. Unlike just setting the nodes to be non-translatable, dropped nodes won’t even appear in the merged XML. This is useful, for example, for elements that hold editorial comments.

Use the rule as you would use its:translateRule:

<page>
  <info>
    <itst:dropRule selector="//comment" drop="yes"/>
  </info>
  <comment><p>This comment is dropped</p></comment>
</page>

You can also use the itst:drop attribute on any element:

<comment itst:drop="yes"><p>This comment is dropped</p></comment>

Deprecated in 2.0 Use the ITS 2.0 External Resource data category instead.

XML documents often reference external files for images, videos, and other non-text content. Although these cannot be translated as strings inside PO files, ITS Tool can help you track these files with the itst:externalRefRule rule. The selector attribute selects nodes that reference external files, and the refPonter attribute selects the files’ URLs relative to those nodes. For example, the built-in Mallard rules contain the following:

<itst:externalRefRule selector="//mal:media" refPointer="@src"/>

ITS Tool will read each external file and calculate an MD5 checksum. It then outputs a message containing the URL and the checksum. ITS Tool uses the special msgctxt "_" for all special messages that don’t correspond to text in the XML document. Here is an example of the output:

msgctxt "_"
msgid "external ref='nautilus.png' md5='cbc3bbf0d998ed7a6567eb3b0c402195'"
msgstr ""

Translators can set the msgstr to anything they like to specify that they’ve created a localized copy of the file. The actual msgstr doesn’t matter. It’s only for tracking purposes. When new external files are added, new messages will be added. When existing files change, their MD5 checksums will change, causing the msgid to change. This tells translators they need to update their localized copy of the file.