Links to internal/external text

This is a requirement corresponding to two previous requirements – 2.13
Citation and 2.14 References to UI messages in document. Here I tried to
combine them into one document simply because I did not see any differences
between them. We could split it into two again, if necessary. I was not
really sure if the term “link” (as in the XLink) should be used here. It’s
not just a link, so maybe “text replacement” or “replaceable text” works
better. Please post any feedbacks on this. 

 

Masaki Itagaki

--------------------------------------------------------------------------


Links to internal/external text


Any text references to internal and external content, such as references to
section titles and software UI items, should be implemented and identified
in such a way that it is possible for localisation tools to automatically
retrieve the actual text from original text places. 


Background 


Direct text references could occur as in the following examples:

1) See Also 

[Sample]
A chapter title: Work with Vouchers

In another section: 
...See also Work with Voucher for more information about this process. 

Translation for “Work with Voucher” could have many variations depending on
context, translation styles and target audience. If a chapter title, in the
example above, is referenced in exactly the same format, the text should be
represented as some sort of linkage in order to carry over the original
text. This way, translators could avoid translating the same text
repeatedly, which is very beneficial from the point of translation
consistency as well as productivity.  

[Sample]
<chapter id=”c18”>Work with Voucher</chapter> ...

In other section: See also <ilink item=”/doc/chapter#id” val=”c18” /> for
more information about this process.

2) References to software UI items 

[Sample]
Selecting Initialise Auditron will always produce a confirmation screen. If
OK is selected twice, the Auditron will be initialised and the account data
deleted. 

The text 'Initialise Auditron' is a quotation from the user interface and
has typically already been translated. Therefore the translator's job is
simply to locate the actual translation previously supplied so as to
maintain consistency. 

For example, 'Initialise Auditron' may have been translated in Spanish in
any of the following ways: 

*	Inicializar Auditrón 
*	Inicializar el Auditrón 
*	Inicialización del Auditrón 

Any of these are acceptable translations, but the translator must try to
choose the exact words used in the context which is being quoted. 

[Sample]
Selecting <ui-message name="Initialise Auditron" id="msg123" /> will always
produce a confirmation screen. If <ui-message name="OK" id="msg124" /> is
selected twice, the Auditron will be initialised and the account data
deleted.