Translation Notes

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.

If you need to use different link text depending on the part of speech where the link occurs, you should provide alternate link titles for each page, and select among these using the role attribute of each inline link.

For example, say you are translating into a language with language code zxx. You have a page with id ducks and the title Ducks. You want the link text to this page to read The ducks when the link is the subject of a sentence, and ducks when the link is the direct object of a sentence. Add the following to the info element on ducks.page:

<title type="link" role="zxx-subject">The ducks</title>
<title type="link" role="zxx-object">ducks</title>

When linking to this page inline, add the role attribute to each link element, matching a role attribute of a title tag, as follows:

<link xref="ducks" role="zxx-subject"/> has more information.
See <link xref="ducks" role="zxx-object"/> for more information.

You can add as many roles as you need. If you have not provided a link title with a matching role for a particular link, the primary title will be shown instead.

To avoid conflicts with other uses of link roles, you should always name your roles starting with your language code followed by a hyphen.

Mallard provides inline markup elements to support common needs in software documentation. Sometimes the markup in the original language is unnecessary in your language, or your language might need additional markup.

The em element emphasizes text. Mallard does not provide separate element for different semantic uses of emphasis, such as foreign words, introductions of terms, and titles of publications. In some languages, these uses don't all use font variations like italics. Non-latin scripts usually don't even have italics, although it is becoming more common to use an oblique font or other variant in those scripts.

If your language does not use italics or other font variants for a particular type of emphasis, you should leave out the em tag altogether and replace it with the correct text. For example, if the title of a publication is emphasized as <em>The Mallard Book</em>, but your language puts publication titles in quotations, you should replace this with «The Mallard Book», 『The Mallard Book』, or similar.