1 LILYPOND DOCUMENTATION TRANSLATION
6 The sources live in a GIT repository. Git 1.5.x is required, and
7 latest version available on your platform is always recommended. To
8 get a fresh version of LilyPond sources run
10 mkdir lily ; cd lily ; git init-db ; mkdir .git/refs/remotes/origin
12 then write the two following lines to a text file named .git/remotes/trans
14 URL: git://git.sv.gnu.org/lilypond.git/
15 Pull: lilypond/translation:refs/remotes/origin/lilypond/translation
20 git checkout -b lilypond/translation origin/lilypond/translation
25 The reader is supposed to be familiar with Git, for example by
26 having experience from lilypond.org translation; see
27 http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=README;hb=web/master
32 Working on LilyPond documentation translations requires:
39 WHICH DOCUMENTATION CAN BE TRANSLATED
41 The makfiles and scripts infrastructure currently supports translation
42 of the following documentation:
44 * documentation index (HTML)
45 * user manual and program usage -- Texinfo source, PDF and HTML
46 output; Info output might be added if there is enough demand for it.
49 STARTING A TRANSLATION IN A NEW LANGUAGE
51 At top of the source directory, do
55 or (if you want to install your self-compiled LilyPond locally):
57 ./autogen.sh --prefix=$HOME
59 If you want to compile LilyPond -- which is almost required to build
60 the docs, but is not required to do translation only -- fix all
61 dependencies and rerun ./configure (with the same options as for
64 Cd into Documentation and run:
66 make ISOLANG=<MY-LANGUAGE> new-lang
68 where <MY-LANGUAGE> is the ISO 639 language code.
70 Add a language definition for your language in
71 buildscripts/langdefs.py.
73 See next section about what files to translate and the following
74 detailed instructions after the next section.
77 FILES TO BE TRANSLATED
79 All the following files are in Documentation/
80 Translation of Documentation/foo/bar should be
81 Documentation/<LANG>/foo/bar.
82 Unmentioned files should not be translated.
89 Files marked with priority 3, 4 or 5 may be submitted individually.
90 Word counts (excluding lilypond snippets) are given for each file.
92 -1- Documentation index and Tutorial
93 396 user/lilypond-learning.tely
94 5593 user/tutorial.itely
95 23 user/dedication.itely
97 2022 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
100 In addition, user/macros.itexi may be translated in case typographic
101 rules used in this file are different in your language.
103 -2- Introduction and beginning of Application Usage
104 411 user/preface.itely
105 3198 user/introduction.itely
106 374 user/lilypond-program.tely
107 1477 user/install.itely (partial translation)
109 2860 user/running.itely
113 8626 user/fundamental.itely -- Fundamental concepts
114 12134 user/tweaks.itely -- Tweaking output
115 2985 user/working.itely -- Working on LilyPond files
116 483 user/templates.itely -- Templates
119 -4- Notation reference
120 539 user/lilypond.tely
121 91 user/notation.itely -- Musical notation
122 2808 user/pitches.itely
123 7336 user/rhythms.itely
124 1681 user/expressive.itely
125 725 user/repeats.itely
126 916 user/simultaneous.itely
127 1861 user/staff.itely
128 879 user/editorial.itely
130 54 user/specialist.itely -- Specialist notation
131 2630 user/vocal.itely
132 1275 user/chords.itely
134 481 user/percussion.itely
135 826 user/guitar.itely
136 66 user/strings.itely
137 242 user/bagpipes.itely
138 4289 user/ancient.itely
139 2458 user/input.itely -- Input syntax
140 2164 user/non-music.itely -- Non-musical notation
141 8399 user/spacing.itely -- Spacing issues
142 5149 user/changing-defaults.itely -- Changing defaults
143 4547 user/programming-interface.itely -- Interfaces for programmers
144 935 user/notation-appendices.itely -- Notation manual tables
145 250 user/cheatsheet.itely -- Cheat sheet
148 -5- Application usage
149 2917 user/lilypond-book.itely -- LilyPond-book
150 975 user/converters.itely -- Converting from other formats
153 -6- Appendices whose translation is optional
154 299 user/literature.itely
155 960 user/scheme-tutorial.itely (needs to be revised first)
159 TRANSLATION DETAILED INSTRUCTIONS
161 Please follow all these instructions with care to ensure quality work.
163 All files should be encoded in UTF-8.
165 * LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
167 Any title which comes with one of the following commands must not be
168 translated directly in the Texinfo source
171 @chapter @unnumbered @appendix @chapheading
172 @section @unnumberedsec @appendixsec @heading
173 @subsection @unnumberedsubsec @appendixsubsec @subheading
174 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
177 As a notable exception, the second argument 'Bar baz' of
178 @ref{Foo,'Bar baz',,info-file} should be translated.
180 @uref's names are to be translated.
182 In any section which looks like
190 the node names (nodeN) are NOT to be translated, whereas extra title
191 information (thingN) is.
193 Every node name or section title must from now on be translated
194 separately in a .po file (just as well as LilyPond output messages).
195 This .po file should be in Documentation/po.
198 Please keep verbatim copies of music snippets (in @lilypond blocs).
199 However, some music snippets containing text that shows in the
200 rendered music, and sometimes translating this text really helps the
201 user to understand the documentation; in this case, and only in this
202 case, you may as an exception translate text in the music snippet, and
203 then you must add a line immediately before the @lilypond block,
208 Otherwise the music snippet would be reset to the same contents as the
209 English version at next 'make snippet-update' run (see UPDATING A
214 @lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}
216 in the source, open input/lsr/FILENAME.ly, translate the texidoc
217 string it contains, enclose it with 'texidoc<MY-LANGUAGE> = "' and
218 '"', and write it into input/texidocs/FILENAME.texidoc -- please keep
219 possibly existing translations in other languages! For instance,
220 input/texidocs/FILENAME.texidoc may contain
223 Spanish translation blah
225 texidocde = "German translation foo
229 @example blocs need not be verbatim copies, e.g. variable names,
230 file names and comments should be translated.
232 Index entries (@cindex and so on) should be translated.
234 Carefully apply every rule exposed in Documentation/README.txt. If
235 one of these rules conflicts with a rule specific to your language,
236 please ask the Translation meister and/or the Documentation Editor on
237 lilypond-devel@gnu.org.
240 * REFERENCE NOTATION AND PROGRAM USAGE MANUAL
242 Copy user/lilypond.tely (or user/lilypond-program.tely, respectively)
243 into <MY-LANGUAGE>/user, then translate this file and run
244 skeleton-update (see UPDATE A TRANSLATION below). Your are now ready
245 to translate notation reference (program usage manual, respectively)
246 exactly like the learning manual.
249 * DOCUMENTATION INDEX index.html.in
251 Unlike almost all HTML pages in this documentation, links in this page
252 are not tweaked by add_html_footer.py, so links should be manually
253 edited to link to existing translations.
256 CHECK STATE OF TRANSLATION
258 First pull, then cd into Documentation (or at top of the source tree,
259 replace 'make' with 'make -C Documentation') and run
261 make ISOLANG=<MY_LANGUAGE> check-translation
263 This presents a diff of the original files since the most recent
264 revision of the translation. To check a single file, cd into
265 Documentation and run
267 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely check-translation
270 Small tip: to see only which files need to be updated, do
272 make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
275 Global state of the translation is recorded in
276 Documentation/translations.html.in, which is used to generate
277 Translations status page. To update that page, do from Documentation/
279 make translation-status
281 This will also leave out/translations-status.txt, which contains
282 up-to-dateness percentages for each translated file.
287 Instead of running check-translation, you can run update-translation,
288 which will run your favorite text editor to update files. First, make
289 sure environment variable EDITOR is set to a text editor command, then
290 run from Documentation
292 make ISOLANG=<MY-LANGUAGE> update-translation
294 or to update a single file
296 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely update-translation
298 For each file to be udpated, update-translation will open your text
299 editor with this file and a diff of the file in English; if the diff
300 cannot be generated or is bigger than the file in English itself, the
301 full file in English will be opened instead.
303 Texinfo skeleton files, i.e. .itely files not yet translated,
304 containing only the Texinfo structure can be updated automatically:
305 whenever 'make check-translation' shows that such files should be
306 updated, run from Documentation
308 make ISOLANG=<MY_LANGUAGE> skeleton-update
310 .po message catalogs in Documentation/po may be updated with (from
311 Documentation or Documentation/po)
315 WARNING: if you run po-update and somebody else does the same and
316 pushes before you push or send a patch to be applied, there will be a
317 conflict when you pull. Therefore, it is better that only the
318 Translation meister runs this command.
320 Updating music snippets can quickly become cumbersome, as most
321 snippets should be identical in all languages. Fortunately, there is
322 a script than can do this odd job for you (run from Documentation):
324 make ISOLANG=<MY_LANGUAGE> snippet-update
326 This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
327 with music snippets from user/every.itely. It ignores skeleton files,
328 and keeps intact music snippets preceded with a line starting with '@c
329 KEEP LY'; it reports an error for each .itely that has not the same
330 music snippet count in both languages.
332 Finally, a command runs the three update processes above for all
333 enabled languages (from Documentation):
335 make all-translations-update
337 This command is mainly intended to be used by the Translation meister.
340 MISCELLANEOUS: DEALING WITH SEVERAL GIT BRANCHES
342 * It is possible to work with several branches on the same local Git
343 repository; this is especially useful for translators who may have to
344 deal with both lilypond/translation and a stable branch
345 (e.g. stable/2.12 or lilypond/translation-2.12). To fetch and check
346 out a new branch named BRANCH on git.sv.gnu.org, write the two
347 following lines to a text file named .git/remotes/SHORTHAND --
348 SHORTHAND is the name of the remote file, i.e. whatever easy-to-type
349 name you would like to use when pulling or pushing BRANCH, and usually
350 SHORTHAND is an abbreviation of BRANCH without slashes
352 URL: git://git.sv.gnu.org/lilypond.git/
353 Pull: BRANCH:refs/remotes/origin/BRANCH
358 git checkout -b BRANCH origin/BRANCH
360 After this, you are able to pull BRANCH from git.sv.gnu.org with
364 You can check out another branch OTHER_BRANCH, i.e. check out
365 OTHER_BRANCH to the working tree, with
367 git checkout OTHER_BRANCH
369 E.g. lilypond/translation, which you still have in your local Git
370 repository but is no longer checked out since you have created the new
373 Note that it is possible to check out another branch while having
374 uncommitted changes, but it is not recommended unless you know what
375 you are doing; it is recommended to run 'git status' to check this
376 kind of issue before checking ouy another branch.
378 When pulling using SHORTHAND, do not forget to check first that the
379 right branch is checked out, i.e. the branch named A in the first part
380 of the "A:B" refspec in .git/remotes/SHORTHAND: as a matter of fact,
381 when you pull using A:B refspec, Git fetch A on the server as B remote
382 branch on your local repository, then tries to merge B into the
383 currently checked out branch.
385 To remember which branch is currently checked out, run 'git branch',
386 which will list all branches and mark the currently checked out branch
387 with a star, or 'git status'.
390 * To merge branch FOO into branch BAR, i.e. to "add" all changes made
391 in branch FOO to branch BAR, run
396 If any conflict happens, please carefully follow the instructions
397 given by 'git merge' -- you usually must resolve conflicts with a text
398 editor by merging pieces of files marked with "<<<" "===" and ">>>",
399 removing these 3 kinds of conflict marks, then commit the result
400 exactly like a usual commit.
402 For example, as a translator, you will often want to merge master into
403 lilypond/translation; on the other hand, the Translations meister
404 wants to merge lilypond/translation into master whenever he has
405 checked that lilypond/translation builds successfully.
408 * If you play with several Git branches (e.g. master,
409 lilypond/translation, stable/2.12), you may want to have one source
410 and build tree for each branch; this is possible with subdirectories
411 of your local Git repository, used as local cloned subrepositories.
412 To create a local clone for the branch named BRANCH, run
415 git clone -l -s -n . SUBDIR
419 Note that SUBDIR must be a directory name which does not already
420 exist. In SUBDIR, you can use all Git commands to browse revisions
421 history, commit and uncommit changes; to update the cloned
422 subrepository with changes made on the main repository, cd into SUBDIR
423 and run 'git pull'; to send changes made on the subrepository back to
424 the main repository, run 'git push' from SUBDIR. Note that only one
425 branch (the currently checked out branch) is created in the
426 subrepository by deafult; it is possible to have several branches in a
427 subrepository and do usual operations (checkout, merge, create,
428 delete...) on these branches, but this is more difficult to manage
429 them and sync them with the main repository, so this possibility is
435 A number of Python scripts handle a part of the documentation
438 * langdefs.py -- language definitions
439 * check_translation.py -- show diff to update a translation
440 * texi-langutils.py -- quickly and dirtily parse Texinfo files to
441 make message catalogs and Texinfo skeleton files
442 * texi-skeleton-update.py -- update Texinfo skeleton files
443 * html-gettext.py -- translate node names, section titles and cross
444 references in HTML files generated by makeinfo
445 * add_html_footer.py (module called by www_post.py) -- add footer and
446 tweak links in HTML pages
447 * texi-gettext.py -- gettext node names, section titles and references
448 before calling texi2pdf
449 * mass-link.py -- link or symlink files between English documentation
450 and documentation in other languages
451 * update-snippets.py -- synchronize ly snippets with those from
453 * translations-status.py -- update translations status pages and word
454 counts in the file you are reading