Update translations status

[lilypond.git] / Documentation / TRANSLATION

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
of LilyPond sources 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


WHICH DOCUMENTATION CAN BE TRANSLATED

The makfiles and scripts infrastructure currently supports translation
of the following documentation:

    * documentation index (HTML)
    * user manual and program usage -- Texinfo source, PDF and HTML
output; Info output might be added if there is enough demand for it.


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.
Word counts (excluding lilypond snippets) are given for each file.

-1- Documentation index and Tutorial
396   user/lilypond-learning.tely
5593  user/tutorial.itely
23    user/dedication.itely
216   index.html.in
2022  po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
8250  total

In addition, user/macros.itexi may be translated in case typographic
rules used in this file are different in your language.

-2- Introduction and beginning of Application Usage
411   user/preface.itely
3198  user/introduction.itely
374   user/lilypond-program.tely
1477  user/install.itely (partial translation)
947   user/setup.itely
2860  user/running.itely
9267  total

-3- Learning manual
8626  user/fundamental.itely -- Fundamental concepts
12134 user/tweaks.itely -- Tweaking output
2985  user/working.itely -- Working on LilyPond files
483   user/templates.itely -- Templates
24228 total

-4- Notation reference
539   user/lilypond.tely
91    user/notation.itely -- Musical notation
2808  user/pitches.itely
7336  user/rhythms.itely
1681  user/expressive.itely
725   user/repeats.itely
916   user/simultaneous.itely
1861  user/staff.itely
879   user/editorial.itely
2336  user/text.itely
54    user/specialist.itely -- Specialist notation
2630  user/vocal.itely
1275  user/chords.itely
702   user/piano.itely
481   user/percussion.itely
826   user/guitar.itely
66    user/strings.itely
242   user/bagpipes.itely
4289  user/ancient.itely
2458  user/input.itely -- Input syntax
2164  user/non-music.itely -- Non-musical notation
8399  user/spacing.itely -- Spacing issues
5149  user/changing-defaults.itely -- Changing defaults
4547  user/programming-interface.itely -- Interfaces for programmers
935   user/notation-appendices.itely -- Notation manual tables
250   user/cheatsheet.itely -- Cheat sheet
53639 total

-5- Application usage
2917  user/lilypond-book.itely -- LilyPond-book
975   user/converters.itely -- Converting from other formats
3892  total

-6- Appendices whose translation is optional
299   user/literature.itely
960   user/scheme-tutorial.itely (needs to be revised first)
1259  total


TRANSLATION DETAILED INSTRUCTIONS

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

All files should be encoded in UTF-8.

* LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION

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

@node                                                   @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.

@uref's names are to 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.


Please keep verbatim copies of music snippets (in @lilypond blocs).
However, some music snippets containing text that shows in the
rendered music, and sometimes translating this text really helps the
user to understand the documentation; in this case, and only in this
case, you may as an exception translate text in the music snippet, and
then you must add a line immediately before the @lilypond block,
beginning with

@c KEEP LY

Otherwise the music snippet would be reset to the same contents as the
English version at next 'make snippet-update' run (see UPDATING A
TRANSLATION below).

When you encounter

  @lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}

in the source, open input/lsr/FILENAME.ly, translate the texidoc
string it contains, enclose it with 'texidoc<MY-LANGUAGE> = "' and
'"', and write it into input/texidocs/FILENAME.texidoc -- please keep
possibly existing translations in other languages!  For instance,
input/texidocs/FILENAME.texidoc may contain

texidoces = "
Spanish translation blah
"
texidocde = "German translation foo
"


@example blocs need not 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.


* REFERENCE NOTATION AND PROGRAM USAGE MANUAL

Copy user/lilypond.tely (or user/lilypond-program.tely, respectively)
into <MY-LANGUAGE>/user, then translate this file and run
skeleton-update (see UPDATE A TRANSLATION below).  Your are now ready
to translate notation reference (program usage manual, respectively)
exactly like the learning manual.


* 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 file, cd into
Documentation and run

    make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely check-translation


Small tip: to see only which files need to be updated, do

    make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'


Global state of the translation is recorded in
Documentation/translations.html.in, which is used to generate
Translations status page.  To update that page, do from Documentation/

    make translation-status

This will also leave out/translations-status.txt, which contains
up-to-dateness percentages for each translated file.


UPDATE A TRANSLATION

Instead of running check-translation, you can run update-translation,
which will run your favorite text editor to update files.  First, make
sure environment variable EDITOR is set to a text editor command, then
run from Documentation

    make ISOLANG=<MY-LANGUAGE> update-translation

or to update a single file

    make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely update-translation

For each file to be udpated, update-translation will open your text
editor with this file and a diff of the file in English; if the diff
cannot be generated or is bigger than the file in English itself, the
full file in English will be opened instead.

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 should be
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

WARNING: if you run po-update and somebody else does the same and
pushes before you push or send a patch to be applied, there will be a
conflict when you pull.  Therefore, it is better that only the
Translation meister runs this command.

Updating music snippets can quickly become cumbersome, as most
snippets should be identical in all languages.  Fortunately, there is
a script than can do this odd job for you (run from Documentation):

    make ISOLANG=<MY_LANGUAGE> snippet-update

This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
with music snippets from user/every.itely.  It ignores skeleton files,
and keeps intact music snippets preceded with a line starting with '@c
KEEP LY'; it reports an error for each .itely that has not the same
music snippet count in both languages.

Finally, a command runs the three update processes above for all
enabled languages (from Documentation):

    make all-translations-update

This command is mainly intended to be used by the Translation meister.


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
* texi-gettext.py -- gettext node names, section titles and references
before calling texi2pdf
* mass-link.py -- link or symlink files between English documentation
and documentation in other languages
* update-snippets.py -- synchronize ly snippets with those from
English docs
* translations-status.py -- update translations status pages and word
counts in the file you are reading