Re: Fwd: manpage i18n miniproject

[James Youngman]

On Thu, May 26, 2005 at 01:39:19AM +0930, Clytie Siddall wrote:

> I gather this has been discussed in the past, but perhaps not  
> followed through. As an initial stage, I have translated the find(1)  
> manpage into Vietnamese. 

Thanks for your contribution.

> What would you see as an effective model for localizing and  
> distributing the resulting manpages? We are willing to adapt to fit  
> the GNU processes, and very much want to produce excellent pieces of  
> documentation for our user communities.

As I am sure you are aware, the GNU project's policy is that Texinfo
format documentation is preferable to manual pages (only).  The GNU
project would prefer it if maintainers spent time on improving the
Texinfo documentation rather than the manual pages.  However, I, like
almost all the GNU maintainers, am a volunteer and therefore choose
how to spend my time.  I elect to spend my time keeping the manual
pages up to date (as well as the Texinfo documentation).  

The existing Translation Project process is very convenient for GNU
maintainers because

1. All submissions are pre-filtered to ensure that only contributions
   by people who haveprovided a copyright assignment go through to the 
   maintainer.  From the maintainer's point of view, this is the most
   valuable thing the TP does, because soliciting and managing copyright 
   assignments is time consuming and not much fun.  

2. The contributions themselves are just single downloadable files, and 
   all the maintainer does is upload the template file and download the 
   translations.  I use wget for this when I get the automated email from 
   the TP, using a process something like this...

        cd source-dir/po
        if rm ${pofile} ; then
                if wget http://......../${pofile} ; then
                        cd build-dir/po
                        make update-po
                        cd source-dir/po
                        cvs -z3 commit -m "Updated ${pofile%%.po} translation" 
${pofile}
                else
                        # failed, get the old one back
                        cvs -z3 update fr.po
                fi
        else
                # new translation
                echo "Please add ${pofile} manually.  Don't forget to update 
ALL_LINGUAS"
                exit 1
        fi
        
3. The maintainer's update process is simple - just sending one email; 
   the TP automation takes care of downloading the new tar file and 
   extracting the updated POT file.

Process-wise, the main problem as I see it is that this process might
not scale terribly well to having N translations of M manual pages.  I
don't want to have to upload all the manual pages to a TP robot every
time I update a manual page, or send separate emails for the pot file
and all the manual pages.  I suppose I'd rather work with you to find
a way of automating this part of the maintainer's process.

I'm not sure what the right answer is there.  I'm not keen on putting
a script in the findutils CVSROOT that informs the TP of manual page
changes, because I'm not sure if the machine that hosts the CVS
repositories (savannah.gnu.org) is really intended to generate lots of
automated email.  If the GNU project is OK with that happening, that
woudl presuably be the simplest way.  A "TP manual page robot" could
then use anonymous CVS to pull the updated version of the file and
inform translators.

Unfortunately I don't think this would work for some of the other GNU
projects (for example coreutils) since the CVS repository that gets
updated when the developers change the code is not available online
for anonymous CVS access (there is an anonymous CVS repository but as
I understand things it would not get updated until a short time
later).

> I will write a brief report on the process for the initial manpage,  
> including testing and feedback, and when the second stage is  
> complete, with several more manpages translated, tested and being  
> used, I will write an initial guideline for other language  
> communities to use when translating manpages. Thus your place in the  
> process is crucial. I look forward to hearing your ideas on how this  
> should be done, and hopefully, to my language community working with  
> you longterm on localizing manpages.

I'm happy to work with you to achieve this, as long as the total
effort overhead of managing the manual pages is not significantly
greater than the overhead effort of managing the po-files.


> I'll look forward to hearing from you about this. It's a worthwhile  
> project, IMHO.

Please be aware though that medium term plans for findutils include
significant updates to the manual pages (see
http://savannah.gnu.org/patch/?func=detailitem&item_id=3775).

Thanks,
James Youngman.