Using gnome-doc-utils for help files

Leonardo Fontenelle leo.fontenelle at gmail.com
Thu Jul 5 19:10:40 EDT 2007


As a GNOME translator, I can say translating documentation with PO
files is _much_ better than editing XML files.

I agree PO files are much more handy when translating user interface,
but editing XML files isn't any better. The translation tools (or
vim/emacs/etc. po-mode) allow us to focus on the actual text, not on
the document structure.

I never ran into a GNOME document which paragraphs I needed to merge
of split. Sometimes I think I would have structured the text
differently, but that's not locale-specific. I never translated
GnuCash documentation, but from what I read I believe I wouldn't have
any problem using gnome-doc-utils with it.

One advantage of gettext translation is that, if I translate the hole
document and a documenter changes a paragraph, the rest of the
document is still translated and only that paragraph will be shown in
English. The lack of this features makes translators avoid translating
man pages, for instance.

I agree sometimes it's hard to spot where the message was changed,
specially if it's a long paragraph. There ways to circunvent this,
however:

1. You may run wdiff (http://www.gnu.org/software/wdiff/) between
previous and current original message, and add the output to the
comments.
2. You could adopt gettext 0.16 and use the --previous function in msgmerge

I never saw a project using any of these, and I don't know if they are
easy to implement. Between gnome-doc-utils without the tricks above
and plain XML editing, I prefer the former.

Maybe that's all because I'm used to gnome-doc-utils, but honestly
I'll try to use xml2po (from gnome-doc-utils) even if I'll have to
build XML latter to commit it.

Leonardo Fontenelle
http://leonardof.org/2007/07/01/gnome-user-guide-completely-translated-to-brazilian-portuguese/en/

2007/7/5, Pierre-Antoine <pa.lacaze at gmail.com>:
> Christian Stimming a écrit :
> > Am Donnerstag, 5. Juli 2007 16:16 schrieb Josh Sled:
> >
> >> Pierre-Antoine Lacaze <pa.lacaze at laposte.net> writes:
> >>
> >>> I'm beginning the French translation of Gnucash's help, and have been
> >>> suggested that it would be a good move to look into converting
> >>> gnucash-help to gnome-doc-utils [1]. g-d-u is supposedly the preferred
> >>> way for documentation handling, and make use of po files.
> >>>
> >
> > Without having looked too much into g-d-u details I'd *strongly* adverse
> > moving our user documentation to po files! Po files are great for smaller
> > chunks of translations which can be translated more or less independent from
> > one another. Our documentation, with the "Guide and Concepts" being the best
> > part of it all, is clearly not at all translatable in a
> > paragraph-by-paragraph way, independently of one another.
> >
> > Also, one of the largest advantages of po files, which is the easy
> > visualization of changed strings, becomes moot if these strings are longer
> > than 1-2 lines. For longer strings, po only says "this whole paragraph has
> > changed in *some* way", whereas .xml or .sgml or even .txt would give you a
> > diff showing the exact line that changed. (Diffs are not possible for po.)
> >
> > IMHO the arbitrary division of the help documents into separate po strings
> > doesn't offer any advantage at all. I don't agree with this being "a
> > preferred way". Well, maybe for a subset of user documentation: This *might*
> > be suitable to the kind of help you'd expect when pressing F1 somewhere,
> > which gives you 2-3 sentences about what is currently going on. But this is
> > not at all suitable for our large Guide document.
> >
> >
> >>> I more or less ported it already, and would like to know if there is a
> >>> compelling reason not to move over.
> >>>
> >>> I fear myself with po files the lack of flexibility required in highly
> >>> technical, country-specific documentation.
> >>>
> >
> > If you still think this might be interesting, then I'd be interested to see
> > the .pot file that comes out of the g-d-u conversion (or part of it). I would
> > clearly recommend against it, though.
> >
> > Regards,
> >
> > Christian
> >
>
> I suspected so, and pot files indeed look scary and unusable.
>
> Does someone know a good way of handling big doc translation in a
> collaborative fashion, without resorting to hard to use tools ? I know
> of a wiki engine capable of editing docbooks, or exporting to docbooks.
>
> -- Pierre-Antoine
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>



More information about the gnucash-devel mailing list