Internationalization Notes

This page provides details for people creating translation tools and other internationalization systems that support Mallard documents. Mallard is an XML format, so there is a wealth of translation tools and techniques that can be applied. XML does not immediately solve all problems, however, and Mallard was designed from the beginning to support features that are important to proper document localization.

Message-based Translation

One of the most difficult aspects of document translation is tracking changes to the source document. For this reason, message-based translation systems such as PO files or XLIFF are popular. XML formats lend themselves well to message-based translation systems, but developers must decide what type of content constitutes a message.

In Mallard, block and inline content are always distinct. You can never, for example, place a paragraph inside the text content of another paragraph. This was done in large part to avoid the need for placeholders in messages. Some elements, such as code and media, can occur in either a block or an inline context. When processing a Mallard page, it is important to keep track of context so you know how to treat an element.

Mallard never places translatable text in attribute values.

Internationalization Attributes

Mallard does not contain its own elements to specify language or text directionality. To specify language, use the standard xml:lang attribute. To override text directionality, use the its:dir attribute from the W3C Internationalization Tag Set (ITS).

It is strongly recommended that you support ITS in translation tools. For example, to allow authors to mark certain elements as non-translatable, use the its:translate attribute.

Localization Notes

Processing tools should support ITS mechanisms for providing notes to translators. At a minimum, tools should support the standalone its:locNote attribute for localization notes.

If more extensive localization notes are needed, the comment element may be used. In tools that support global ITS rules, particular comment elements can be set as localization notes using the its:locNoteRule element in an its:rules element in an info element.


There are two different methods of identifying language and locale information that are likely to be encountered by those working with Mallard. Since Mallard is an XML format, language identifiers are expected to conform to IETF RFC 3066. Since Mallard is often used in a desktop help system, POSIX locale identifiers are often more convenient. Processing tools should convert between these two formats, and should generally prefer RFC 3066 identifiers, except where compatibility with other systems takes a priority.

The language and region portions of these two locale identifier schemes are identical (although by convention often differ in case). Other modifiers, such as script, nearly always use different codes, necessitating a conversion table.

Container Elements

Mallard provides the generic span and div container elements. These elements may be used to group together inline and block elements for specifying localization data, such as translatability or localization notes.

Media Elements

Mallard allows audio, video, and images to be inserted into pages using the media element. These cannot generally be translated using textual translation tools. You should provide a way for translators to provide localized multimedia files and see when the original files have changed.

Translation Credits

Mallard allows contributors to be credited using the credit element. The type attribute can be set to "translator" to credit translators. Since translator credits aren't direct translations of existing elements, they can't be provided using simple message-based translation alone.

You should provide a mechanism to insert translator credits into translated output pages.

© 2009, 2019 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by