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 2022 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 2458 user/input.itely -- Input syntax
133 2164 user/non-music.itely -- Non-musical notation
134 8399 user/spacing.itely -- Spacing issues
135 5149 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.
158 * LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
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
207 @lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}
209 in the source, open input/lsr/FILENAME.ly, translate the texidoc
210 string it contains, enclose it with 'texidoc<MY-LANGUAGE> = "' and
211 '"', and write it into input/texidocs/FILENAME.texidoc -- please keep
212 possibly existing translations in other languages! For instance,
213 input/texidocs/FILENAME.texidoc may contain
216 Spanish translation blah
218 texidocde = "German translation foo
222 @example blocs need not be verbatim copies, e.g. variable names,
223 file names and comments should be translated.
225 Index entries (@cindex and so on) should be translated.
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.
233 * REFERENCE NOTATION AND PROGRAM USAGE MANUAL
235 Copy user/lilypond.tely (or user/lilypond-program.tely, respectively)
236 into <MY-LANGUAGE>/user, then translate this file and run
237 skeleton-update (see UPDATE A TRANSLATION below). Your are now ready
238 to translate notation reference (program usage manual, respectively)
239 exactly like the learning manual.
242 * DOCUMENTATION INDEX index.html.in
244 Unlike almost all HTML pages in this documentation, links in this page
245 are not tweaked by add_html_footer.py, so links should be manually
246 edited to link to existing translations.
249 CHECK STATE OF TRANSLATION
251 First pull, then cd into Documentation (or at top of the source tree,
252 replace 'make' with 'make -C Documentation') and run
254 make ISOLANG=<MY_LANGUAGE> check-translation
256 This presents a diff of the original files since the most recent
257 revision of the translation. To check a single file, cd into
258 Documentation and run
260 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely check-translation
263 Small tip: to see only which files need to be updated, do
265 make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
268 Global state of the translation is recorded in
269 Documentation/translations.html.in, which is used to generate
270 Translations status page. To update that page, do from Documentation/
272 make translation-status
274 This will also leave out/translations-status.txt, which contains
275 up-to-dateness percentages for each translated file.
280 Instead of running check-translation, you can run update-translation,
281 which will run your favorite text editor to update files. First, make
282 sure environment variable EDITOR is set to a text editor command, then
283 run from Documentation
285 make ISOLANG=<MY-LANGUAGE> update-translation
287 or to update a single file
289 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely update-translation
291 For each file to be udpated, update-translation will open your text
292 editor with this file and a diff of the file in English; if the diff
293 cannot be generated or is bigger than the file in English itself, the
294 full file in English will be opened instead.
296 Texinfo skeleton files, i.e. .itely files not yet translated,
297 containing only the Texinfo structure can be updated automatically:
298 whenever 'make check-translation' shows that such files should be
299 updated, run from Documentation
301 make ISOLANG=<MY_LANGUAGE> skeleton-update
303 .po message catalogs in Documentation/po may be updated with (from
304 Documentation or Documentation/po)
308 WARNING: if you run po-update and somebody else does the same and
309 pushes before you push or send a patch to be applied, there will be a
310 conflict when you pull. Therefore, it is better that only the
311 Translation meister runs this command.
313 Updating music snippets can quickly become cumbersome, as most
314 snippets should be identical in all languages. Fortunately, there is
315 a script than can do this odd job for you (run from Documentation):
317 make ISOLANG=<MY_LANGUAGE> snippet-update
319 This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
320 with music snippets from user/every.itely. It ignores skeleton files,
321 and keeps intact music snippets preceded with a line starting with '@c
322 KEEP LY'; it reports an error for each .itely that has not the same
323 music snippet count in both languages.
325 Finally, a command runs the three update processes above for all
326 enabled languages (from Documentation):
328 make all-translations-update
330 This command is mainly intended to be used by the Translation meister.
335 A number of Python scripts handle a part of the documentation
338 * langdefs.py -- language definitions
339 * check_translation.py -- show diff to update a translation
340 * texi-langutils.py -- quickly and dirtily parse Texinfo files to
341 make message catalogs and Texinfo skeleton files
342 * texi-skeleton-update.py -- update Texinfo skeleton files
343 * html-gettext.py -- translate node names, section titles and cross
344 references in HTML files generated by makeinfo
345 * add_html_footer.py (module called by www_post.py) -- add footer and
346 tweak links in HTML pages
347 * texi-gettext.py -- gettext node names, section titles and references
348 before calling texi2pdf
349 * mass-link.py -- link or symlink files between English documentation
350 and documentation in other languages
351 * update-snippets.py -- synchronize ly snippets with those from
353 * translations-status.py -- update translations status pages and word
354 counts in the file you are reading