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