I’ve recently been talking with Petr Kovar about how to make language packs for videos work well with Mallard. Petr, Jakub Steiner, and others have been working on a video-intensive “Getting Started” document for GNOME. Videos, of course, can take up a lot of disk space very quickly, and the problem is compounded when we localize into dozens of languages, as we do in GNOME.
I suggested making language packs for videos. So, for example, the Czech videos would be in a package called gnome-getting-started-cz. But you can’t expect people to use the software center to install the language pack on their own before viewing some introductory videos. Fortunately, we have a mechanism to install packages directly from a help document, using install action links.
<note>
<p>Install a language pack to view vidoes in your language.</p>
<p><link action="install:gnome-getting-started-cz" style="button">Install<link></p>
</note>
This works nicely when viewed locally in Yelp, but it doesn’t work so well when the document is built to HTML for the web. We can use Mallard Conditionals to make the note only visible when install action links are available.
<if:if test="action:install"
xmlns:if="http://projectmallard.org/if/1.0/">
<note>
<p>Install a language pack to view vidoes in your language.</p>
<p><link action="install:gnome-getting-started-cz" style="button">Install<link></p>
</note>
</if:if>
And while we’re at it, we really don’t want this note showing up when you view the original English source document, so we can refine the conditional with some language tokens:
<if:if test="action:install !lang:C !lang:en"
xmlns:if="http://projectmallard.org/if/1.0/">
<note>
<p>Install a language pack to view vidoes in your language.</p>
<p><link action="install:gnome-getting-started-cz" style="button">Install<link></p>
</note>
</if:if>
This is almost right, except that we’ve hard-coded the package name for the Czech language pack. We want to be able to translate the package name in the action attribute. If you use itstool to translate your Mallard document with PO files, it turns out the package name will be in a translatable message, but embedded in markup in a way that translators won’t like:
msgid "<link action=\"install:getting-started-cz\" style=\"button\">Install</link>"
Worse yet, if you use Okapi to translate your document with XLIFF files, it won’t appear at all. Okapi and itstool are both based on the W3C Internationalization Tag Set (ITS), and this is a case where I think ITS really shines. We can use local overrides and embedded ITS rules to instruct these tools on exactly what to offer for translation.
For convenience, define these two namespace prefixes on the page element:
xmlns:mal="http://projectmallard.org/1.0/"
xmlns:its="http://www.w3.org/2005/11/its"
To make segmentation clearer (especially for itstool), mark the link as non-translatable. This makes sure the action attribute doesn’t just get segmented with the rest of the containing paragraph. But we do want to translate the content of the link, so add a span that is translatable:
<p><link action="install:gnome-getting-started-cz" style="button" its:translate="no">
<span its:translate="yes">Install</span><link></p>
With itstool, you’ll now get the nicer no-markup message in your PO file:
msgid "Install"
But now we want to be able to translate the action attribute. Of course, we can’t add an its:translate attribute to the attribute. XML just doesn’t work that way. So we have to use embedded global rules to mark it is translatable. And while we’re at it, we can also provide a localization note for translators. Put this in the info element of the page:
<its:rules version="1.0">
<its:translateRule selector="//mal:link/@action" translate="yes"/>
<its:locNoteRule selector="//mal:link/@action" locNoteType="description">
<its:locNote>Translate this to install:getting-started-LL, replacing LL
with your locale, only if there is a video translation pack for your
locale.</its:locNote>
</its:locNoteRule>
</its:rules>
You’ll now get this in your PO file:
#. Translate this to install:getting-started-LL, replacing LL with your
#. locale, only if there is a video translation pack for your locale.
msgid "install:getting-started-cz"
This is the kind of thing that’s possible when you have a dynamic help format, an integrated local help viewer, a run-time conditional processing system, and a translation process based on powerful industry standards. And it’s why I still love XML.
