1 LILYPOND DOCUMENTATION TRANSLATION
8 WHICH DOCUMENTATION CAN BE TRANSLATED
9 STARTING A TRANSLATION IN A NEW LANGUAGE
10 FILES TO BE TRANSLATED
11 TRANSLATION DETAILED INSTRUCTIONS
12 * LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
13 * REFERENCE NOTATION AND PROGRAM USAGE MANUAL
14 * DOCUMENTATION INDEX index.html.in
15 CHECK STATE OF TRANSLATION
17 POLICY DURING GDP PROCESS
18 MANAGING TRANSLATIONS WITH GIT
20 DEALING WITH SEVERAL GIT BRANCHES
27 The sources live in a GIT repository. Git 1.5.x is required, and
28 latest version available on your platform is always recommended. To
29 get a fresh version of LilyPond sources run
31 mkdir lily ; cd lily ; git init-db ; mkdir .git/remotes
33 then write the two following lines to a text file named .git/remotes/trans
35 URL: git://git.sv.gnu.org/lilypond.git/
36 Pull: lilypond/translation:refs/remotes/origin/lilypond/translation
41 git checkout -b lilypond/translation origin/lilypond/translation
46 The reader is supposed to be familiar with Git, for example by
47 having experience from lilypond.org translation; see
48 http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=README;hb=web/master
53 Working on LilyPond documentation translations requires:
60 WHICH DOCUMENTATION CAN BE TRANSLATED
62 The makfiles and scripts infrastructure currently supports translation
63 of the following documentation:
65 * documentation index (HTML)
66 * user manual and program usage -- Texinfo source, PDF and HTML
67 output; Info output might be added if there is enough demand for it.
70 STARTING A TRANSLATION IN A NEW LANGUAGE
72 At top of the source directory, do
76 or (if you want to install your self-compiled LilyPond locally):
78 ./autogen.sh --prefix=$HOME
80 If you want to compile LilyPond -- which is almost required to build
81 the docs, but is not required to do translation only -- fix all
82 dependencies and rerun ./configure (with the same options as for
85 Cd into Documentation and run:
87 make ISOLANG=<MY-LANGUAGE> new-lang
89 where <MY-LANGUAGE> is the ISO 639 language code.
91 Add a language definition for your language in
92 buildscripts/langdefs.py.
94 See next section about what files to translate and the following
95 detailed instructions after the next section.
98 FILES TO BE TRANSLATED
100 All the following files are in Documentation/
101 Translation of Documentation/foo/bar should be
102 Documentation/<LANG>/foo/bar.
103 Unmentioned files should not be translated.
110 Files marked with priority 3, 4 or 5 may be submitted individually.
111 Word counts (excluding lilypond snippets) are given for each file.
113 -1- Documentation index and Tutorial
114 407 user/lilypond-learning.tely
115 6365 user/tutorial.itely
116 23 user/dedication.itely
117 423 user/macros.itexi
119 6411 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
122 -2- Introduction and beginning of Application Usage
123 411 user/preface.itely
124 3855 user/introduction.itely
125 385 user/lilypond-program.tely
126 1930 user/install.itely (partial translation)
127 1149 user/setup.itely
128 2896 user/running.itely
132 10318 user/fundamental.itely -- Fundamental concepts
133 14581 user/tweaks.itely -- Tweaking output
134 3007 user/working.itely -- Working on LilyPond files
135 483 user/templates.itely -- Templates
138 -4- Notation reference
139 672 user/lilypond.tely
140 91 user/notation.itely -- Musical notation
141 3086 user/pitches.itely
142 5013 user/rhythms.itely
143 1146 user/expressive.itely
144 555 user/repeats.itely
145 1455 user/simultaneous.itely
146 1635 user/staff.itely
147 906 user/editorial.itely
149 76 user/specialist.itely -- Specialist notation
150 2638 user/vocal.itely
151 1333 user/chords.itely
153 810 user/percussion.itely
154 826 user/guitar.itely
155 66 user/strings.itely
156 242 user/bagpipes.itely
157 4486 user/ancient.itely
158 5805 user/input.itely -- Input syntax
159 2164 user/non-music.itely -- Non-musical notation
160 8444 user/spacing.itely -- Spacing issues
161 11291 user/changing-defaults.itely -- Changing defaults
162 5202 user/programming-interface.itely -- Interfaces for programmers
163 1155 user/notation-appendices.itely -- Notation manual tables
164 250 user/cheatsheet.itely -- Cheat sheet
167 -5- Application usage
168 3202 user/lilypond-book.itely -- LilyPond-book
169 1171 user/converters.itely -- Converting from other formats
172 -6- Appendices whose translation is optional
173 310 user/literature.itely
174 960 user/scheme-tutorial.itely (needs to be revised first)
178 TRANSLATION DETAILED INSTRUCTIONS
180 Please follow all these instructions with care to ensure quality work.
182 All files should be encoded in UTF-8.
184 * LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
186 Any title which comes with one of the following commands must not be
187 translated directly in the Texinfo source
190 @chapter @unnumbered @appendix @chapheading
191 @section @unnumberedsec @appendixsec @heading
192 @subsection @unnumberedsubsec @appendixsubsec @subheading
193 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
196 As a notable exception, the second argument 'Bar baz' of
197 @ref{Foo,'Bar baz',,info-file} should be translated.
199 @uref's names are to be translated.
201 In any section which looks like
209 the node names (nodeN) are NOT to be translated, whereas extra title
210 information (thingN) is.
212 Every node name or section title must from now on be translated
213 separately in a .po file (just as well as LilyPond output messages).
214 This .po file should be in Documentation/po.
217 Take care of using typographic rules for your language, especially in
221 Please keep verbatim copies of music snippets (in @lilypond blocs).
222 However, some music snippets containing text that shows in the
223 rendered music, and sometimes translating this text really helps the
224 user to understand the documentation; in this case, and only in this
225 case, you may as an exception translate text in the music snippet, and
226 then you must add a line immediately before the @lilypond block,
231 Otherwise the music snippet would be reset to the same content as the
232 English version at next 'make snippet-update' run (see UPDATING A
237 @lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}
239 in the source, open input/lsr/FILENAME.ly, translate the `texidoc'
240 header field it contains, enclose it with 'texidoc<MY-LANGUAGE> = "'
241 and '"', and write it into input/texidocs/FILENAME.texidoc -- please
242 keep possibly existing translations in other languages!
243 Additionnally, you may translate the snippet's title in `doctitle'
244 header field, in case `doctitle' is a fragment option used in
245 @lilypondfile; you can do this exactly the same way as `texidoc'. For
246 instance, input/texidocs/FILENAME.texidoc may contain
248 doctitlees = "Spanish title baz"
250 Spanish translation blah
252 doctitlede = "German title bar"
253 texidocde = "German translation foo
257 @example blocs need not be verbatim copies, e.g. variable names,
258 file names and comments should be translated.
260 Index entries (@cindex and so on) should be translated.
262 Carefully apply every rule exposed in Documentation/README.txt. If
263 one of these rules conflicts with a rule specific to your language,
264 please ask the Translation meister and/or the Documentation Editor on
265 lilypond-devel@gnu.org.
268 * REFERENCE NOTATION AND PROGRAM USAGE MANUAL
270 Copy user/lilypond.tely (or user/lilypond-program.tely, respectively)
271 into <MY-LANGUAGE>/user, then translate this file and run
272 skeleton-update (see UPDATE A TRANSLATION below). Your are now ready
273 to translate notation reference (program usage manual, respectively)
274 exactly like the learning manual.
277 * DOCUMENTATION INDEX index.html.in
279 Unlike almost all HTML pages in this documentation, links in this page
280 are not tweaked by add_html_footer.py, so links should be manually
281 edited to link to existing translations.
284 CHECK STATE OF TRANSLATION
286 First pull, then cd into Documentation (or at top of the source tree,
287 replace 'make' with 'make -C Documentation') and run
289 make ISOLANG=<MY_LANGUAGE> check-translation
291 This presents a diff of the original files since the most recent
292 revision of the translation. To check a single file, cd into
293 Documentation and run
295 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely check-translation
298 Small tip: to see only which files need to be updated, do
300 make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
302 To avoid printing terminal colors control characters, which is often
303 desirable when you redirect output to a file, run
305 make ISOLANG=<MY_LANGUAGE> NO_COLOR=1 check-translation
308 Global state of the translation is recorded in
309 Documentation/translations.html.in, which is used to generate
310 Translations status page. To update that page, do from Documentation/
312 make translation-status
314 This will also leave out/translations-status.txt, which contains
315 up-to-dateness percentages for each translated file, and update word
316 counts of documentation files in this file.
321 Instead of running check-translation, you can run update-translation,
322 which will run your favorite text editor to update files. First, make
323 sure environment variable EDITOR is set to a text editor command, then
324 run from Documentation
326 make ISOLANG=<MY-LANGUAGE> update-translation
328 or to update a single file
330 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely update-translation
332 For each file to be udpated, update-translation will open your text
333 editor with this file and a diff of the file in English; if the diff
334 cannot be generated or is bigger than the file in English itself, the
335 full file in English will be opened instead.
337 Texinfo skeleton files, i.e. .itely files not yet translated,
338 containing only the Texinfo structure can be updated automatically:
339 whenever 'make check-translation' shows that such files should be
340 updated, run from Documentation
342 make ISOLANG=<MY_LANGUAGE> skeleton-update
344 .po message catalogs in Documentation/po may be updated with (from
345 Documentation or Documentation/po)
349 WARNING: if you run po-update and somebody else does the same and
350 pushes before you push or send a patch to be applied, there will be a
351 conflict when you pull. Therefore, it is better that only the
352 Translation meister runs this command.
354 Updating music snippets can quickly become cumbersome, as most
355 snippets should be identical in all languages. Fortunately, there is
356 a script that can do this odd job for you (run from Documentation):
358 make ISOLANG=<MY_LANGUAGE> snippet-update
360 This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
361 with music snippets from user/every.itely. It ignores skeleton files,
362 and keeps intact music snippets preceded with a line starting with '@c
363 KEEP LY'; it reports an error for each .itely that has not the same
364 music snippet count in both languages. Always use this script with a
365 lot of care, i.e. run it on a clean Git working tree, and check the
366 changes it made with "git diff" before committing; if you don't do so,
367 some @lilypond snippets might be broken or make no sense in their
370 Finally, a command runs the three update processes above for all
371 enabled languages (from Documentation):
373 make all-translations-update
375 Use this command with caution, and keep in mind it will not be really
376 useful until translations are stabilized after the end of GDP.
379 POLICY DURING GDP PROCESS
380 or "How to maintain translations without updating them"
382 During GDP progress, documentation changes so much, and translators are
383 often involved in GDP too, so keeping translations up to date is very
384 difficult. However, it is possible -- and even recommended -- to
385 perform some maintaining that keeps translated documentation usable
386 and eases future translation updating. The rationale below the tasks
387 list motivates this plan.
389 The following tasks are listed in decreasing priority order.
391 1) Update macros.itexi. For each obsolete macro definition, if it is
392 possible to update macro usage in documentation with an automatic text
393 or regexp substitution, do it and delete the macro definition from
394 macros.itexi; otherwise, mark this macro definition as obsolete with a
395 comment, and keep it in macros.itexi until the documentation
396 translation has been updated and no longer uses this macro.
398 2) Update *.tely files completely with make check-translation -- you
399 may want to redirect ouptput to a file because of overwhelming output,
400 or call check-translation.py on individual files, see CHECK STATE OF
403 3) in .itelys, match sections and .itely file names with those from
404 English docs, which possibly involves moving nodes contents in block
405 between files, without updating contents itself. In other words, the
406 game is catching where has gone each section. In Learning manual, and
407 in Notation Reference sections which have been revised in GDP, there
408 may be completely new sections: in this case, copy @node and
409 @section-command from English docs, and add the marker for
410 untranslated status '@untranslated' on a single line. Note that it is
411 not possible to exactly match subsections or subsubsections of
412 documentation in English, when contents has been deeply revised; in
413 this case, keep obsolete (sub)subsections in the translation, marking
414 them with a line '@c obsolete' just before the node.
416 4) update sections finished in GDP; check sections status at GDP website.
419 * Hints for Emacs users
421 Emacs with Texinfo mode makes this step easier:
423 - without Emacs AucTeX installed, C-c C-s shows structure of current
424 Texinfo file in a new buffer *Occur*; to show structure of two files
425 simultaneously, first split Emacs window in 4 tiles (with C-x 1 and
426 C-x 2), press C-c C-s to show structure of one file (e.g. the translated
427 file), copy *Occur* contents into *Scratch*, then press C-c C-s for the
429 If you happen to have installed AucTeX, you can either call the macro
430 by doing M-x texinfo-show-structure or create a key binding in your
431 ~/.emacs, by adding the four following lines:
432 (add-hook 'Texinfo-mode-hook
434 (define-key Texinfo-mode-map "\C-cs"
435 'texinfo-show-structure)))
436 and then obtain the structure in the *Occur* buffer with C-c s
439 - Do not bother updating @menus when all menu entries are in the same
440 file ; make sure there is at least a (possibly empty) @menu block
441 everywhere it is needed, then do C-c C-u C-a ("update all menus") when
442 you have updated all the rest of the file.
444 - Moving to next or previous node: press C-s and type node (or C-s
445 @node if the text contains the word 'node') then press C-s to move to
446 next node or C-r to move to previous node. Similar operation can be
447 used to move to the next/previous section.
449 - Moving a whole node (or even a sequence of nodes): jump to beginning
450 of the node (quit incremental search by pressing an arrow), press
451 C-SPACE, press C-s node and repeat C-s until you have selected enough
452 text, cut it with C-w or C-x, jump to the right place (moving between
453 nodes with the previous hint is often useful) and paste with C-y or
457 4) update documentation PO. Unless you have special interest in
458 having all titles translated in the next development release, it is
459 better to wait until step 3) has been completed, to avoid doing the
462 5) Fix broken cross-references by running (from Documentation/)
464 make ISOLANG=<YOUR-LANGUAGE> fix-xrefs
466 This step requires a sucessful documentation build (with 'make web').
467 Some cross-references are broken because they point to a node that
468 exists in the documentation in English, which has not been added to
469 the translation; in this case, do not fix the cross-reference but keep
470 it "broken", so that the resulting HTML link will point to an existing
471 page of documentation in English.
475 You may wonder if it would not be better to leave translations as-is
476 until you can really start updating translations. There are several
477 reasons to do these maintenance tasks right now.
479 - This will have to be done sooner or later anyway, before updating
480 translation of documentation contents, and this can already be done
481 without needing to be redone later, as sections of documentation in
482 English are mostly revised once. However, note that not all
483 documentation sectioning has been revised in one go, so all this
484 maintenance plan has to be repeated whenever a big reorganization is
485 made. Currently (in May 2008), only chapters 3-7 in Notation Reference
486 and Application Usage have not been reorganized yet.
488 - This just makes translated documentation take advantage of the new
489 organization, which is far better than the old one.
491 - Moving and renaming sections to match sectioning of documentation in
492 English simplify future updating work: it allows updating the
493 translation by side-by-side comparison, without bothering whether
494 cross-reference names already exist in the translation.
496 - Each maintenance task (except 4) updating PO files) can be done by
497 the same person for all languages, which saves overall time spent by
498 translators to achieve this task: the node names and section titles
499 are in English, so you can do. It is important to take advantage of
500 this now, as it will be more complicated (but still possible) to do
501 step 3) in all languages when documentation is compiled with
502 texi2html and node names are directly translated in source files.
505 MANAGING TRANSLATIONS WITH GIT
507 This policy explains how to manage Git branches and commit
510 * Translation changes matching master branch are preferably made on
511 lilypond/translation branch; they may be pushed directly on master
512 only if they do not break compilation of LilyPond and its
513 documentation, and in this case they should be pushed to
514 lilypond/translation too. Similarly, changes matching stable/X.Y are
515 preferably made on lilypond/X.Ytranslation.
517 * lilypond/translation Git branch may be merged into master only if
518 LilyPond ('make all') and documentation ('make web') compile
521 * master Git branch may be merged into lilypond/translation whenever
522 'make' and 'make web' are succesful (in order to ease documentation
523 compilation by translators), or when significant changes had been made
524 in documentation in English in master branch.
526 * General maintenance may be done by anybody who knows what he does
527 in documentation in all languages, without informing translators
528 first. General maintenance include simple text substitutions
529 (e.g. automated by sed), compilation fixes, updating Texinfo or
530 lilypond-book commands, updating macros, updating ly code, fixing
531 cross-references, and operations described in 'POLICY DURING GDP
537 * Saving uncommited changes in the working tree:
541 This does not save untracked or ignored files. If you prefer to
542 include changes added to the index with 'git add', replace 'git diff'
543 with 'git diff HEAD'.
544 Then, you may try to apply foo.diff on a source tree with
549 DEALING WITH SEVERAL GIT BRANCHES
551 * It is possible to work with several branches on the same local Git
552 repository; this is especially useful for translators who may have to
553 deal with both lilypond/translation and a stable branch
554 (e.g. stable/2.12 or lilypond/translation-2.12). To fetch and check
555 out a new branch named BRANCH on git.sv.gnu.org, write the two
556 following lines to a text file named .git/remotes/SHORTHAND --
557 SHORTHAND is the name of the remote file, i.e. whatever easy-to-type
558 name you would like to use when pulling or pushing BRANCH, and usually
559 SHORTHAND is an abbreviation of BRANCH without slashes
561 URL: git://git.sv.gnu.org/lilypond.git/
562 Pull: BRANCH:refs/remotes/origin/BRANCH
567 git checkout -b BRANCH origin/BRANCH
569 After this, you are able to pull BRANCH from git.sv.gnu.org with
573 You can check out another branch OTHER_BRANCH, i.e. check out
574 OTHER_BRANCH to the working tree, with
576 git checkout OTHER_BRANCH
578 E.g. lilypond/translation, which you still have in your local Git
579 repository but is no longer checked out since you have created the new
582 Note that it is possible to check out another branch while having
583 uncommitted changes, but it is not recommended unless you know what
584 you are doing; it is recommended to run 'git status' to check this
585 kind of issue before checking out another branch.
587 When pulling using SHORTHAND, do not forget to check first that the
588 right branch is checked out, i.e. the branch named A in the first part
589 of the "A:B" refspec in .git/remotes/SHORTHAND: as a matter of fact,
590 when you pull using A:B refspec, Git fetch A on the server as B remote
591 branch on your local repository, then tries to merge B into the
592 currently checked out branch.
594 To remember which branch is currently checked out, run 'git branch',
595 which will list all branches and mark the currently checked out branch
596 with a star, or 'git status'.
599 * To merge branch FOO into branch BAR, i.e. to "add" all changes made
600 in branch FOO to branch BAR, run
605 If any conflict happens, please carefully follow the instructions
606 given by 'git merge' -- you usually must resolve conflicts with a text
607 editor by merging pieces of files marked with "<<<" "===" and ">>>",
608 removing these 3 kinds of conflict marks, then commit the result
609 exactly like a usual commit.
611 For example, as a translator, you will often want to merge master into
612 lilypond/translation; on the other hand, the Translations meister
613 wants to merge lilypond/translation into master whenever he has
614 checked that lilypond/translation builds successfully.
617 * If you play with several Git branches (e.g. master,
618 lilypond/translation, stable/2.12), you may want to have one source
619 and build tree for each branch; this is possible with subdirectories
620 of your local Git repository, used as local cloned subrepositories.
621 To create a local clone for the branch named BRANCH, run
624 git clone -l -s -n . SUBDIR
628 Note that SUBDIR must be a directory name which does not already
629 exist. In SUBDIR, you can use all Git commands to browse revisions
630 history, commit and uncommit changes; to update the cloned
631 subrepository with changes made on the main repository, cd into SUBDIR
632 and run 'git pull'; to send changes made on the subrepository back to
633 the main repository, run 'git push' from SUBDIR. Note that only one
634 branch (the currently checked out branch) is created in the
635 subrepository by default; it is possible to have several branches in a
636 subrepository and do usual operations (checkout, merge, create,
637 delete...) on these branches, but this possibility is not detailed
640 Note that when you push BRANCH from SUBDIR to the main repository,
641 and BRANCH is checked out in the main repository, you must save
642 uncommitted changes (see SOME GIT TIPS) and do 'git reset --hard' in
643 the main repository in order to apply pushed changes in the working
644 tree of the main repository.
649 If you have permission to push to Git with login USER, please start a
650 new Git repository from scratch to avoid polluting history with
651 duplicate commits; follow the usual instructions, except that every
652 file you write in .git/remotes should contain instead
654 URL: ssh://USER@git.sv.gnu.org/srv/git/lilypond.git
655 Push: BRANCH:refs/heads/BRANCH
656 Pull: BRANCH:refs/remotes/origin/BRANCH
658 Then, you can use .git/remotes/NAME to push BRANCH with
662 which works regardless of the branch checked out.
667 A number of Python scripts handle a part of the documentation
668 translation process. All are located in buildscripts/, except
669 langdefs.py which is in python/
671 * buildlib.py -- module containing common functions (read piped output
672 of a shell command, use Git)
673 * langdefs.py -- language definitions module
674 * check_translation.py -- show diff to update a translation
675 * texi-langutils.py -- quickly and dirtily parse Texinfo files to
676 make message catalogs and Texinfo skeleton files
677 * texi-skeleton-update.py -- update Texinfo skeleton files
678 * html-gettext.py -- translate node names, section titles and cross
679 references in HTML files generated by makeinfo
680 * add_html_footer.py (module imported by www_post.py) -- add footer and
681 tweak links in HTML pages
682 * texi-gettext.py -- gettext node names, section titles and references
683 before calling texi2pdf
684 * mass-link.py -- link or symlink files between English documentation
685 and documentation in other languages
686 * update-snippets.py -- synchronize ly snippets with those from
688 * translations-status.py -- update translations status pages and word
689 counts in the file you are reading.