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:  1. delivery, 2. 3. 4. 5. later, 6. optional.
  78
  79 Files marked with priority 3, 4 or 5 may be submitted individually.
  80
  81 -1- Documentation index, Tutorial and Cheat Sheet
  82 1 user/lilypond.tely
  83 1 user/tutorial.itely
  84 1 user/dedication.itely
  85 1 user/cheatsheet.itely
  86 1 index.html.in
  87   po/<MY-LANGUAGE>.po
  88
  89 In addition, user/macros.itexi may be translated in case typographic
  90 rules used in this file are different in your language.
  91
  92 -2- User manual introduction
  93 2 user/preface.itely
  94 2 user/introduction.itely
  95
  96 -3- Learning manual
  97 3 user/putting.itely -- Putting it all together
  98 3 user/working.itely -- Working on LilyPond files
  99 3 user/tweaks.itely -- Tweaking output
 100
 101 -4- Notation reference
 102 4 user/basic-notation.itely -- Basic notation
 103 4 user/instrument-notation.itely -- Instrument-specific notation
 104 4 user/advanced-notation.itely -- Advanced notation
 105 4 user/changing-defaults.itely -- Changing defaults
 106 4 user/non-music.itely -- Non-musical notation
 107 4 user/spacing.itely -- Spacing issues
 108 4 user/programming-interface.itely -- Interfaces for programmers
 109 4 user/scheme-tutorial.itely -- Scheme tutorial
 110
 111 -5- Program usage
 112 5 user/lilypond-program.tely
 113 5 user/install.itely -- How to install or compile
 114 5 user/running.itely -- Running LilyPond
 115 5 user/lilypond-book.itely -- LilyPond-book
 116 5 user/converters.itely -- Converting from other formats
 117
 118 -6- Appendices whose translation is optional
 119 6 user/literature.itely
 120 6 user/templates.itely
 121 6 user/notation-appendices.itely
 122
 123 * WORD COUNTS FOR CATEGORIES
 124
 125 LANG=C wc --words $(grep ^1 TRANSLATION | cut -d ' ' -f 2)
 126   777 user/lilypond.tely
 127  6322 user/tutorial.itely
 128    63 user/dedication.itely
 129   632 user/cheatsheet.itely
 130   361 index.html.in
 131  8155 total
 132
 133 LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2)
 134   451 user/preface.itely
 135  4170 user/introduction.itely
 136  4621 total
 137
 138 LANG=C wc --words $(grep ^3 TRANSLATION | cut -d ' ' -f 2)
 139  2230 user/putting.itely
 140  3232 user/working.itely
 141  2327 user/tweaks.itely
 142  7789 total
 143
 144 LANG=C wc --words $(grep ^4 TRANSLATION | cut -d ' ' -f 2)
 145  12391 user/basic-notation.itely
 146  15779 user/instrument-notation.itely
 147   9530 user/advanced-notation.itely
 148   7386 user/changing-defaults.itely
 149   3884 user/non-music.itely
 150   8318 user/spacing.itely
 151   4781 user/programming-interface.itely
 152    915 user/scheme-tutorial.itely
 153  62984 total
 154
 155 LANG=C wc --words $(grep ^5 TRANSLATION | cut -d ' ' -f 2)
 156  3566 user/running.itely
 157  3549 user/lilypond-book.itely
 158  1062 user/converters.itely
 159  8177 total
 160
 161 LANG=C wc --words $(grep ^6 TRANSLATION | cut -d ' ' -f 2)
 162   339 user/literature.itely
 163  4648 user/templates.itely
 164   836 user/notation-appendices.itely
 165  5823 total
 166
 167
 168 TRANSLATION DETAILED INSTRUCTIONS
 169
 170 Please follow all these instructions with care to ensure quality work.
 171
 172 All files should be encoded in UTF-8.
 173
 174 * USER MANUAL
 175
 176 Any title which comes with one of the following commands must not be
 177 translated directly in the Texinfo source
 178
 179 @node                                                   @majorheading
 180 @chapter       @unnumbered          @appendix           @chapheading
 181 @section       @unnumberedsec       @appendixsec        @heading
 182 @subsection    @unnumberedsubsec    @appendixsubsec     @subheading
 183 @subsubsection @unnumberedsubsubsec @appendixsubsubsec  @subsubheading
 184 @ref           @rglos
 185
 186 As a notable exception, the second argument 'Bar baz' of
 187 @ref{Foo,'Bar baz',,info-file} should be translated.
 188
 189 @uref's names are to be translated.
 190
 191 In any section which looks like
 192
 193 @menu
 194 * node1:: thing1
 195 * node2:: thing2
 196 ...
 197 @end menu
 198
 199 the node names (nodeN) are NOT to be translated, whereas extra title
 200 information (thingN) is.
 201
 202 Every node name or section title must from now on be translated
 203 separately in a .po file (just as well as LilyPond output messages).
 204 This .po file should be in Documentation/po.
 205
 206
 207 Please keep verbatim copies of music snippets (in @lilypond blocs).
 208 However, some music snippets containing text that shows in the
 209 rendered music, and sometimes translating this text really helps the
 210 user to understand the documentation; in this case, and only in this
 211 case, you may as an exception translate text in the music snippet, and
 212 then you must add a line immediately before the @lilypond block,
 213 beginning with
 214
 215 @c KEEP LY
 216
 217 Otherwise the music snippet would be reset to the same contents as the
 218 English version at next 'make snippet-update' run (see UPDATING A
 219 TRANSLATION below).
 220
 221
 222 @example blocs need not be verbatim copies, e.g. variable names,
 223 file names and comments should be translated.
 224
 225 Index entries (@cindex and so on) should be translated.
 226
 227 Carefully apply every rule exposed in Documentation/README.txt.  If
 228 one of these rules conflicts with a rule specific to your language,
 229 please ask the Translation meister and/or the Documentation Editor on
 230 lilypond-devel@gnu.org.
 231
 232
 233 * PROGRAM USAGE MANUAL
 234
 235 Copy user/lilypond-program.tely into <MY-LANGUAGE>/user, then
 236 translate this file and run skeleton-update (see UPDATE A TRANSLATION
 237 below).  Your are now ready to translate program usage manual exactly
 238 like the user manual.
 239
 240
 241 * DOCUMENTATION INDEX index.html.in
 242
 243 Unlike almost all HTML pages in this documentation, links in this page
 244 are not tweaked by add_html_footer.py, so links should be manually
 245 edited to link to existing translations.
 246
 247
 248 CHECK STATE OF TRANSLATION
 249
 250 First pull, then cd into Documentation (or at top of the source tree,
 251 replace 'make' with 'make -C Documentation') and run
 252
 253     make ISOLANG=<MY_LANGUAGE> check-translation
 254
 255 This presents a diff of the original files since the most recent
 256 revision of the translation.  To check a single file, run
 257
 258     python buildscripts/check_translation.py buildscripts Documentation/<MY-LANGUAGE>/user/foo.itely
 259
 260
 261
 262 UPDATE A TRANSLATION
 263
 264 Texinfo skeleton files, i.e. .itely files not yet translated,
 265 containing only the Texinfo structure can be updated automatically:
 266 whenever 'make check-translation' shows that such files should be
 267 updated, run from Documentation
 268
 269     make ISOLANG=<MY_LANGUAGE> skeleton-update
 270
 271 .po message catalogs in Documentation/po may be updated with (from
 272 Documentation or Documentation/po)
 273
 274     make po-update
 275
 276 WARNING: if you run po-update and somebody else does the same and
 277 pushes before you push or send a patch to be applied, there will be a
 278 conflict when you pull.  Therefore, it is better that only the
 279 Translation meister runs this command.
 280
 281 Updating music snippets can quickly become cumbersome, as most
 282 snippets should be identical in all languages.  Fortunately, there is
 283 a script than can do this odd job for you (run from Documentation):
 284
 285     make ISOLANG=<MY_LANGUAGE> snippet-update
 286
 287 This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
 288 with music snippets from user/every.itely.  It ignores skeleton files,
 289 and keeps intact music snippets preceded with a line starting with '@c
 290 KEEP LY'; it reports an error for each .itely that has not the same
 291 music snippet count in both languages.
 292
 293 Finally, a command runs the three update processes above for all
 294 enabled languages (from Documentation):
 295
 296     make all-translations-update
 297
 298 This command is mainly intended to be used by the Translation meister.
 299
 300
 301 TECHNICAL BACKGROUND
 302
 303 A number of Python scripts handle a part of the documentation
 304 translation process:
 305
 306 * langdefs.py  -- language definitions
 307 * check_translation.py  -- show diff to update a translation
 308 * texi-langutils.py  -- quickly and dirtily parse Texinfo files to
 309 make message catalogs and Texinfo skeleton files
 310 * texi-skeleton-update.py -- update Texinfo skeleton files
 311 * html-gettext.py -- translate node names, section titles and cross
 312 references in HTML files generated by makeinfo
 313 * add_html_footer.py (module called by www_post.py) -- add footer and
 314 tweak links in HTML pages
 315 * texi-gettext.py -- gettext node names, section titles and references
 316 before calling texi2pdf
 317 * mass-link.py -- link or symlink files between English documentation
 318 and documentation in other languages
 319 * update-snippets.py -- synchronize ly snippets with those from
 320 English docs