ITS WG Collaborative editing page

Follow the conventions for editing this page.

Status: Initial Draft ie. please focus on technical content, rather than wordsmithing at this stage.

Author: Masaki Itagaki

Links to internal/external text and objects

Summary

Any text and object references to internal and external content, such as references to section titles, software UI items, screen captures and localizable graphic contents, should be implemented and identified in such a way that it is possible for localisation tools to retrieve the actual text or objects from original text places. A standardized mechanism to retrieve access-releted infromation, such as authentication, authorization and location, as well as appropriate language information should be provided.

[CL] Isn't "text references" too restricted? Wouldn't we also like to ensure for example that a screenshot/graphics which appears in a document, corresponds to a certain GUI element?

[CL] "retrieve the actual text" seems too ambitious from my point of view. Example: I might need a certain user and password in order to connect to the development repository. This information (user id and password) is not sth. I would like to code in the XML content. Suggested alternate formulation: Identify corresponding development object/referenced object uniquely.

YS-''' So maybe something like: "...it is possible for localization tools to automatically retrieve the information about how to access the references at their original locations." '''

[[MI- However, how to retrieve the linked data should be an seperate issue. It's not just an authentication issue. Accessing to external data may require a specific access parameters, URL, ane even a specific application. How to access to external data should be left to a rendering application or process. When the Linked Tag has something like src=/database/formItems/description@pk=123, how to access to the data in the description field of the formItems table should be taken care of by a rendering tool or a localization tool. ]]

[CL] As mentioned during the 19 May 05 conf call: From my understanding, we are looking at two requirements

a) markup which allows us to say 'the content here originates somewhere else'

b. identification/access information related to the markup (this might be something simple like a GUID, or something more complex like all information necessary to actually log on to a terminology management system and navigate to a term stored in the system)

Example:

See also <originatesElsewhere infoId="42">Work with Voucher</originatesElsewhere>

<info>

<general system="MYSystem" database="DB4" user="xxx" password=""/>
<entry id=42" termInDB="4444"/>

</info>

Challenge/Issue

Direct text references could occur as in the following examples:

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 reuse the original translated 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.

[CL] I am not sure about the "carrying over". In XML vocabularies I am familiar with, link often allows you to have a link text in the link source/origin that is different from the text of the link target. Example: <a>point to</a>, where the a element allows you to use arbitrary text. You are not restricted to the text in the link target. I guess there's a reason behind the provision for this mechanism.

[MI] We'll discuss this durind the next teleconference.

[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.

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.

[[YS- I could also see some paragraph about the need to e able to modify the reference text as it is retrieved. For example, the data from a software UI "&File..." cannot be use as-it in the documentation, one need to remove the '&' (and maybe '...' too). But it also affect capitalization, etc. especially since different languages may have different rules for this. ]] 'MI-''' This may require some noramlization in rendering external data but it's only if UI items are linked. So definitely some normalization machanism must be provided as an option. Maybe I should put this in Quick Guideline Thoughts. ''

[[YS- A better example, maybe: a UI string "The file '{0}' could not be found." is used linked to the product documentation. The '{0}' variable placeholder should be replaced by a more meaningful information, for insteance: "The file '<filename>' could not be found.". This in turn need to be properly localized to "Le fichier '<nom du fichier>' est manquant." The replacement for '{0}' needs to be defined somewhere and be accessible for localization as part of the reference/linking mechanism.

So, in addition to the indication that an item reside somewhere else, and that a identifier to access it should be available, we also have the requirement that, if the referencing mechanism allows for modifications in the refered text, then it should also allows the possible localization of such modifications.

For example:

Not very localization-friendly:

<p>If you get the error "<xref id="resfile.resx" subst="s/{0}/<Filename>/">",
then do...<p>

A little better:

<p>If you get the error "<xref id="resfile.resx">
 <subst>
  <search>{0}</search>
  <replace><Filename></replace>
 </subst>
</xref>", then do...<p>

]]

[[YS- Another aspect, maybe more important, is to have the reference mechanism language-aware. You don't want to have to change each reference 'path' to the files in each localized versions of the document that uses the references. In other words, the reference mechanism should have provision for possibly working in conjuction with the current language settings.]] MI-''' This is also a rendering issue, correct? Datasource should be language-aware, but it can always refer to a language/locale in the superordinate element and fetch a correct langauage text. This should be mentioned in the Challenge/Issue section.'''

[[YS- Yes, the way the language itself is defined in the document can be achieved different ways. But I think what is important is that the referencing mechanism should be as language-independant as possible (rather than 'aware' like I said before).

For instance, in the example <xref id="resfile.resx">...</xref>, we should not have to change the value of id. Whether the referencing works with a relative directory structure or add automatically language info to the base file name (ie. "resfile_fr.resx") is not important, as long as we don't have to modify the id. Just like you don't want to have to change references to images in <img src="whatever.png"/>).]]