Documentation/TRANSLATION

   1 LILYPOND DOCUMENTATION TRANSLATION
   2
   3
   4 SOURCES
   5
   6 The sources live in a GIT repository.  Git 1.4.4.1 or newer is
   7 required, and Git 1.5.x is highly recommended.  To get a fresh version
   8 run
   9
  10     mkdir lily ; cd lily
  11     git init-db
  12     git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/master:remotemaster
  13     git checkout -b master remotemaster
  14
  15
  16 GIT
  17
  18 The reader is supposed to be familiar with Git, for example by
  19 having experience from lilypond.org translation; see
  20 http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=README;hb=web/master
  21
  22
  23 REQUIREMENTS
  24
  25 Working on LilyPond documentation translations requires:
  26
  27     * python
  28     * make
  29     * gettext
  30
  31
  32 STARTING A TRANSLATION IN A NEW LANGUAGE
  33
  34 At top of the source directory, do
  35
  36     ./autogen.sh
  37
  38 or (if you want to install your self-compiled LilyPond locally):
  39
  40     ./autogen.sh --prefix=$HOME
  41
  42 If you want to compile LilyPond -- which is almost required to build
  43 the docs, but is not required to do translation only -- fix all
  44 dependencies and rerun ./configure (with the same options as for
  45 autogen).
  46
  47 Cd into Documentation and run:
  48
  49     make ISOLANG=<MY-LANGUAGE> new-lang
  50
  51 where <MY-LANGUAGE> is the ISO 639 language code
  52
  53 Add a language definition for your language in
  54 buildscripts/langdefs.py.
  55
  56 See next section about what files to translate and the following
  57 detailed instructions after the next section.
  58
  59 FILES TO BE TRANSLATED
  60
  61 All the following files are in Documentation/
  62 Translation of Documentation/foo/bar should be
  63 Documentation/<LANG>/foo/bar.
  64 Unmentioned files should not be translated.
  65
  66 Priorities:  1. delivery, 2. 3. 4. 5. later, 6. optional.
  67
  68 Files marked with priority 3, 4 or 5 may be submitted individually.
  69
  70 -1- Documentation index, Tutorial and Cheat Sheet
  71 1 user/lilypond.tely
  72 1 user/tutorial.itely
  73 1 user/dedication.itely
  74 1 user/cheatsheet.itely
  75 1 index.html.in
  76
  77 -2- User manual introduction
  78 2 user/preface.itely
  79 2 user/introduction.itely
  80
  81 -3- Learning manual
  82 3 user/putting.itely -- Putting it all together
  83 3 user/working.itely -- Working on LilyPond files
  84 3 user/tweaks.itely -- Tweaking output
  85
  86 -4- Notation reference
  87 4 user/basic-notation.itely -- Basic notation
  88 4 user/instrument-notation.itely -- Instrument-specific notation
  89 4 user/advanced-notation.itely -- Advanced notation
  90 4 user/changing-defaults.itely -- Changing defaults
  91 4 user/non-music.itely -- Non-musical notation
  92 4 user/spacing.itely -- Spacing issues
  93 4 user/programming-interface.itely -- Interfaces for programmers
  94 4 user/scheme-tutorial.itely -- Scheme tutorial
  95
  96 -5- Program usage
  97 5 user/running.itely -- Running LilyPond
  98 5 user/lilypond-book.itely -- LilyPond-book
  99 5 user/converters.itely -- Converting from other formats
 100
 101 -6- Appendices whose translation is optional
 102 6 user/literature.itely
 103 6 user/templates.itely
 104 6 user/notation-appendices.itely
 105
 106 * WORD COUNTS FOR CATEGORIES
 107
 108 LANG=C wc --words $(grep ^1 TRANSLATION | cut -d ' ' -f 2 | sed 's@^@site/@')
 109
 110 LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2 | sed 's@^@site/@')
 111
 112
 113 TRANSLATION DETAILED INSTRUCTIONS
 114
 115 Please follow all these instructions with care to ensure quality work.
 116
 117 * USER MANUAL
 118
 119 Any title which comes with one of the following commands must not be
 120 translated directly in the Texinfo source
 121
 122 @node          @top                                     @majorheading
 123 @chapter       @unnumbered          @appendix           @chapheading
 124 @section       @unnumberedsec       @appendixsec        @heading
 125 @subsection    @unnumberedsubsec    @appendixsubsec     @subheading
 126 @subsubsection @unnumberedsubsubsec @appendixsubsubsec  @subsubheading
 127 @ref           @rglos
 128
 129
 130 In any section which looks like
 131
 132 @menu
 133 * node1:: thing1
 134 * node2:: thing2
 135 ...
 136 @end menu
 137
 138 the node names (nodeN) are NOT to be translated, whereas extra title
 139 information (thingN) is.
 140
 141
 142 Every node name or section title must from now on be translated
 143 separately in a .po file (just as well as LilyPond output messages).
 144 This .po file should be in Documentation/po.
 145
 146 Make sure to keep *verbatim* copies of music snippets (in @lilypond blocs).
 147 @example blocs do not have to be verbatim copies, e.g. variable names,
 148 file names and comments should be translated.
 149
 150 Index entries (@cindex and so on) should be translated.
 151
 152 Carefully apply every rule exposed in Documentation/README.txt.  If
 153 one of these rules conflicts with a rule specific to your language,
 154 please ask the Translation meister and/or the Documentation Editor on
 155 lilypond-devel@gnu.org.
 156
 157
 158 * DOCUMENTATION INDEX index.html.in
 159
 160
 161
 162 CHECK STATE OF TRANSLATION
 163
 164
 165
 166 UPDATE A TRANSLATION
 167
 168
 169
 170 TECHNICAL BACKGROUND
 171
 172 *** This section is a draft and should be overhauled ***
 173 - J. Mandereau
 174
 175 When starting a translation, texi-langutils.py quickly parses
 176 lilypond.tely and the included .itely's, and generates a skeleton with
 177 node and sectionning commands.  When translating a .itely file, the
 178 skeleton file is replaced with the real translation, in exception of
 179 the the node, sectioning and glossary reference commands, which
 180 remains in English.  All this ensures easy navigation between nodes in
 181 different languages in HTML docs, i.e.: there is automatic language
 182 selection on lilypond.org, all sections and cross-references are
 183 always available, at least in English (for example, see the "Other
 184 languages: xxx" menu at bottom of tutorial pages).  From the user's
 185 point of view, docs in his native language with node and sections in
 186 English are painful, so texi-langutils generates a .po of node and
 187 section names; this .po file is used to translate the section titles
 188 in the HTML generated docs.