LILYPOND DOCUMENTATION TRANSLATION


SOURCES

The sources live in a GIT repository.  Git 1.4.4.1 or newer is
required, and Git 1.5.x is highly recommended.  To get a fresh version
run

    mkdir lily ; cd lily
    git init-db
    git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/lilypond/translation:lilypond/translation
    git checkout -b mytranslations lilypond/translation


GIT

The reader is supposed to be familiar with Git, for example by
having experience from lilypond.org translation; see
http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=README;hb=web/master


REQUIREMENTS

Working on LilyPond documentation translations requires:

    * python
    * make
    * gettext


STARTING A TRANSLATION IN A NEW LANGUAGE

At top of the source directory, do

    ./autogen.sh

or (if you want to install your self-compiled LilyPond locally):

    ./autogen.sh --prefix=$HOME

If you want to compile LilyPond -- which is almost required to build
the docs, but is not required to do translation only -- fix all
dependencies and rerun ./configure (with the same options as for
autogen).

Cd into Documentation and run:

    make ISOLANG=<MY-LANGUAGE> new-lang

where <MY-LANGUAGE> is the ISO 639 language code.

Add a language definition for your language in
buildscripts/langdefs.py.

See next section about what files to translate and the following
detailed instructions after the next section.

FILES TO BE TRANSLATED

All the following files are in Documentation/
Translation of Documentation/foo/bar should be
Documentation/<LANG>/foo/bar.
Unmentioned files should not be translated.

Priorities:  1. delivery, 2. 3. 4. 5. later, 6. optional.

Files marked with priority 3, 4 or 5 may be submitted individually.

-1- Documentation index, Tutorial and Cheat Sheet
1 user/lilypond.tely
1 user/tutorial.itely
1 user/dedication.itely
1 user/cheatsheet.itely
1 index.html.in
  po/<MY-LANGUAGE>.po

-2- User manual introduction
2 user/preface.itely
2 user/introduction.itely

-3- Learning manual
3 user/putting.itely -- Putting it all together
3 user/working.itely -- Working on LilyPond files
3 user/tweaks.itely -- Tweaking output

-4- Notation reference
4 user/basic-notation.itely -- Basic notation
4 user/instrument-notation.itely -- Instrument-specific notation
4 user/advanced-notation.itely -- Advanced notation
4 user/changing-defaults.itely -- Changing defaults
4 user/non-music.itely -- Non-musical notation
4 user/spacing.itely -- Spacing issues
4 user/programming-interface.itely -- Interfaces for programmers
4 user/scheme-tutorial.itely -- Scheme tutorial

-5- Program usage
5 user/running.itely -- Running LilyPond
5 user/lilypond-book.itely -- LilyPond-book
5 user/converters.itely -- Converting from other formats

-6- Appendices whose translation is optional
6 user/literature.itely
6 user/templates.itely
6 user/notation-appendices.itely

* WORD COUNTS FOR CATEGORIES

LANG=C wc --words $(grep ^1 TRANSLATION | cut -d ' ' -f 2)
  777 user/lilypond.tely
 6322 user/tutorial.itely
   63 user/dedication.itely
  632 user/cheatsheet.itely
  361 index.html.in
 8155 total

LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2)
  451 user/preface.itely
 4170 user/introduction.itely
 4621 total

LANG=C wc --words $(grep ^3 TRANSLATION | cut -d ' ' -f 2)
 2230 user/putting.itely
 3232 user/working.itely
 2327 user/tweaks.itely
 7789 total

LANG=C wc --words $(grep ^4 TRANSLATION | cut -d ' ' -f 2)
 12391 user/basic-notation.itely
 15779 user/instrument-notation.itely
  9530 user/advanced-notation.itely
  7386 user/changing-defaults.itely
  3884 user/non-music.itely
  8318 user/spacing.itely
  4781 user/programming-interface.itely
   915 user/scheme-tutorial.itely
 62984 total

LANG=C wc --words $(grep ^5 TRANSLATION | cut -d ' ' -f 2)
 3566 user/running.itely
 3549 user/lilypond-book.itely
 1062 user/converters.itely
 8177 total

LANG=C wc --words $(grep ^6 TRANSLATION | cut -d ' ' -f 2)
  339 user/literature.itely
 4648 user/templates.itely
  836 user/notation-appendices.itely
 5823 total


TRANSLATION DETAILED INSTRUCTIONS

Please follow all these instructions with care to ensure quality work.

All files should be encoded in UTF-8.

* USER MANUAL

Any title which comes with one of the following commands must not be
translated directly in the Texinfo source

@node          @top                                     @majorheading
@chapter       @unnumbered          @appendix           @chapheading
@section       @unnumberedsec       @appendixsec        @heading
@subsection    @unnumberedsubsec    @appendixsubsec     @subheading
@subsubsection @unnumberedsubsubsec @appendixsubsubsec  @subsubheading
@ref           @rglos

As a notable exception, the second argument 'Bar baz' of
@ref{Foo,'Bar baz',,info-file} should be translated.

In any section which looks like

@menu
* node1:: thing1
* node2:: thing2
...
@end menu

the node names (nodeN) are NOT to be translated, whereas extra title
information (thingN) is.


Every node name or section title must from now on be translated
separately in a .po file (just as well as LilyPond output messages).
This .po file should be in Documentation/po.

Make sure to keep *verbatim* copies of music snippets (in @lilypond blocs).
@example blocs do not have to be verbatim copies, e.g. variable names,
file names and comments should be translated.

Index entries (@cindex and so on) should be translated.

Carefully apply every rule exposed in Documentation/README.txt.  If
one of these rules conflicts with a rule specific to your language,
please ask the Translation meister and/or the Documentation Editor on
lilypond-devel@gnu.org.


* DOCUMENTATION INDEX index.html.in

Unlike almost all HTML pages in this documentation, links in this page
are not tweaked by add_html_footer.py, so links should be manually
edited to link to existing translations.


CHECK STATE OF TRANSLATION

First pull, then cd into Documentation (or at top of the source tree,
replace 'make' with 'make -C Documentation') and run

    make ISOLANG=<MY_LANGUAGE> check-translation

This presents a diff of the original files since the most recent
revision of the translation.  To check a single page, run

    buildscripts/check-translation.py Documentation/user/<MY-LANGUAGE>/foo/bar.itely



UPDATE A TRANSLATION

Texinfo skeleton files, i.e. .itely files not yet translated,
containing only the Texinfo structure can be updated automatically:
whenever 'make check-translation' shows that such files shouldbe
updated, run from Documentation

    make ISOLANG=<MY_LANGUAGE> skeleton-update

.po message catalogs in Documentation/po may be updated with (from
Documentation or Documentation/po)

    make po-update



TECHNICAL BACKGROUND

A number of Python scripts handle a part of the documentation
translation process:

langdefs.py  -- language definitions
check_translation.py  -- show diff to update a translation
texi-langutils.py  -- quickly and dirtily parse Texinfo files to
make message catalogs and Texinfo skeleton files
texi-skeleton-update.py -- update Texinfo skeleton files
html-gettext.py -- translate node names, section titles and cross
references in HTML files generated by makeinfo
add_html_footer.py (module called by www_post.py) -- add footer and
tweak links in HTML pages
