Re: [docbook-apps] Preserving entities and language translation

[Shaun McCance <shaunm@gnome.org>]

Hi Warren,

I'm not sure if you've successfully made the switch to itstool yet for
your PO round-tripping. I think we talked a bit about entity expansion
at the Open Help Conference last year.

The default behavior in itstool is that it expands entities, but does
not do XInclude. So I recommend using entities for words, phrases, and
other mid-sentence substitutions. Use XInclude for entire blocks or
sections.

The idea is that translators have a difficult time with mid-sentence
substitutions when they need to do inflections and declensions on words.
For example:

<!ENTITY b "button">
<para>Click the &b;.</para>
<para>The &b; is blue.</para>

A translator can't reliably translate this without entity substitution,
because she might need to translate "button" differently in each case.
You can override this with the -k option, but I don't recommend it.

If we could somehow figure out which entities are inline and which are
block-level, that might help. Perhaps not expanding SYSTEM entities
(likely used for large blocks), expanding regular entities (likely used
for words and phrases), and expanding SYSTEM parameter entities (likely
used to pull in entity definitions). I don't know if libxml2's API
allows for that. libxml2 can do a lot that xmllint doesn't expose.

--
Shaun

On Mon, 2016-01-18 at 21:42 -0700, Warren Block wrote:
> Some of the articles in the FreeBSD documentation use entities to 
> include large blocks of data.  For example, one article is just a very 
> large list of PGP keys for developers: 
> https://www.freebsd.org/doc/en_US.ISO8859-1/articles/pgpkeys/index.html
> 
> The DocBook article.xml is only 2K, because it does things like this:
> 
>    <sect1 xml:id="pgpkeys-officers">
>      <title>Officers</title>
> 
>      &section.pgpkeys-officers;
>    </sect1>
> 
> We use xmllint to normalize the article into a single XML file for use 
> with PO translation tools.  Of course, all entities are expanded into 
> text at that point.
> 
> It would be really nice to mark that particular entity as one that 
> should be preserved in the translated file.  Is it possible to do that 
> with processing instructions or some other method?  For example:
> 
>    <sect1 xml:id="pgpkeys-officers">
>      <title>Officers</title>
> 
>      <?translate off?>
>      &section.pgpkeys-officers;
>      <?translate on?>
>    </sect1>
> 
> In the normalized file, it could be a string to indicate to translators 
> that it should be left alone:
> 
>    <sect1 xml:id="pgpkeys-officers">
>      <title>Officers</title>
> 
>      <?translate off?>
>      do not translate: section.pgpkeys-officers
>      <?translate on?>
>    </sect1>
> 
> Of course, it has to be changed back when the translated XML file is 
> generated.
> 
> Is there a standard or elegant way to do this?
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>