[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Debian Policy released: localized manpages

On Sun, 16 Aug 2009 16:31:09 +0800
Paul Wise <pabs@debian.org> wrote:

> On Sun, Aug 16, 2009 at 3:49 PM, Christian Perrier<bubulle@debian.org> wrote:
> > Before people "blindly" update their Standards-Version, I deeply
> > suggest looking at this item:
> >
> >>   * Localized man pages should either be kept up-to-date with the
> >>     original version or warn that they're not up-to-date, either with
> >>     warning text or by showing missing or changed portions in the
> >>     original language.                                        [12.1]
> >
> > *many* packages do provide localized manpages where l10n is handled
> > "manually" (the translated manpages are just a copy of the original
> > ones....where English is manually replaced by the said language). With
> > such setup, it is nearly impossible to guarantee that the localized
> > manpage is in sync with the original one.
> Could the i18n team write something about the technical details of
> doing translated manual pages the "right way" that could be shown to
> upstreams and promoted via lwn.net, blogs and similar? I wanted to do
> translated manual pages for chromium-bsu upstream but not knowing how
> to do it properly prevented me from doing it at all.


I did start such a guide via my blog during DebConf8


The key is to generate the manpages from whichever format you prefer
and then use po4a to arrange that the format bears the translation. The
generation of the manpages is then independent of the language of that
translation and the translated content itself comes from typical PO
files with which translators are already familiar.

This makes it much the same method as other translations:
1. Upstream changes the English text for a new release
2. Build system processes the English and generates a POT file
containing the updated strings, merges those strings with any existing
PO files and creates an output format of a type chosen by upstream that
contains those strings that can be translated along with any modified
strings that are awaiting translation. i.e. a mixed document that
clearly complies with Policy. This is basically scripting po4a to work
with the paths to the files containing the strings for translation.
3. The (temporary) generated files are then processed by po4a within the
normal build system to generate not only the English manpages but also
whichever translations carry enough translated strings to exceed some
threshold value - often 70%. The actual value is configurable. Note
that each string is quite long - I can't remember if it is 70% of the
number of strings independent of length or 70% of the total length of
the strings.
4. The modified POT file and any existing PO file is sent for
translation updates - necessarily, this process needs to be allowed
more time than a string freeze for debconf or program string
translation due to the number and length of the strings. e.g.
emdebian-tools manpages created a POT file with 3,500 strings at one
point, each string being maybe 50 words. Translations that fail to
exceed the threshold will not have any translated manpages generated.
Translations that are between the threshold and 100% will have some
sentences in English and only unchanged sentences translated.
5. Updated PO files are put into the relevant po/ directory upstream,
the final release tarball is built and/or po/ files are patched with
updates etc..

That being said, translating manpages is a different issue to
translating debconf strings or even program translations - the sheer
size of each string and the number of strings in total makes updating
and maintaining those translations into quite a burden.


Neil Williams

Attachment: pgp3maRTMHMq7.pgp
Description: PGP signature

Reply to: