1 LILYPOND DOCUMENTATION TRANSLATION
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
12 git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/lilypond/translation:lilypond/translation
13 git checkout -b mytranslations lilypond/translation
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
25 Working on LilyPond documentation translations requires:
32 WHICH DOCUMENTATION CAN BE TRANSLATED
34 The makfiles and scripts infrastructure currently supports translation
35 of the following documentation:
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.
42 STARTING A TRANSLATION IN A NEW LANGUAGE
44 At top of the source directory, do
48 or (if you want to install your self-compiled LilyPond locally):
50 ./autogen.sh --prefix=$HOME
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
57 Cd into Documentation and run:
59 make ISOLANG=<MY-LANGUAGE> new-lang
61 where <MY-LANGUAGE> is the ISO 639 language code.
63 Add a language definition for your language in
64 buildscripts/langdefs.py.
66 See next section about what files to translate and the following
67 detailed instructions after the next section.
70 FILES TO BE TRANSLATED
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.
82 Files marked with priority 3, 4 or 5 may be submitted individually.
83 Word counts (excluding lilypond snippets) are given for each file.
85 -1- Documentation index and Tutorial
86 396 user/lilypond-learning.tely
87 5593 user/tutorial.itely
88 23 user/dedication.itely
90 1954 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
93 In addition, user/macros.itexi may be translated in case typographic
94 rules used in this file are different in your language.
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)
102 2860 user/running.itely
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
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
123 54 user/specialist.itely -- Specialist notation
124 2630 user/vocal.itely
125 1275 user/chords.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
141 -5- Application usage
142 2917 user/lilypond-book.itely -- LilyPond-book
143 975 user/converters.itely -- Converting from other formats
146 -6- Appendices whose translation is optional
147 299 user/literature.itely
148 960 user/scheme-tutorial.itely (needs to be revised first)
152 TRANSLATION DETAILED INSTRUCTIONS
154 Please follow all these instructions with care to ensure quality work.
156 All files should be encoded in UTF-8.
160 Any title which comes with one of the following commands must not be
161 translated directly in the Texinfo source
164 @chapter @unnumbered @appendix @chapheading
165 @section @unnumberedsec @appendixsec @heading
166 @subsection @unnumberedsubsec @appendixsubsec @subheading
167 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
170 As a notable exception, the second argument 'Bar baz' of
171 @ref{Foo,'Bar baz',,info-file} should be translated.
173 @uref's names are to be translated.
175 In any section which looks like
183 the node names (nodeN) are NOT to be translated, whereas extra title
184 information (thingN) is.
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.
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,
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
206 @example blocs need not be verbatim copies, e.g. variable names,
207 file names and comments should be translated.
209 Index entries (@cindex and so on) should be translated.
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.
217 * PROGRAM USAGE MANUAL
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.
225 * DOCUMENTATION INDEX index.html.in
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.
232 CHECK STATE OF TRANSLATION
234 First pull, then cd into Documentation (or at top of the source tree,
235 replace 'make' with 'make -C Documentation') and run
237 make ISOLANG=<MY_LANGUAGE> check-translation
239 This presents a diff of the original files since the most recent
240 revision of the translation. To check a single file, run
242 python buildscripts/check_translation.py buildscripts Documentation/<MY-LANGUAGE>/user/foo.itely
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
253 make ISOLANG=<MY_LANGUAGE> skeleton-update
255 .po message catalogs in Documentation/po may be updated with (from
256 Documentation or Documentation/po)
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.
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):
269 make ISOLANG=<MY_LANGUAGE> snippet-update
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.
277 Finally, a command runs the three update processes above for all
278 enabled languages (from Documentation):
280 make all-translations-update
282 This command is mainly intended to be used by the Translation meister.
287 A number of Python scripts handle a part of the documentation
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