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/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 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   po/<MY-LANGUAGE>.po
  77
  78 -2- User manual introduction
  79 2 user/preface.itely
  80 2 user/introduction.itely
  81
  82 -3- Learning manual
  83 3 user/putting.itely -- Putting it all together
  84 3 user/working.itely -- Working on LilyPond files
  85 3 user/tweaks.itely -- Tweaking output
  86
  87 -4- Notation reference
  88 4 user/basic-notation.itely -- Basic notation
  89 4 user/instrument-notation.itely -- Instrument-specific notation
  90 4 user/advanced-notation.itely -- Advanced notation
  91 4 user/changing-defaults.itely -- Changing defaults
  92 4 user/non-music.itely -- Non-musical notation
  93 4 user/spacing.itely -- Spacing issues
  94 4 user/programming-interface.itely -- Interfaces for programmers
  95 4 user/scheme-tutorial.itely -- Scheme tutorial
  96
  97 -5- Program usage
  98 5 user/running.itely -- Running LilyPond
  99 5 user/lilypond-book.itely -- LilyPond-book
 100 5 user/converters.itely -- Converting from other formats
 101
 102 -6- Appendices whose translation is optional
 103 6 user/literature.itely
 104 6 user/templates.itely
 105 6 user/notation-appendices.itely
 106
 107 * WORD COUNTS FOR CATEGORIES
 108
 109 LANG=C wc --words $(grep ^1 TRANSLATION | cut -d ' ' -f 2)
 110   777 user/lilypond.tely
 111  6322 user/tutorial.itely
 112    63 user/dedication.itely
 113   632 user/cheatsheet.itely
 114   361 index.html.in
 115  8155 total
 116
 117 LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2)
 118   451 user/preface.itely
 119  4170 user/introduction.itely
 120  4621 total
 121
 122 LANG=C wc --words $(grep ^3 TRANSLATION | cut -d ' ' -f 2)
 123  2230 user/putting.itely
 124  3232 user/working.itely
 125  2327 user/tweaks.itely
 126  7789 total
 127
 128 LANG=C wc --words $(grep ^4 TRANSLATION | cut -d ' ' -f 2)
 129  12391 user/basic-notation.itely
 130  15779 user/instrument-notation.itely
 131   9530 user/advanced-notation.itely
 132   7386 user/changing-defaults.itely
 133   3884 user/non-music.itely
 134   8318 user/spacing.itely
 135   4781 user/programming-interface.itely
 136    915 user/scheme-tutorial.itely
 137  62984 total
 138
 139 LANG=C wc --words $(grep ^5 TRANSLATION | cut -d ' ' -f 2)
 140  3566 user/running.itely
 141  3549 user/lilypond-book.itely
 142  1062 user/converters.itely
 143  8177 total
 144
 145 LANG=C wc --words $(grep ^6 TRANSLATION | cut -d ' ' -f 2)
 146   339 user/literature.itely
 147  4648 user/templates.itely
 148   836 user/notation-appendices.itely
 149  5823 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          @top                                     @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 In any section which looks like
 174
 175 @menu
 176 * node1:: thing1
 177 * node2:: thing2
 178 ...
 179 @end menu
 180
 181 the node names (nodeN) are NOT to be translated, whereas extra title
 182 information (thingN) is.
 183
 184
 185 Every node name or section title must from now on be translated
 186 separately in a .po file (just as well as LilyPond output messages).
 187 This .po file should be in Documentation/po.
 188
 189 Make sure to keep *verbatim* copies of music snippets (in @lilypond blocs).
 190 @example blocs do not have to be verbatim copies, e.g. variable names,
 191 file names and comments should be translated.
 192
 193 Index entries (@cindex and so on) should be translated.
 194
 195 Carefully apply every rule exposed in Documentation/README.txt.  If
 196 one of these rules conflicts with a rule specific to your language,
 197 please ask the Translation meister and/or the Documentation Editor on
 198 lilypond-devel@gnu.org.
 199
 200
 201 * DOCUMENTATION INDEX index.html.in
 202
 203 Unlike almost all HTML pages in this documentation, links in this page
 204 are not tweaked by add_html_footer.py, so links should be manually
 205 edited to link to existing translations.
 206
 207
 208 CHECK STATE OF TRANSLATION
 209
 210 First pull, then cd into Documentation (or at top of the source tree,
 211 replace 'make' with 'make -C Documentation') and run
 212
 213     make ISOLANG=<MY_LANGUAGE> check-translation
 214
 215 This presents a diff of the original files since the most recent
 216 revision of the translation.  To check a single page, run
 217
 218     buildscripts/check-translation.py Documentation/user/<MY-LANGUAGE>/foo/bar.itely
 219
 220
 221
 222 UPDATE A TRANSLATION
 223
 224 Texinfo skeleton files, i.e. .itely files not yet translated,
 225 containing only the Texinfo structure can be updated automatically:
 226 whenever 'make check-translation' shows that such files shouldbe
 227 updated, run from Documentation
 228
 229     make ISOLANG=<MY_LANGUAGE> skeleton-update
 230
 231 .po message catalogs in Documentation/po may be updated with (from
 232 Documentation or Documentation/po)
 233
 234     make po-update
 235
 236
 237
 238 TECHNICAL BACKGROUND
 239
 240 A number of Python scripts handle a part of the documentation
 241 translation process:
 242
 243 langdefs.py  -- language definitions
 244 check_translation.py  -- show diff to update a translation
 245 texi-langutils.py  -- quickly and dirtily parse Texinfo files to
 246 make message catalogs and Texinfo skeleton files
 247 texi-skeleton-update.py -- update Texinfo skeleton files
 248 html-gettext.py -- translate node names, section titles and cross
 249 references in HTML files generated by makeinfo
 250 add_html_footer.py (module called by www_post.py) -- add footer and
 251 tweak links in HTML pages