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 429 user/lilypond-learning.tely
115 6365 user/tutorial.itely
116 23 user/dedication.itely
117 423 user/macros.itexi
119 6420 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
120 --- ../lilypond-texi2html.init (section TRANSLATIONS)
123 -2- Introduction and beginning of Application Usage
124 411 user/preface.itely
125 3855 user/introduction.itely
126 407 user/lilypond-program.tely
127 1930 user/install.itely (partial translation)
128 1149 user/setup.itely
129 2827 user/running.itely
133 10318 user/fundamental.itely -- Fundamental concepts
134 14581 user/tweaks.itely -- Tweaking output
135 3007 user/working.itely -- Working on LilyPond files
136 483 user/templates.itely -- Templates
139 -4- Notation reference
140 695 user/lilypond.tely
141 91 user/notation.itely -- Musical notation
142 3086 user/pitches.itely
143 5013 user/rhythms.itely
144 1146 user/expressive.itely
145 555 user/repeats.itely
146 1455 user/simultaneous.itely
147 1635 user/staff.itely
148 906 user/editorial.itely
150 76 user/specialist.itely -- Specialist notation
151 2670 user/vocal.itely
152 1333 user/chords.itely
154 810 user/percussion.itely
155 826 user/guitar.itely
156 66 user/strings.itely
157 242 user/bagpipes.itely
158 4486 user/ancient.itely
159 5805 user/input.itely -- Input syntax
160 2164 user/non-music.itely -- Non-musical notation
161 8444 user/spacing.itely -- Spacing issues
162 11291 user/changing-defaults.itely -- Changing defaults
163 5202 user/programming-interface.itely -- Interfaces for programmers
164 1155 user/notation-appendices.itely -- Notation manual tables
165 250 user/cheatsheet.itely -- Cheat sheet
168 -5- Application usage
169 3185 user/lilypond-book.itely -- LilyPond-book
170 1171 user/converters.itely -- Converting from other formats
173 -6- Appendices whose translation is optional
174 310 user/literature.itely
175 960 user/scheme-tutorial.itely (needs to be revised first)
179 TRANSLATION DETAILED INSTRUCTIONS
181 Please follow all these instructions with care to ensure quality work.
183 All files should be encoded in UTF-8.
185 * LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
187 Any title which comes with one of the following commands must not be
188 translated directly in the Texinfo source
191 @chapter @unnumbered @appendix @chapheading
192 @section @unnumberedsec @appendixsec @heading
193 @subsection @unnumberedsubsec @appendixsubsec @subheading
194 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
197 As a notable exception, the second argument 'Bar baz' of
198 @ref{Foo,'Bar baz',,info-file} should be translated.
200 @uref's names are to be translated.
202 In any section which looks like
210 the node names (nodeN) are NOT to be translated, whereas extra title
211 information (thingN) is.
213 Every node name or section title must from now on be translated
214 separately in a .po file (just as well as LilyPond output messages).
215 This .po file should be in Documentation/po.
218 Take care of using typographic rules for your language, especially in
222 Please keep verbatim copies of music snippets (in @lilypond blocs).
223 However, some music snippets containing text that shows in the
224 rendered music, and sometimes translating this text really helps the
225 user to understand the documentation; in this case, and only in this
226 case, you may as an exception translate text in the music snippet, and
227 then you must add a line immediately before the @lilypond block,
232 Otherwise the music snippet would be reset to the same content as the
233 English version at next 'make snippet-update' run (see UPDATING A
238 @lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}
240 in the source, open input/lsr/FILENAME.ly, translate the `texidoc'
241 header field it contains, enclose it with 'texidoc<MY-LANGUAGE> = "'
242 and '"', and write it into input/texidocs/FILENAME.texidoc -- please
243 keep possibly existing translations in other languages!
244 Additionnally, you may translate the snippet's title in `doctitle'
245 header field, in case `doctitle' is a fragment option used in
246 @lilypondfile; you can do this exactly the same way as `texidoc'. For
247 instance, input/texidocs/FILENAME.texidoc may contain
249 doctitlees = "Spanish title baz"
251 Spanish translation blah
253 doctitlede = "German title bar"
254 texidocde = "German translation foo
258 @example blocs need not be verbatim copies, e.g. variable names,
259 file names and comments should be translated.
261 Index entries (@cindex and so on) should be translated.
263 Carefully apply every rule exposed in Documentation/README.txt. If
264 one of these rules conflicts with a rule specific to your language,
265 please ask the Translation meister and/or the Documentation Editor on
266 lilypond-devel@gnu.org.
269 * REFERENCE NOTATION AND PROGRAM USAGE MANUAL
271 Copy user/lilypond.tely (or user/lilypond-program.tely, respectively)
272 into <MY-LANGUAGE>/user, then translate this file and run
273 skeleton-update (see UPDATE A TRANSLATION below). Your are now ready
274 to translate notation reference (program usage manual, respectively)
275 exactly like the learning manual.
278 * DOCUMENTATION INDEX index.html.in
280 Unlike almost all HTML pages in this documentation, links in this page
281 are not tweaked by add_html_footer.py, so links should be manually
282 edited to link to existing translations.
285 CHECK STATE OF TRANSLATION
287 First pull, then cd into Documentation (or at top of the source tree,
288 replace 'make' with 'make -C Documentation') and run
290 make ISOLANG=<MY_LANGUAGE> check-translation
292 This presents a diff of the original files since the most recent
293 revision of the translation. To check a single file, cd into
294 Documentation and run
296 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely check-translation
299 Small tip: to see only which files need to be updated, do
301 make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
303 To avoid printing terminal colors control characters, which is often
304 desirable when you redirect output to a file, run
306 make ISOLANG=<MY_LANGUAGE> NO_COLOR=1 check-translation
309 Global state of the translation is recorded in
310 Documentation/translations.html.in, which is used to generate
311 Translations status page. To update that page, do from Documentation/
313 make translation-status
315 This will also leave out/translations-status.txt, which contains
316 up-to-dateness percentages for each translated file, and update word
317 counts of documentation files in this file.
322 Instead of running check-translation, you can run update-translation,
323 which will run your favorite text editor to update files. First, make
324 sure environment variable EDITOR is set to a text editor command, then
325 run from Documentation
327 make ISOLANG=<MY-LANGUAGE> update-translation
329 or to update a single file
331 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely update-translation
333 For each file to be udpated, update-translation will open your text
334 editor with this file and a diff of the file in English; if the diff
335 cannot be generated or is bigger than the file in English itself, the
336 full file in English will be opened instead.
338 Texinfo skeleton files, i.e. .itely files not yet translated,
339 containing only the Texinfo structure can be updated automatically:
340 whenever 'make check-translation' shows that such files should be
341 updated, run from Documentation
343 make ISOLANG=<MY_LANGUAGE> skeleton-update
345 .po message catalogs in Documentation/po may be updated with (from
346 Documentation or Documentation/po)
350 WARNING: if you run po-update and somebody else does the same and
351 pushes before you push or send a patch to be applied, there will be a
352 conflict when you pull. Therefore, it is better that only the
353 Translation meister runs this command.
355 Updating music snippets can quickly become cumbersome, as most
356 snippets should be identical in all languages. Fortunately, there is
357 a script that can do this odd job for you (run from Documentation):
359 make ISOLANG=<MY_LANGUAGE> snippet-update
361 This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
362 with music snippets from user/every.itely. It ignores skeleton files,
363 and keeps intact music snippets preceded with a line starting with '@c
364 KEEP LY'; it reports an error for each .itely that has not the same
365 music snippet count in both languages. Always use this script with a
366 lot of care, i.e. run it on a clean Git working tree, and check the
367 changes it made with "git diff" before committing; if you don't do so,
368 some @lilypond snippets might be broken or make no sense in their
371 Finally, a command runs the three update processes above for all
372 enabled languages (from Documentation):
374 make all-translations-update
376 Use this command with caution, and keep in mind it will not be really
377 useful until translations are stabilized after the end of GDP.
380 POLICY DURING GDP PROCESS
381 or "How to maintain translations without updating them"
383 During GDP progress, documentation changes so much, and translators are
384 often involved in GDP too, so keeping translations up to date is very
385 difficult. However, it is possible -- and even recommended -- to
386 perform some maintaining that keeps translated documentation usable
387 and eases future translation updating. The rationale below the tasks
388 list motivates this plan.
390 The following tasks are listed in decreasing priority order.
392 1) Update macros.itexi. For each obsolete macro definition, if it is
393 possible to update macro usage in documentation with an automatic text
394 or regexp substitution, do it and delete the macro definition from
395 macros.itexi; otherwise, mark this macro definition as obsolete with a
396 comment, and keep it in macros.itexi until the documentation
397 translation has been updated and no longer uses this macro.
399 2) Update *.tely files completely with make check-translation -- you
400 may want to redirect ouptput to a file because of overwhelming output,
401 or call check-translation.py on individual files, see CHECK STATE OF
404 3) in .itelys, match sections and .itely file names with those from
405 English docs, which possibly involves moving nodes contents in block
406 between files, without updating contents itself. In other words, the
407 game is catching where has gone each section. In Learning manual, and
408 in Notation Reference sections which have been revised in GDP, there
409 may be completely new sections: in this case, copy @node and
410 @section-command from English docs, and add the marker for
411 untranslated status '@untranslated' on a single line. Note that it is
412 not possible to exactly match subsections or subsubsections of
413 documentation in English, when contents has been deeply revised; in
414 this case, keep obsolete (sub)subsections in the translation, marking
415 them with a line '@c obsolete' just before the node.
417 4) update sections finished in GDP; check sections status at GDP website.
420 * Hints for Emacs users
422 Emacs with Texinfo mode makes this step easier:
424 - without Emacs AucTeX installed, C-c C-s shows structure of current
425 Texinfo file in a new buffer *Occur*; to show structure of two files
426 simultaneously, first split Emacs window in 4 tiles (with C-x 1 and
427 C-x 2), press C-c C-s to show structure of one file (e.g. the translated
428 file), copy *Occur* contents into *Scratch*, then press C-c C-s for the
430 If you happen to have installed AucTeX, you can either call the macro
431 by doing M-x texinfo-show-structure or create a key binding in your
432 ~/.emacs, by adding the four following lines:
433 (add-hook 'Texinfo-mode-hook
435 (define-key Texinfo-mode-map "\C-cs"
436 'texinfo-show-structure)))
437 and then obtain the structure in the *Occur* buffer with C-c s
440 - Do not bother updating @menus when all menu entries are in the same
441 file ; make sure there is at least a (possibly empty) @menu block
442 everywhere it is needed, then do C-c C-u C-a ("update all menus") when
443 you have updated all the rest of the file.
445 - Moving to next or previous node: press C-s and type node (or C-s
446 @node if the text contains the word 'node') then press C-s to move to
447 next node or C-r to move to previous node. Similar operation can be
448 used to move to the next/previous section.
450 - Moving a whole node (or even a sequence of nodes): jump to beginning
451 of the node (quit incremental search by pressing an arrow), press
452 C-SPACE, press C-s node and repeat C-s until you have selected enough
453 text, cut it with C-w or C-x, jump to the right place (moving between
454 nodes with the previous hint is often useful) and paste with C-y or
458 4) update documentation PO. Unless you have special interest in
459 having all titles translated in the next development release, it is
460 better to wait until step 3) has been completed, to avoid doing the
463 5) Fix broken cross-references by running (from Documentation/)
465 make ISOLANG=<YOUR-LANGUAGE> fix-xrefs
467 This step requires a sucessful documentation build (with 'make web').
468 Some cross-references are broken because they point to a node that
469 exists in the documentation in English, which has not been added to
470 the translation; in this case, do not fix the cross-reference but keep
471 it "broken", so that the resulting HTML link will point to an existing
472 page of documentation in English.
476 You may wonder if it would not be better to leave translations as-is
477 until you can really start updating translations. There are several
478 reasons to do these maintenance tasks right now.
480 - This will have to be done sooner or later anyway, before updating
481 translation of documentation contents, and this can already be done
482 without needing to be redone later, as sections of documentation in
483 English are mostly revised once. However, note that not all
484 documentation sectioning has been revised in one go, so all this
485 maintenance plan has to be repeated whenever a big reorganization is
486 made. Currently (in May 2008), only chapters 3-7 in Notation Reference
487 and Application Usage have not been reorganized yet.
489 - This just makes translated documentation take advantage of the new
490 organization, which is far better than the old one.
492 - Moving and renaming sections to match sectioning of documentation in
493 English simplify future updating work: it allows updating the
494 translation by side-by-side comparison, without bothering whether
495 cross-reference names already exist in the translation.
497 - Each maintenance task (except 4) updating PO files) can be done by
498 the same person for all languages, which saves overall time spent by
499 translators to achieve this task: the node names and section titles
500 are in English, so you can do. It is important to take advantage of
501 this now, as it will be more complicated (but still possible) to do
502 step 3) in all languages when documentation is compiled with
503 texi2html and node names are directly translated in source files.
506 MANAGING TRANSLATIONS WITH GIT
508 This policy explains how to manage Git branches and commit
511 * Translation changes matching master branch are preferably made on
512 lilypond/translation branch; they may be pushed directly on master
513 only if they do not break compilation of LilyPond and its
514 documentation, and in this case they should be pushed to
515 lilypond/translation too. Similarly, changes matching stable/X.Y are
516 preferably made on lilypond/X.Ytranslation.
518 * lilypond/translation Git branch may be merged into master only if
519 LilyPond ('make all') and documentation ('make web') compile
522 * master Git branch may be merged into lilypond/translation whenever
523 'make' and 'make web' are succesful (in order to ease documentation
524 compilation by translators), or when significant changes had been made
525 in documentation in English in master branch.
527 * General maintenance may be done by anybody who knows what he does
528 in documentation in all languages, without informing translators
529 first. General maintenance include simple text substitutions
530 (e.g. automated by sed), compilation fixes, updating Texinfo or
531 lilypond-book commands, updating macros, updating ly code, fixing
532 cross-references, and operations described in 'POLICY DURING GDP
538 * Saving uncommited changes in the working tree:
542 This does not save untracked or ignored files. If you prefer to
543 include changes added to the index with 'git add', replace 'git diff'
544 with 'git diff HEAD'.
545 Then, you may try to apply foo.diff on a source tree with
550 DEALING WITH SEVERAL GIT BRANCHES
552 * It is possible to work with several branches on the same local Git
553 repository; this is especially useful for translators who may have to
554 deal with both lilypond/translation and a stable branch
555 (e.g. stable/2.12 or lilypond/translation-2.12). To fetch and check
556 out a new branch named BRANCH on git.sv.gnu.org, write the two
557 following lines to a text file named .git/remotes/SHORTHAND --
558 SHORTHAND is the name of the remote file, i.e. whatever easy-to-type
559 name you would like to use when pulling or pushing BRANCH, and usually
560 SHORTHAND is an abbreviation of BRANCH without slashes
562 URL: git://git.sv.gnu.org/lilypond.git/
563 Pull: BRANCH:refs/remotes/origin/BRANCH
568 git checkout -b BRANCH origin/BRANCH
570 After this, you are able to pull BRANCH from git.sv.gnu.org with
574 You can check out another branch OTHER_BRANCH, i.e. check out
575 OTHER_BRANCH to the working tree, with
577 git checkout OTHER_BRANCH
579 E.g. lilypond/translation, which you still have in your local Git
580 repository but is no longer checked out since you have created the new
583 Note that it is possible to check out another branch while having
584 uncommitted changes, but it is not recommended unless you know what
585 you are doing; it is recommended to run 'git status' to check this
586 kind of issue before checking out another branch.
588 When pulling using SHORTHAND, do not forget to check first that the
589 right branch is checked out, i.e. the branch named A in the first part
590 of the "A:B" refspec in .git/remotes/SHORTHAND: as a matter of fact,
591 when you pull using A:B refspec, Git fetch A on the server as B remote
592 branch on your local repository, then tries to merge B into the
593 currently checked out branch.
595 To remember which branch is currently checked out, run 'git branch',
596 which will list all branches and mark the currently checked out branch
597 with a star, or 'git status'.
600 * To merge branch FOO into branch BAR, i.e. to "add" all changes made
601 in branch FOO to branch BAR, run
606 If any conflict happens, please carefully follow the instructions
607 given by 'git merge' -- you usually must resolve conflicts with a text
608 editor by merging pieces of files marked with "<<<" "===" and ">>>",
609 removing these 3 kinds of conflict marks, then commit the result
610 exactly like a usual commit.
612 For example, as a translator, you will often want to merge master into
613 lilypond/translation; on the other hand, the Translations meister
614 wants to merge lilypond/translation into master whenever he has
615 checked that lilypond/translation builds successfully.
618 * If you play with several Git branches (e.g. master,
619 lilypond/translation, stable/2.12), you may want to have one source
620 and build tree for each branch; this is possible with subdirectories
621 of your local Git repository, used as local cloned subrepositories.
622 To create a local clone for the branch named BRANCH, run
625 git clone -l -s -n . SUBDIR
629 Note that SUBDIR must be a directory name which does not already
630 exist. In SUBDIR, you can use all Git commands to browse revisions
631 history, commit and uncommit changes; to update the cloned
632 subrepository with changes made on the main repository, cd into SUBDIR
633 and run 'git pull'; to send changes made on the subrepository back to
634 the main repository, run 'git push' from SUBDIR. Note that only one
635 branch (the currently checked out branch) is created in the
636 subrepository by default; it is possible to have several branches in a
637 subrepository and do usual operations (checkout, merge, create,
638 delete...) on these branches, but this possibility is not detailed
641 Note that when you push BRANCH from SUBDIR to the main repository,
642 and BRANCH is checked out in the main repository, you must save
643 uncommitted changes (see SOME GIT TIPS) and do 'git reset --hard' in
644 the main repository in order to apply pushed changes in the working
645 tree of the main repository.
650 If you have permission to push to Git with login USER, please start a
651 new Git repository from scratch to avoid polluting history with
652 duplicate commits; follow the usual instructions, except that every
653 file you write in .git/remotes should contain instead
655 URL: ssh://USER@git.sv.gnu.org/srv/git/lilypond.git
656 Push: BRANCH:refs/heads/BRANCH
657 Pull: BRANCH:refs/remotes/origin/BRANCH
659 Then, you can use .git/remotes/NAME to push BRANCH with
663 which works regardless of the branch checked out.
668 A number of Python scripts handle a part of the documentation
669 translation process. All are located in buildscripts/, except
670 langdefs.py which is in python/
672 * buildlib.py -- module containing common functions (read piped output
673 of a shell command, use Git)
674 * langdefs.py -- language definitions module
675 * check_translation.py -- show diff to update a translation
676 * texi-langutils.py -- quickly and dirtily parse Texinfo files to
677 make message catalogs and Texinfo skeleton files
678 * texi-skeleton-update.py -- update Texinfo skeleton files
679 * html-gettext.py -- translate node names, section titles and cross
680 references in HTML files generated by makeinfo
681 * add_html_footer.py (module imported by www_post.py) -- add footer and
682 tweak links in HTML pages
683 * texi-gettext.py -- gettext node names, section titles and references
684 before calling texi2pdf
685 * mass-link.py -- link or symlink files between English documentation
686 and documentation in other languages
687 * update-snippets.py -- synchronize ly snippets with those from
689 * translations-status.py -- update translations status pages and word
690 counts in the file you are reading.