Re: Doc Translations

[Shaun McCance <shaunm gnome org>]

On Mon, 2004-09-13 at 07:55, Karl Eichwalder wrote:
> danilo gnome org (Danilo Åegan) writes:
> 
> Your approach is very interesting and quite clean.
> 
> > Another drawback of xml2po is that it cannot cope with some fancy
> > usage of XML entities (eg. entities are declared in one, toplevel
> > file, but used in another; I can solve this easily if I sacrifice
> > ability to merge file-by-file, and simply output entire translation
> > into one XML file, and Python libxml2 bindings would probably need
> > some extensions to allow for the proper fix).
> 
> There is another issue with entity resolution.  Usually one want to
> preserve those in the original and the translation - but things like 
> 
> <!ENTITY appversion "2.1.6">
> <!ENTITY manversion "2.1.0">
> <!ENTITY app "Bug Buddy">
> ...
>        <para>
>           <application>&app;</application> is a tool which
>           will guide you through making a bug report as painlessly as possible.          You can alter things at any stage, and then either send, save, or
>           abandon the resulting report. This document describes
>           version &appversion; of <application>&app;</application>: note that
>           it has changed substantially in appearance from earlier versions.
>         </para>
> 
> will get resolved to their literal values in the .pot file:
> 
> #: two.xml:15
> msgid ""
> "<application>Bug Buddy</application> is a tool which will guide you through "
> "making a bug report as painlessly as possible. You can alter things at any "
> "stage, and then either send, save, or abandon the resulting report. This "
> "document describes version 2.1.6 of <application>Bug Buddy</application>: "
> "note that it has changed substantially in appearance from earlier versions."
> 
> This will cause unnecessary fuzzies once entity vulues change.

These entities are just a typing convenience.  We could just as well put
<application>Bug Buddy</application> in all of the English docs.  If we
had to chagne the name of the application, we'd do a search and replace,
and you'd still have the same fuzziness.  Really, changes to the entity
values should be treated no differently than any other string change in
the documentation.

SYSTEM entities concern me much more.  My proposal is (and has been for
quite some time) that we use XInclude for all subdocument inclusions. 
So if we split a document into multiple files on chapter boundaries, we
would use XInclude rather than SYSTEM entities to include these.  This
would also be done for the boilerplace legal.xml that contains the GFDL
legalnotice in all our documentation.

Each XML document would then be well-formed.  If they each need to have
certain entities defined (appversion, app, etc.) then they can define
those entities.  This doesn't bother XInclude at all, whereas it does
mess up SYSTEM entity inclusion.  Better yet, these common entities can
be put in a config.ent file, which can be included in each XML document.
In fact, a clever build tool could create config.ent automatically for
each language.

Additionally, there's no reason translators should have to translate the
GFDL legalnotice in every single document.  A clever build tool could
ship with translated legal.xml files, and automatically copy them into
each language's directory.

--
Shaun