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,

Kate

..........................................................................................................................................................................................................................

Kate Wringe | Tech
Writer 2| Sybase

445 Wes Graham Way, Waterloo, ON, N2L 6R2 Canada | Tel: (519) 883-6838
|  | www.sybase.com 

 

David Cramer <>

01/30/2010 02:23 PM

To

<>,
"Bob Stayton" <>

cc

<>,
<>

Subject

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. 

David

> 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: 

For additional commands, e-mail: