OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [docbook] Entities vs olinks

Hi David, Dave, Steven, Bob et al,

Thank you for your replies and for the reminders regarding with perils of programmatically replacing text.
We actually ran into the a/an article problem a few years ago when they changed our product's name. We try to be very careful with our use of entities.

In this particular case though, we are trying to replace the text that comes from the software resource strings, such as the name of the field in a dialog (e.g, "Password, Object Type, Userid, etc.,"). Regardless of the language, when we describe the UI, the descriptions of the UI text in the docs must match the text used in the UI.  E.g, If the field label is User Name, it can't call it anything else.

Our main objection to pre-processing the entities/xincludes before translation is that the connection to the software strings would be lost for all non-English languages. In a perfect world, the software resources would all be translated and locked down before translation of the docs takes place. However, this is not always possible. If we preprocessed the docs before we sent them to be translated, we'd have to manually update them for each language each time a software resource changes.

Xincludes, like entities, also are not able to be expanded by the translation software. So, our translators only see the xinclude element.  
For this reason, we have intentionally limited our use of xincludes to content that can stand on its own (e.g., descriptions of clauses, sections,notes, procedures, etc., ).
From what I understand, most translation software editors are not full XML editors (hence they don't expand entities nor xincludes).

Currently, we are exploring the feasibility of defining attributes for guilabel within our own namespace
Example:  <guilabel ias:targetfile="..."  ias:targetptr="....">Software Text</guilabel>

Thanks again,



Sybase 25 Year Anniversary logo Kate Wringe | Tech Writer 2| Sybase
445 Wes Graham Way, Waterloo, ON, N2L 6R2 Canada | Tel: (519) 883-6838 | kate.wringe@sybase.com | www.sybase.com


David Cramer <dcramer@motive.com>

01/30/2010 02:23 PM

<Steven.Cogorno@Sun.COM>, "Bob Stayton" <bobs@sagehill.net>
<Kate.Wringe@sybase.com>, <docbook@lists.oasis-open.org>
RE: [docbook] Entities vs olinks

Even with English, you have to be careful with entities (or any
programmatic text replacement mechanism). Consider a case of a product
named "ACME server" that's rebranded as "FOOBAR server" and the sentence
"If you have installed an &ProductName; on the host..." The word "an" is
fine when &ProductName; resolves to "ACME server" but is wrong when it
resolves to "FOOBAR server". I know French and German have words that
contract in differnet ways depending on the gender of the noun, e.g. "de
la" v. "du" (instead of "de le"). I'm sure other langages have quirks
I've never imagined. For this reason and others we also preprocess docs
that we send to be translated.

In addition to resolving entities and pruning <remark>s, comments, and
internal content, the xslt does some pretty printing. The goal is to
avoid a situation where the editor might introduce whitespace that might
confuse the translation tool and cause it to fail to match segements
from the translation memory. We also flag certain content (e.g.
programlisting, filename, database, code) as non-translatable. For
exceptions, the writer flags them as translatable before we run the l10n
prep script. This can dramatically reduce the word count and so
translation cost. The vendors seem happy to quote you a price based on a
word count of 10000 words and not make any allowance for the fact that a
sizable fraction of those words are in code listings that they won't
ever touch.


> The most important reason why I think direct text expansion
> *before* translation is the optimal solution is because the
> translation of the entity text itself often depends on the
> surrounding text. Phrases or words that can be used in
> multiple contexts within English documents often won't make
> sense in a translated document. If the entity has been
> expanded to plain text *before* translation, then the
> translator can alter the text as needed in each context.  But
> if OLink or some other replacement is done *after*
> translation, there can only be one replacement per entity,
> regardless of context.
> Hopefully that makes sense. Sorry I didn't give more
> background before...

To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]