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 ON GIT
19 DEALING WITH SEVERAL GIT BRANCHES
24 The sources live in a GIT repository. Git 1.5.x is required, and
25 latest version available on your platform is always recommended. To
26 get a fresh version of LilyPond sources run
28 mkdir lily ; cd lily ; git init-db ; mkdir .git/remotes
30 then write the two following lines to a text file named .git/remotes/trans
32 URL: git://git.sv.gnu.org/lilypond.git/
33 Pull: lilypond/translation:refs/remotes/origin/lilypond/translation
38 git checkout -b lilypond/translation origin/lilypond/translation
43 The reader is supposed to be familiar with Git, for example by
44 having experience from lilypond.org translation; see
45 http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=README;hb=web/master
50 Working on LilyPond documentation translations requires:
57 WHICH DOCUMENTATION CAN BE TRANSLATED
59 The makfiles and scripts infrastructure currently supports translation
60 of the following documentation:
62 * documentation index (HTML)
63 * user manual and program usage -- Texinfo source, PDF and HTML
64 output; Info output might be added if there is enough demand for it.
67 STARTING A TRANSLATION IN A NEW LANGUAGE
69 At top of the source directory, do
73 or (if you want to install your self-compiled LilyPond locally):
75 ./autogen.sh --prefix=$HOME
77 If you want to compile LilyPond -- which is almost required to build
78 the docs, but is not required to do translation only -- fix all
79 dependencies and rerun ./configure (with the same options as for
82 Cd into Documentation and run:
84 make ISOLANG=<MY-LANGUAGE> new-lang
86 where <MY-LANGUAGE> is the ISO 639 language code.
88 Add a language definition for your language in
89 buildscripts/langdefs.py.
91 See next section about what files to translate and the following
92 detailed instructions after the next section.
95 FILES TO BE TRANSLATED
97 All the following files are in Documentation/
98 Translation of Documentation/foo/bar should be
99 Documentation/<LANG>/foo/bar.
100 Unmentioned files should not be translated.
107 Files marked with priority 3, 4 or 5 may be submitted individually.
108 Word counts (excluding lilypond snippets) are given for each file.
110 -1- Documentation index and Tutorial
111 396 user/lilypond-learning.tely
112 5593 user/tutorial.itely
113 23 user/dedication.itely
114 100 user/macros.itexi
116 2022 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
119 -2- Introduction and beginning of Application Usage
120 411 user/preface.itely
121 3198 user/introduction.itely
122 374 user/lilypond-program.tely
123 1477 user/install.itely (partial translation)
125 2860 user/running.itely
129 8626 user/fundamental.itely -- Fundamental concepts
130 12134 user/tweaks.itely -- Tweaking output
131 2985 user/working.itely -- Working on LilyPond files
132 483 user/templates.itely -- Templates
135 -4- Notation reference
136 539 user/lilypond.tely
137 91 user/notation.itely -- Musical notation
138 2808 user/pitches.itely
139 7336 user/rhythms.itely
140 1681 user/expressive.itely
141 725 user/repeats.itely
142 916 user/simultaneous.itely
143 1861 user/staff.itely
144 879 user/editorial.itely
146 54 user/specialist.itely -- Specialist notation
147 2630 user/vocal.itely
148 1275 user/chords.itely
150 481 user/percussion.itely
151 826 user/guitar.itely
152 66 user/strings.itely
153 242 user/bagpipes.itely
154 4289 user/ancient.itely
155 2458 user/input.itely -- Input syntax
156 2164 user/non-music.itely -- Non-musical notation
157 8399 user/spacing.itely -- Spacing issues
158 5149 user/changing-defaults.itely -- Changing defaults
159 4547 user/programming-interface.itely -- Interfaces for programmers
160 935 user/notation-appendices.itely -- Notation manual tables
161 250 user/cheatsheet.itely -- Cheat sheet
164 -5- Application usage
165 2917 user/lilypond-book.itely -- LilyPond-book
166 975 user/converters.itely -- Converting from other formats
169 -6- Appendices whose translation is optional
170 299 user/literature.itely
171 960 user/scheme-tutorial.itely (needs to be revised first)
175 TRANSLATION DETAILED INSTRUCTIONS
177 Please follow all these instructions with care to ensure quality work.
179 All files should be encoded in UTF-8.
181 * LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
183 Any title which comes with one of the following commands must not be
184 translated directly in the Texinfo source
187 @chapter @unnumbered @appendix @chapheading
188 @section @unnumberedsec @appendixsec @heading
189 @subsection @unnumberedsubsec @appendixsubsec @subheading
190 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
193 As a notable exception, the second argument 'Bar baz' of
194 @ref{Foo,'Bar baz',,info-file} should be translated.
196 @uref's names are to be translated.
198 In any section which looks like
206 the node names (nodeN) are NOT to be translated, whereas extra title
207 information (thingN) is.
209 Every node name or section title must from now on be translated
210 separately in a .po file (just as well as LilyPond output messages).
211 This .po file should be in Documentation/po.
214 Take care of using typographic rules for your language, especially in
218 Please keep verbatim copies of music snippets (in @lilypond blocs).
219 However, some music snippets containing text that shows in the
220 rendered music, and sometimes translating this text really helps the
221 user to understand the documentation; in this case, and only in this
222 case, you may as an exception translate text in the music snippet, and
223 then you must add a line immediately before the @lilypond block,
228 Otherwise the music snippet would be reset to the same contents as the
229 English version at next 'make snippet-update' run (see UPDATING A
234 @lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}
236 in the source, open input/lsr/FILENAME.ly, translate the `texidoc'
237 header field it contains, enclose it with 'texidoc<MY-LANGUAGE> = "'
238 and '"', and write it into input/texidocs/FILENAME.texidoc -- please
239 keep possibly existing translations in other languages!
240 Additionnally, you may translate the snippet's title in `doctitle'
241 header field, in case `doctitle' is a fragment option used in
242 @lilypondfile; you can do this exactly the same way as `texidoc'. For
243 instance, input/texidocs/FILENAME.texidoc may contain
245 doctitlees = "Spanish title baz"
247 Spanish translation blah
249 doctitlede = "German title bar"
250 texidocde = "German translation foo
254 @example blocs need not be verbatim copies, e.g. variable names,
255 file names and comments should be translated.
257 Index entries (@cindex and so on) should be translated.
259 Carefully apply every rule exposed in Documentation/README.txt. If
260 one of these rules conflicts with a rule specific to your language,
261 please ask the Translation meister and/or the Documentation Editor on
262 lilypond-devel@gnu.org.
265 * REFERENCE NOTATION AND PROGRAM USAGE MANUAL
267 Copy user/lilypond.tely (or user/lilypond-program.tely, respectively)
268 into <MY-LANGUAGE>/user, then translate this file and run
269 skeleton-update (see UPDATE A TRANSLATION below). Your are now ready
270 to translate notation reference (program usage manual, respectively)
271 exactly like the learning manual.
274 * DOCUMENTATION INDEX index.html.in
276 Unlike almost all HTML pages in this documentation, links in this page
277 are not tweaked by add_html_footer.py, so links should be manually
278 edited to link to existing translations.
281 CHECK STATE OF TRANSLATION
283 First pull, then cd into Documentation (or at top of the source tree,
284 replace 'make' with 'make -C Documentation') and run
286 make ISOLANG=<MY_LANGUAGE> check-translation
288 This presents a diff of the original files since the most recent
289 revision of the translation. To check a single file, cd into
290 Documentation and run
292 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely check-translation
295 Small tip: to see only which files need to be updated, do
297 make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
300 Global state of the translation is recorded in
301 Documentation/translations.html.in, which is used to generate
302 Translations status page. To update that page, do from Documentation/
304 make translation-status
306 This will also leave out/translations-status.txt, which contains
307 up-to-dateness percentages for each translated file, and update word
308 counts of documentation files in this file.
313 Instead of running check-translation, you can run update-translation,
314 which will run your favorite text editor to update files. First, make
315 sure environment variable EDITOR is set to a text editor command, then
316 run from Documentation
318 make ISOLANG=<MY-LANGUAGE> update-translation
320 or to update a single file
322 make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely update-translation
324 For each file to be udpated, update-translation will open your text
325 editor with this file and a diff of the file in English; if the diff
326 cannot be generated or is bigger than the file in English itself, the
327 full file in English will be opened instead.
329 Texinfo skeleton files, i.e. .itely files not yet translated,
330 containing only the Texinfo structure can be updated automatically:
331 whenever 'make check-translation' shows that such files should be
332 updated, run from Documentation
334 make ISOLANG=<MY_LANGUAGE> skeleton-update
336 .po message catalogs in Documentation/po may be updated with (from
337 Documentation or Documentation/po)
341 WARNING: if you run po-update and somebody else does the same and
342 pushes before you push or send a patch to be applied, there will be a
343 conflict when you pull. Therefore, it is better that only the
344 Translation meister runs this command.
346 Updating music snippets can quickly become cumbersome, as most
347 snippets should be identical in all languages. Fortunately, there is
348 a script than can do this odd job for you (run from Documentation):
350 make ISOLANG=<MY_LANGUAGE> snippet-update
352 This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
353 with music snippets from user/every.itely. It ignores skeleton files,
354 and keeps intact music snippets preceded with a line starting with '@c
355 KEEP LY'; it reports an error for each .itely that has not the same
356 music snippet count in both languages.
358 Finally, a command runs the three update processes above for all
359 enabled languages (from Documentation):
361 make all-translations-update
363 Use this command with caution, and keep in mind it will not be really
364 useful until translations are stabilized after the end of GDP.
367 POLICY DURING GDP PROCESS
368 or "How to maintain translations without updating them"
370 During GDP progress, documentation changes so much, and translators are
371 often involved in GDP too, so keeping translations up to date is very
372 difficult. However, it is possible -- and even recommended -- to
373 perform some maintaining that keeps translated documentation usable
374 and eases future translation updating. The rationale below the tasks
375 list motivates this plan.
377 The following tasks are listed in decreasing priority order.
379 1) Update macros.itexi. For each obsolete macro definition, if it is
380 possible to update macro usage in documentation with an automatic text
381 or regexp substitution, do it and delete the macro definition from
382 macros.itexi; otherwise, mark this macro definition as obsolete with a
383 comment, and keep it in macros.itexi until the documentation
384 translation has been updated and no longer uses this macro.
386 2) Update *.tely files completely with make check-translation -- you
387 may want to redirect ouptput to a file because of overwhelming output,
388 or call check-translation.py on individual files, see CHECK STATE OF
391 3) in .itelys, match sections and .itely file names with those from
392 English docs, which possibly involves moving nodes contents in block
393 between files, without updating contents itself. In other words, the
394 game is catching where has gone each section. In Learning manual, and
395 in Notation Reference sections which have been revised in GDP, there
396 may be completely new sections: in this case, copy @node and
397 @section-command from English docs, and put the usual tricky line
398 'UNTRANSLATED NODE: IGNORE ME'. Note that it is not possible to
399 exactly match subsections or subsubsections of documentation in
400 English, when contents has been deeply revised; in this case, kee
401 obsolete (sub)subsections in the translation.
403 * Hints for Emacs users (without Emacs AucTeX installed)
405 Emacs with Texinfo mode makes this step easier:
407 - C-c C-s shows structure of current Texinfo file in a new buffer
408 *Occur*; to show structure of two files simultaneously, first split
409 Emacs window in 4 tiles (with C-x 1 and C-x 2), press C-c C-s to
410 show structure of one file (e.g. the translated file), copy *Occur*
411 contents into *Scratch*, then press C-c C-s for the other file.
413 - Do not bother updating @menus when all menu entries are in the same
414 file ; make sure there is at least a (possibly empty) @menu block
415 everywhere it is needed, then do C-c C-u C-a ("update all menus") when
416 you have updated all the rest of the file.
418 - Moving to next or previous node: press C-s and type node (or C-s
419 @node if the text contains the word 'node') then press C-s to move to
420 next node or C-r to move to previous node. Similar operation can be
421 used to move to the next/previous section.
423 - Moving a whole node (or even a sequence of nodes): jump to beginning
424 of the node (quit incremental search by pressing an arrow), press
425 C-SPACE, press C-s node and repeat C-s until you have selected enough
426 text, cut it with C-w or C-x, jump to the right place (moving between
427 nodes with the previous hint is often useful) and paste with C-y or
431 4) update documentation PO. Unless you have special interest in
432 having all titles translated in the next development release, it is
433 better to wait until step 3) has been completed, to avoid doing the
436 5) Fix broken cross-references by running (from Documentation/)
438 make ISOLANG=<YOUR-LANGUAGE> fix-xrefs
440 This step requires a sucessful documentation build (with 'make web').
441 Some cross-references are broken because they point to a node that
442 exists in the documentation in English, which has not been added to
443 the translation; in this case, do not fix the cross-reference but keep
444 it "broken", so that the resulting HTML link will point to an existing
445 page of documentation in English.
449 You may wonder if it would not be better to leave translations as-is
450 until you can really start updating translations. There are several
451 reasons to do these maintenance tasks right now.
453 - This will have to be done sooner or later anyway, before updating
454 translation of documentation contents, and this can already be done
455 without needing to be redone later, as sections of documentation in
456 English are mostly revised once. However, note that not all
457 documentation sectioning has been revised in one go, so all this
458 maintenance plan has to be repeated whenever a big reorganization is
459 made. Currently (in May 2008), only chapters 3-7 in Notation Reference
460 and Application Usage have not be reorganized yet.
462 - This just makes translated documentation take advantage of the new
463 organization, which is far better than the old one.
465 - Moving and renaming sections to match sectioning of documentation in
466 English simplify future updating work: it allows updating the
467 translation by side-by-side comparison, without bothering whether
468 cross-reference names already exist in the translation.
470 - Each maintenance task (except 4) updating PO files) can be done by
471 the same person for all languages, which saves overall time spent by
472 translators to achieve this task: the node names and section titles
473 are in English, so you can do. It is important to take advantage of
474 this now, as it will be more complicated (but still possible) to do
475 step 3) in all languages when documentation is compiled with
476 texi2html and node names are directly translated in source files.
479 MANAGING TRANSLATIONS ON GIT
481 This policy explains how to manage Git branches and commit
484 * Translation changes matching master branch are preferably made on
485 lilypond/translation branch; they may be pushed directly on master
486 only if they do not break compilation of LilyPond and its
487 documentation, and in this case they should be pushed to
488 lilypond/translation too. Similarly, changes matching stable/X.Y are
489 preferably made on lilypond/X.Ytranslation.
491 * lilypond/translation Git branch may be merged into master only if
492 LilyPond ('make all') and documentation ('make web') compile
495 * master Git branch may be merged into lilypond/translation whenever
496 'make' and 'make web' are succesful (in order to ease documentation
497 compilation by translators), or when significant changes had been made
498 in documentation in English in master branch.
500 * General maintenance may be done by anybody who knows what he does
501 in documentation in all languages, without informing translators
502 first. General maintenance include simple text substitutions
503 (e.g. automated by sed), compilation fixes, updating Texinfo or
504 lilypond-book commands, updating macros, updating ly code, fixing
505 cross-references, and operations described in 'POLICY DURING GDP
509 DEALING WITH SEVERAL GIT BRANCHES
511 * It is possible to work with several branches on the same local Git
512 repository; this is especially useful for translators who may have to
513 deal with both lilypond/translation and a stable branch
514 (e.g. stable/2.12 or lilypond/translation-2.12). To fetch and check
515 out a new branch named BRANCH on git.sv.gnu.org, write the two
516 following lines to a text file named .git/remotes/SHORTHAND --
517 SHORTHAND is the name of the remote file, i.e. whatever easy-to-type
518 name you would like to use when pulling or pushing BRANCH, and usually
519 SHORTHAND is an abbreviation of BRANCH without slashes
521 URL: git://git.sv.gnu.org/lilypond.git/
522 Pull: BRANCH:refs/remotes/origin/BRANCH
527 git checkout -b BRANCH origin/BRANCH
529 After this, you are able to pull BRANCH from git.sv.gnu.org with
533 You can check out another branch OTHER_BRANCH, i.e. check out
534 OTHER_BRANCH to the working tree, with
536 git checkout OTHER_BRANCH
538 E.g. lilypond/translation, which you still have in your local Git
539 repository but is no longer checked out since you have created the new
542 Note that it is possible to check out another branch while having
543 uncommitted changes, but it is not recommended unless you know what
544 you are doing; it is recommended to run 'git status' to check this
545 kind of issue before checking ouy another branch.
547 When pulling using SHORTHAND, do not forget to check first that the
548 right branch is checked out, i.e. the branch named A in the first part
549 of the "A:B" refspec in .git/remotes/SHORTHAND: as a matter of fact,
550 when you pull using A:B refspec, Git fetch A on the server as B remote
551 branch on your local repository, then tries to merge B into the
552 currently checked out branch.
554 To remember which branch is currently checked out, run 'git branch',
555 which will list all branches and mark the currently checked out branch
556 with a star, or 'git status'.
559 * To merge branch FOO into branch BAR, i.e. to "add" all changes made
560 in branch FOO to branch BAR, run
565 If any conflict happens, please carefully follow the instructions
566 given by 'git merge' -- you usually must resolve conflicts with a text
567 editor by merging pieces of files marked with "<<<" "===" and ">>>",
568 removing these 3 kinds of conflict marks, then commit the result
569 exactly like a usual commit.
571 For example, as a translator, you will often want to merge master into
572 lilypond/translation; on the other hand, the Translations meister
573 wants to merge lilypond/translation into master whenever he has
574 checked that lilypond/translation builds successfully.
577 * If you play with several Git branches (e.g. master,
578 lilypond/translation, stable/2.12), you may want to have one source
579 and build tree for each branch; this is possible with subdirectories
580 of your local Git repository, used as local cloned subrepositories.
581 To create a local clone for the branch named BRANCH, run
584 git clone -l -s -n . SUBDIR
588 Note that SUBDIR must be a directory name which does not already
589 exist. In SUBDIR, you can use all Git commands to browse revisions
590 history, commit and uncommit changes; to update the cloned
591 subrepository with changes made on the main repository, cd into SUBDIR
592 and run 'git pull'; to send changes made on the subrepository back to
593 the main repository, run 'git push' from SUBDIR. Note that only one
594 branch (the currently checked out branch) is created in the
595 subrepository by default; it is possible to have several branches in a
596 subrepository and do usual operations (checkout, merge, create,
597 delete...) on these branches, but this possibility is not detailed
603 A number of Python scripts handle a part of the documentation
604 translation process. All are located in buildscripts/, except
605 langdefs.py which is in python/
607 * buildlib.py -- module containing common functions (read piped output
608 of a shell command, use Git)
609 * langdefs.py -- language definitions module
610 * check_translation.py -- show diff to update a translation
611 * texi-langutils.py -- quickly and dirtily parse Texinfo files to
612 make message catalogs and Texinfo skeleton files
613 * texi-skeleton-update.py -- update Texinfo skeleton files
614 * html-gettext.py -- translate node names, section titles and cross
615 references in HTML files generated by makeinfo
616 * add_html_footer.py (module imported by www_post.py) -- add footer and
617 tweak links in HTML pages
618 * texi-gettext.py -- gettext node names, section titles and references
619 before calling texi2pdf
620 * mass-link.py -- link or symlink files between English documentation
621 and documentation in other languages
622 * update-snippets.py -- synchronize ly snippets with those from
624 * translations-status.py -- update translations status pages and word
625 counts in the file you are reading.