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 -- Texinfo source, PDF and HTML output; Info output
39 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.
77 Priorities: 1. delivery, 2. 3. 4. 5. later, 6. optional.
79 Files marked with priority 3, 4 or 5 may be submitted individually.
81 -1- Documentation index, Tutorial and Cheat Sheet
84 1 user/dedication.itely
85 1 user/cheatsheet.itely
89 -2- User manual introduction
91 2 user/introduction.itely
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
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
109 5 user/running.itely -- Running LilyPond
110 5 user/lilypond-book.itely -- LilyPond-book
111 5 user/converters.itely -- Converting from other formats
113 -6- Appendices whose translation is optional
114 6 user/literature.itely
115 6 user/templates.itely
116 6 user/notation-appendices.itely
118 * WORD COUNTS FOR CATEGORIES
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
128 LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2)
129 451 user/preface.itely
130 4170 user/introduction.itely
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
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
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
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
163 TRANSLATION DETAILED INSTRUCTIONS
165 Please follow all these instructions with care to ensure quality work.
167 All files should be encoded in UTF-8.
171 Any title which comes with one of the following commands must not be
172 translated directly in the Texinfo source
174 @node @top @majorheading
175 @chapter @unnumbered @appendix @chapheading
176 @section @unnumberedsec @appendixsec @heading
177 @subsection @unnumberedsubsec @appendixsubsec @subheading
178 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
181 As a notable exception, the second argument 'Bar baz' of
182 @ref{Foo,'Bar baz',,info-file} should be translated.
184 @uref's names are to be translated.
186 In any section which looks like
194 the node names (nodeN) are NOT to be translated, whereas extra title
195 information (thingN) is.
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.
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,
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
217 @example blocs need not be verbatim copies, e.g. variable names,
218 file names and comments should be translated.
220 Index entries (@cindex and so on) should be translated.
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.
228 * DOCUMENTATION INDEX index.html.in
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.
235 CHECK STATE OF TRANSLATION
237 First pull, then cd into Documentation (or at top of the source tree,
238 replace 'make' with 'make -C Documentation') and run
240 make ISOLANG=<MY_LANGUAGE> check-translation
242 This presents a diff of the original files since the most recent
243 revision of the translation. To check a single file, run
245 python buildscripts/check_translation.py Documentation/<MY-LANGUAGE>/user/foo.itely
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
256 make ISOLANG=<MY_LANGUAGE> skeleton-update
258 .po message catalogs in Documentation/po may be updated with (from
259 Documentation or Documentation/po)
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):
267 make ISOLANG=<MY_LANGUAGE> snippet-update
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.
275 Finally, a command runs the three update processes above for all
276 enabled languages (from Documentation):
278 make all-translations-update
280 This command is mainly intended to be used by the Translation meister.
285 A number of Python scripts handle a part of the documentation
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