Re: documentation translation

[John Mandereau]

Han-Wen Nienhuys wrote:
> Ludovic Sardain escreveu:
> > Hello,
> > 
> > As you know, we are a small team of french translators, and for some
> > months, we're not doing anything, because none of us has understood
> > how to compile the documentation. There's also some problem about
> > whereas we must translate or not the nodes titles.
> 
> Jan and I have been working very hard over the last days to give our 
> build infrastructuer an update. It should be possible, in the short run, 
> to have an almost-single-button-push   method of compiling the documentation
> 

By "build infrastructure", do you mean the git repository? Do you plan
to replace cvs with git for the main (read/write) repository on
savannah.gnu.org?


Besides that, the growing number of people on address@hidden
asking for a French translation of the docs, or offering to participate
in doing it has (finally) urged me to have a look at the makefiles
infrastructure.

So, here's a [LONG] follow-up of
http://lists.gnu.org/archive/html/lilypond-devel/2005-09/msg00036.html

Jan Nieuwenhuizen wrote: 
> John Mandereau writes:
> 
> > Does it mean that that the node names cannot be translated? (Or have I
> > not understood well what you explained?)
> 
> Yes, that's what I meant.  I'm not 100% sure this is the best way, but
> this is what I'd like to try first.  What we'd do is (excuse les mots)
> 
>    @node First steps
>    @section Premier etapes
> 
> and
> 
>    @menu
>    * First steps::                 Premiere etapes
> 
> That would result in web pages:
> 
>     Documentation/user/out-www/lilypond/First-steps.html
>     Documentation/user/out-www/lilypond/First-steps.fr.html
> 
> Having the same html file names could be an advantage, I guess; it
> would be a lot easier to switch and compare different languages, and
> see what other languages are available for that page, just like the
> main web site.  I'm not sure about the usability of the INFO docs,
> where you'd have to use English node names.

It's important to have the same html filenames, but the node names
should be translated, otherwise all that hard translation work is not
very worthy imho.

Why not gettext node names? I mean that a script could collect all node
names from the .(i)tely files and write them to a po file, then (after
the html docs have been generated) another script could replace the node
names with regexp substitutions (like "<title>[node name] - GNU
LilyPond</title>" or "<a href=".*">[node name]</a>").

These two scripts are fairly easy to write in Python (I've already
almost written the first one).


> I would just like to see the effect/usability of this after having
> translated a few pages, and see if that's the right way to continue,
> or whether we have to think of something else.

I have tested Jan's makefile (see patch from
http://lists.gnu.org/archive/html/lilypond-devel/2005-09/msg00017.html )
against latest tutorial French translation: it works except that I had
to do some minor corrections, and PNG symlinks to PNGs of English pages
don't work.


Before dealing with any concrete code, I would like to have the opinion
of the main hackers on the goal and the main technical aspects of
translating the docs.

IMHO it's useful to translate the whole user manual, because:
- it is the part of the documentation where there is most explanation
blurb, and so it is the part of the documentation where translation is
most useful and (technically speaking) doable (unlike the program
reference, for example).
- we are enough translators to achieve this in a reasonnable time: it
took 3 translators 3 months to translate lilypond.org, and I guess there
are at least as many translators ready to start working.

Documentation today is available both on-line and in a tarball, and
AFAIK the same files are used for both forms. If we want content
negociation (i.e. automatic language selection) for the docs on
lilypond.org, this will no longer be possible. I really like content
negociation, mainly because it requires almost no user intervention.

Regarding handling of HTML files, the most useful for both forms is
certainly to hard link Documentation/user/*.LANG.html to
Documentation/LANG/(user/)*.html, just like Jan's patch does.

Then, for the on-line docs on lilypond.org, .html extensions should be
stripped in all hrefs so that content negociation works, and a footer
about automatic language selection and available languages should be
added like on lilypond.org main site.

For the tarball docs, I think the best solution is to generate one
tarball per language: for languages other than English, *.LANG.html
files should be renamed to *.html, and html pages which have no
translation should be packed into the tarball too.


Regarding ly snippets, there are 2 possibilities:

1) PNGs and code snippets from the English docs are used for the
translated docs through symlinks. The main advantage is that translated
docs don't take too much time to make and don't take too much disk space
on lilypond.org.

2) ly snippets in translated docs are totally independent from ly
snippets from untranslated docs. This has 2 advantages: it is easier to
write the makefiles and it makes the snippets translatable, which is
nicer for the end-user (texts and maybe pitch names could be
translated).

I prefer #2 over #1. Maybe we could ask end users on lilypond-user-fr to
give their preference?


Regarding translation maintaining, as the current maintainer of
lilypond.org French translation, I'm happy with check-translation, so we
could use almost the same script to maintain the user manual
translation. But to avoid to maintain already translated stuff while
doing the main translation work, and possibly to make translation
available for 2.10 before the next stable release, I think it's better
we stick with 2.10, and update to the development branch only when
everything is translated.


Please comment so I (we?) can work further on the translation
infrastructure and try to submit real code.

Cheers,
-- 
John Mandereau <address@hidden>