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 of LilyPond sources run
   9
  10     mkdir lily ; cd lily
  11     git init-db
  12     git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/lilypond/translation:lilypond/translation
  13     git checkout -b mytranslations lilypond/translation
  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 WHICH DOCUMENTATION CAN BE TRANSLATED
  33
  34 The makfiles and scripts infrastructure currently supports translation
  35 of the following documentation:
  36
  37     * documentation index (HTML)
  38     * user manual and program usage -- Texinfo source, PDF and HTML
  39 output; Info output might be added if there is enough demand for it.
  40
  41
  42 STARTING A TRANSLATION IN A NEW LANGUAGE
  43
  44 At top of the source directory, do
  45
  46     ./autogen.sh
  47
  48 or (if you want to install your self-compiled LilyPond locally):
  49
  50     ./autogen.sh --prefix=$HOME
  51
  52 If you want to compile LilyPond -- which is almost required to build
  53 the docs, but is not required to do translation only -- fix all
  54 dependencies and rerun ./configure (with the same options as for
  55 autogen).
  56
  57 Cd into Documentation and run:
  58
  59     make ISOLANG=<MY-LANGUAGE> new-lang
  60
  61 where <MY-LANGUAGE> is the ISO 639 language code.
  62
  63 Add a language definition for your language in
  64 buildscripts/langdefs.py.
  65
  66 See next section about what files to translate and the following
  67 detailed instructions after the next section.
  68
  69
  70 FILES TO BE TRANSLATED
  71
  72 All the following files are in Documentation/
  73 Translation of Documentation/foo/bar should be
  74 Documentation/<LANG>/foo/bar.
  75 Unmentioned files should not be translated.
  76
  77 Priorities:
  78   1. delivery
  79   2. 3. 4. 5. later
  80   6. optional
  81
  82 Files marked with priority 3, 4 or 5 may be submitted individually.
  83 Word counts (excluding lilypond snippets) are given for each file.
  84
  85 -1- Documentation index and Tutorial
  86 396   user/lilypond-learning.tely
  87 5593  user/tutorial.itely
  88 23    user/dedication.itely
  89 216   index.html.in
  90 1954  po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
  91 8182  total
  92
  93 In addition, user/macros.itexi may be translated in case typographic
  94 rules used in this file are different in your language.
  95
  96 -2- Introduction and beginning of Application Usage
  97 411   user/preface.itely
  98 3198  user/introduction.itely
  99 374   user/lilypond-program.tely
 100 1477  user/install.itely (partial translation)
 101 947   user/setup.itely
 102 2860  user/running.itely
 103 9267  total
 104
 105 -3- Learning manual
 106 8626  user/fundamental.itely -- Fundamental concepts
 107 12134 user/tweaks.itely -- Tweaking output
 108 2985  user/working.itely -- Working on LilyPond files
 109 483   user/templates.itely -- Templates
 110 24228 total
 111
 112 -4- Notation reference
 113 539   user/lilypond.tely
 114 91    user/notation.itely -- Musical notation
 115 2808  user/pitches.itely
 116 7336  user/rhythms.itely
 117 1681  user/expressive.itely
 118 725   user/repeats.itely
 119 916   user/simultaneous.itely
 120 1861  user/staff.itely
 121 879   user/editorial.itely
 122 2336  user/text.itely
 123 54    user/specialist.itely -- Specialist notation
 124 2630  user/vocal.itely
 125 1275  user/chords.itely
 126 702   user/piano.itely
 127 481   user/percussion.itely
 128 826   user/guitar.itely
 129 66    user/strings.itely
 130 242   user/bagpipes.itely
 131 4289  user/ancient.itely
 132 2502  user/input.itely -- Input syntax
 133 2164  user/non-music.itely -- Non-musical notation
 134 8399  user/spacing.itely -- Spacing issues
 135 5107  user/changing-defaults.itely -- Changing defaults
 136 4547  user/programming-interface.itely -- Interfaces for programmers
 137 935   user/notation-appendices.itely -- Notation manual tables
 138 250   user/cheatsheet.itely -- Cheat sheet
 139 53641 total
 140
 141 -5- Application usage
 142 2917  user/lilypond-book.itely -- LilyPond-book
 143 975   user/converters.itely -- Converting from other formats
 144 3892  total
 145
 146 -6- Appendices whose translation is optional
 147 299   user/literature.itely
 148 960   user/scheme-tutorial.itely (needs to be revised first)
 149 1259  total
 150
 151
 152 TRANSLATION DETAILED INSTRUCTIONS
 153
 154 Please follow all these instructions with care to ensure quality work.
 155
 156 All files should be encoded in UTF-8.
 157
 158 * USER MANUAL
 159
 160 Any title which comes with one of the following commands must not be
 161 translated directly in the Texinfo source
 162
 163 @node                                                   @majorheading
 164 @chapter       @unnumbered          @appendix           @chapheading
 165 @section       @unnumberedsec       @appendixsec        @heading
 166 @subsection    @unnumberedsubsec    @appendixsubsec     @subheading
 167 @subsubsection @unnumberedsubsubsec @appendixsubsubsec  @subsubheading
 168 @ref           @rglos
 169
 170 As a notable exception, the second argument 'Bar baz' of
 171 @ref{Foo,'Bar baz',,info-file} should be translated.
 172
 173 @uref's names are to be translated.
 174
 175 In any section which looks like
 176
 177 @menu
 178 * node1:: thing1
 179 * node2:: thing2
 180 ...
 181 @end menu
 182
 183 the node names (nodeN) are NOT to be translated, whereas extra title
 184 information (thingN) is.
 185
 186 Every node name or section title must from now on be translated
 187 separately in a .po file (just as well as LilyPond output messages).
 188 This .po file should be in Documentation/po.
 189
 190
 191 Please keep verbatim copies of music snippets (in @lilypond blocs).
 192 However, some music snippets containing text that shows in the
 193 rendered music, and sometimes translating this text really helps the
 194 user to understand the documentation; in this case, and only in this
 195 case, you may as an exception translate text in the music snippet, and
 196 then you must add a line immediately before the @lilypond block,
 197 beginning with
 198
 199 @c KEEP LY
 200
 201 Otherwise the music snippet would be reset to the same contents as the
 202 English version at next 'make snippet-update' run (see UPDATING A
 203 TRANSLATION below).
 204
 205
 206 @example blocs need not be verbatim copies, e.g. variable names,
 207 file names and comments should be translated.
 208
 209 Index entries (@cindex and so on) should be translated.
 210
 211 Carefully apply every rule exposed in Documentation/README.txt.  If
 212 one of these rules conflicts with a rule specific to your language,
 213 please ask the Translation meister and/or the Documentation Editor on
 214 lilypond-devel@gnu.org.
 215
 216
 217 * PROGRAM USAGE MANUAL
 218
 219 Copy user/lilypond-program.tely into <MY-LANGUAGE>/user, then
 220 translate this file and run skeleton-update (see UPDATE A TRANSLATION
 221 below).  Your are now ready to translate program usage manual exactly
 222 like the user manual.
 223
 224
 225 * DOCUMENTATION INDEX index.html.in
 226
 227 Unlike almost all HTML pages in this documentation, links in this page
 228 are not tweaked by add_html_footer.py, so links should be manually
 229 edited to link to existing translations.
 230
 231
 232 CHECK STATE OF TRANSLATION
 233
 234 First pull, then cd into Documentation (or at top of the source tree,
 235 replace 'make' with 'make -C Documentation') and run
 236
 237     make ISOLANG=<MY_LANGUAGE> check-translation
 238
 239 This presents a diff of the original files since the most recent
 240 revision of the translation.  To check a single file, run
 241
 242     python buildscripts/check_translation.py buildscripts Documentation/<MY-LANGUAGE>/user/foo.itely
 243
 244
 245
 246 UPDATE A TRANSLATION
 247
 248 Texinfo skeleton files, i.e. .itely files not yet translated,
 249 containing only the Texinfo structure can be updated automatically:
 250 whenever 'make check-translation' shows that such files should be
 251 updated, run from Documentation
 252
 253     make ISOLANG=<MY_LANGUAGE> skeleton-update
 254
 255 .po message catalogs in Documentation/po may be updated with (from
 256 Documentation or Documentation/po)
 257
 258     make po-update
 259
 260 WARNING: if you run po-update and somebody else does the same and
 261 pushes before you push or send a patch to be applied, there will be a
 262 conflict when you pull.  Therefore, it is better that only the
 263 Translation meister runs this command.
 264
 265 Updating music snippets can quickly become cumbersome, as most
 266 snippets should be identical in all languages.  Fortunately, there is
 267 a script than can do this odd job for you (run from Documentation):
 268
 269     make ISOLANG=<MY_LANGUAGE> snippet-update
 270
 271 This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
 272 with music snippets from user/every.itely.  It ignores skeleton files,
 273 and keeps intact music snippets preceded with a line starting with '@c
 274 KEEP LY'; it reports an error for each .itely that has not the same
 275 music snippet count in both languages.
 276
 277 Finally, a command runs the three update processes above for all
 278 enabled languages (from Documentation):
 279
 280     make all-translations-update
 281
 282 This command is mainly intended to be used by the Translation meister.
 283
 284
 285 TECHNICAL BACKGROUND
 286
 287 A number of Python scripts handle a part of the documentation
 288 translation process:
 289
 290 * langdefs.py  -- language definitions
 291 * check_translation.py  -- show diff to update a translation
 292 * texi-langutils.py  -- quickly and dirtily parse Texinfo files to
 293 make message catalogs and Texinfo skeleton files
 294 * texi-skeleton-update.py -- update Texinfo skeleton files
 295 * html-gettext.py -- translate node names, section titles and cross
 296 references in HTML files generated by makeinfo
 297 * add_html_footer.py (module called by www_post.py) -- add footer and
 298 tweak links in HTML pages
 299 * texi-gettext.py -- gettext node names, section titles and references
 300 before calling texi2pdf
 301 * mass-link.py -- link or symlink files between English documentation
 302 and documentation in other languages
 303 * update-snippets.py -- synchronize ly snippets with those from
 304 English docs