Internationalization Notes

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.

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.

Mallard can automatically generate text for a link using the title of the target page or section. In many formats, this presents a serious problem to languages with declensions for different parts of speech.

Mallard allows any number of extra link titles to be provided for a page or section. Each of these link titles specifies where it should be used with the role attribute. Links can then specify which title to use using the role attribute on the link element.

You should provide a way for translators to provide additional link titles for each page or section, and for them to specify the appropriate roles on inline links.

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.

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.