LILYPOND DOCUMENTATION TRANSLATION SOURCES The sources live in a GIT repository. Git 1.5.x is required, and latest version available on your platform is always recommended. To get a fresh version of LilyPond sources run mkdir lily ; cd lily ; git init-db ; mkdir .git/refs/remotes/origin then write the two following lines to a text file named .git/remotes/trans URL: git://git.sv.gnu.org/lilypond.git/ Pull: lilypond/translation:refs/remotes/origin/lilypond/translation then run git fetch trans git checkout -b lilypond/translation origin/lilypond/translation GIT The reader is supposed to be familiar with Git, for example by having experience from lilypond.org translation; see http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=README;hb=web/master REQUIREMENTS Working on LilyPond documentation translations requires: * python * make * gettext WHICH DOCUMENTATION CAN BE TRANSLATED The makfiles and scripts infrastructure currently supports translation of the following documentation: * documentation index (HTML) * user manual and program usage -- Texinfo source, PDF and HTML output; Info output might be added if there is enough demand for it. STARTING A TRANSLATION IN A NEW LANGUAGE At top of the source directory, do ./autogen.sh or (if you want to install your self-compiled LilyPond locally): ./autogen.sh --prefix=$HOME If you want to compile LilyPond -- which is almost required to build the docs, but is not required to do translation only -- fix all dependencies and rerun ./configure (with the same options as for autogen). Cd into Documentation and run: make ISOLANG= new-lang where is the ISO 639 language code. Add a language definition for your language in buildscripts/langdefs.py. See next section about what files to translate and the following detailed instructions after the next section. FILES TO BE TRANSLATED All the following files are in Documentation/ Translation of Documentation/foo/bar should be Documentation//foo/bar. Unmentioned files should not be translated. Priorities: 1. delivery 2. 3. 4. 5. later 6. optional Files marked with priority 3, 4 or 5 may be submitted individually. Word counts (excluding lilypond snippets) are given for each file. -1- Documentation index and Tutorial 396 user/lilypond-learning.tely 5593 user/tutorial.itely 23 user/dedication.itely 216 index.html.in 2022 po/lilypond-doc.pot (translate to po/.po) 8250 total In addition, user/macros.itexi may be translated in case typographic rules used in this file are different in your language. -2- Introduction and beginning of Application Usage 411 user/preface.itely 3198 user/introduction.itely 374 user/lilypond-program.tely 1477 user/install.itely (partial translation) 947 user/setup.itely 2860 user/running.itely 9267 total -3- Learning manual 8626 user/fundamental.itely -- Fundamental concepts 12134 user/tweaks.itely -- Tweaking output 2985 user/working.itely -- Working on LilyPond files 483 user/templates.itely -- Templates 24228 total -4- Notation reference 539 user/lilypond.tely 91 user/notation.itely -- Musical notation 2808 user/pitches.itely 7336 user/rhythms.itely 1681 user/expressive.itely 725 user/repeats.itely 916 user/simultaneous.itely 1861 user/staff.itely 879 user/editorial.itely 2336 user/text.itely 54 user/specialist.itely -- Specialist notation 2630 user/vocal.itely 1275 user/chords.itely 702 user/piano.itely 481 user/percussion.itely 826 user/guitar.itely 66 user/strings.itely 242 user/bagpipes.itely 4289 user/ancient.itely 2458 user/input.itely -- Input syntax 2164 user/non-music.itely -- Non-musical notation 8399 user/spacing.itely -- Spacing issues 5149 user/changing-defaults.itely -- Changing defaults 4547 user/programming-interface.itely -- Interfaces for programmers 935 user/notation-appendices.itely -- Notation manual tables 250 user/cheatsheet.itely -- Cheat sheet 53639 total -5- Application usage 2917 user/lilypond-book.itely -- LilyPond-book 975 user/converters.itely -- Converting from other formats 3892 total -6- Appendices whose translation is optional 299 user/literature.itely 960 user/scheme-tutorial.itely (needs to be revised first) 1259 total TRANSLATION DETAILED INSTRUCTIONS Please follow all these instructions with care to ensure quality work. All files should be encoded in UTF-8. * LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION Any title which comes with one of the following commands must not be translated directly in the Texinfo source @node @majorheading @chapter @unnumbered @appendix @chapheading @section @unnumberedsec @appendixsec @heading @subsection @unnumberedsubsec @appendixsubsec @subheading @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading @ref @rglos As a notable exception, the second argument 'Bar baz' of @ref{Foo,'Bar baz',,info-file} should be translated. @uref's names are to be translated. In any section which looks like @menu * node1:: thing1 * node2:: thing2 ... @end menu the node names (nodeN) are NOT to be translated, whereas extra title information (thingN) is. Every node name or section title must from now on be translated separately in a .po file (just as well as LilyPond output messages). This .po file should be in Documentation/po. Please keep verbatim copies of music snippets (in @lilypond blocs). However, some music snippets containing text that shows in the rendered music, and sometimes translating this text really helps the user to understand the documentation; in this case, and only in this case, you may as an exception translate text in the music snippet, and then you must add a line immediately before the @lilypond block, beginning with @c KEEP LY Otherwise the music snippet would be reset to the same contents as the English version at next 'make snippet-update' run (see UPDATING A TRANSLATION below). When you encounter @lilypondfile[,texidoc]{FILENAME.ly} in the source, open input/lsr/FILENAME.ly, translate the texidoc string it contains, enclose it with 'texidoc = "' and '"', and write it into input/texidocs/FILENAME.texidoc -- please keep possibly existing translations in other languages! For instance, input/texidocs/FILENAME.texidoc may contain texidoces = " Spanish translation blah " texidocde = "German translation foo " @example blocs need not be verbatim copies, e.g. variable names, file names and comments should be translated. Index entries (@cindex and so on) should be translated. Carefully apply every rule exposed in Documentation/README.txt. If one of these rules conflicts with a rule specific to your language, please ask the Translation meister and/or the Documentation Editor on lilypond-devel@gnu.org. * REFERENCE NOTATION AND PROGRAM USAGE MANUAL Copy user/lilypond.tely (or user/lilypond-program.tely, respectively) into /user, then translate this file and run skeleton-update (see UPDATE A TRANSLATION below). Your are now ready to translate notation reference (program usage manual, respectively) exactly like the learning manual. * DOCUMENTATION INDEX index.html.in Unlike almost all HTML pages in this documentation, links in this page are not tweaked by add_html_footer.py, so links should be manually edited to link to existing translations. CHECK STATE OF TRANSLATION First pull, then cd into Documentation (or at top of the source tree, replace 'make' with 'make -C Documentation') and run make ISOLANG= check-translation This presents a diff of the original files since the most recent revision of the translation. To check a single file, cd into Documentation and run make CHECKED_FILES=/user/foo.itely check-translation Small tip: to see only which files need to be updated, do make ISOLANG= check-translation | grep 'diff --git' Global state of the translation is recorded in Documentation/translations.html.in, which is used to generate Translations status page. To update that page, do from Documentation/ make translation-status This will also leave out/translations-status.txt, which contains up-to-dateness percentages for each translated file. UPDATE A TRANSLATION Instead of running check-translation, you can run update-translation, which will run your favorite text editor to update files. First, make sure environment variable EDITOR is set to a text editor command, then run from Documentation make ISOLANG= update-translation or to update a single file make CHECKED_FILES=/user/foo.itely update-translation For each file to be udpated, update-translation will open your text editor with this file and a diff of the file in English; if the diff cannot be generated or is bigger than the file in English itself, the full file in English will be opened instead. Texinfo skeleton files, i.e. .itely files not yet translated, containing only the Texinfo structure can be updated automatically: whenever 'make check-translation' shows that such files should be updated, run from Documentation make ISOLANG= skeleton-update .po message catalogs in Documentation/po may be updated with (from Documentation or Documentation/po) make po-update WARNING: if you run po-update and somebody else does the same and pushes before you push or send a patch to be applied, there will be a conflict when you pull. Therefore, it is better that only the Translation meister runs this command. Updating music snippets can quickly become cumbersome, as most snippets should be identical in all languages. Fortunately, there is a script than can do this odd job for you (run from Documentation): make ISOLANG= snippet-update This script overwrites music snippets in /user/every.itely with music snippets from user/every.itely. It ignores skeleton files, and keeps intact music snippets preceded with a line starting with '@c KEEP LY'; it reports an error for each .itely that has not the same music snippet count in both languages. Finally, a command runs the three update processes above for all enabled languages (from Documentation): make all-translations-update This command is mainly intended to be used by the Translation meister. MISCELLANEOUS: DEALING WITH SEVERAL GIT BRANCHES * It is possible to work with several branches on the same local Git repository; this is especially useful for translators who may have to deal with both lilypond/translation and a stable branch (e.g. stable/2.12 or lilypond/translation-2.12). To fetch and check out a new branch named BRANCH on git.sv.gnu.org, write the two following lines to a text file named .git/remotes/SHORTHAND -- SHORTHAND is the name of the remote file, i.e. whatever easy-to-type name you would like to use when pulling or pushing BRANCH, and usually SHORTHAND is an abbreviation of BRANCH without slashes URL: git://git.sv.gnu.org/lilypond.git/ Pull: BRANCH:refs/remotes/origin/BRANCH Then, run git fetch SHORTHAND git checkout -b BRANCH origin/BRANCH After this, you are able to pull BRANCH from git.sv.gnu.org with git pull SHORTHAND You can check out another branch OTHER_BRANCH, i.e. check out OTHER_BRANCH to the working tree, with git checkout OTHER_BRANCH E.g. lilypond/translation, which you still have in your local Git repository but is no longer checked out since you have created the new branch BRANCH. Note that it is possible to check out another branch while having uncommitted changes, but it is not recommended unless you know what you are doing; it is recommended to run 'git status' to check this kind of issue before checking ouy another branch. When pulling using SHORTHAND, do not forget to check first that the right branch is checked out, i.e. the branch named A in the first part of the "A:B" refspec in .git/remotes/SHORTHAND: as a matter of fact, when you pull using A:B refspec, Git fetch A on the server as B remote branch on your local repository, then tries to merge B into the currently checked out branch. To remember which branch is currently checked out, run 'git branch', which will list all branches and mark the currently checked out branch with a star, or 'git status'. * To merge branch FOO into branch BAR, i.e. to "add" all changes made in branch FOO to branch BAR, run git checkout BAR git merge FOO If any conflict happens, please carefully follow the instructions given by 'git merge' -- you usually must resolve conflicts with a text editor by merging pieces of files marked with "<<<" "===" and ">>>", removing these 3 kinds of conflict marks, then commit the result exactly like a usual commit. For example, as a translator, you will often want to merge master into lilypond/translation; on the other hand, the Translations meister wants to merge lilypond/translation into master whenever he has checked that lilypond/translation builds successfully. * If you play with several Git branches (e.g. master, lilypond/translation, stable/2.12), you may want to have one source and build tree for each branch; this is possible with subdirectories of your local Git repository, used as local cloned subrepositories. To create a local clone for the branch named BRANCH, run git checkout BRANCH git clone -l -s -n . SUBDIR cd SUBDIR git reset --hard Note that SUBDIR must be a directory name which does not already exist. In SUBDIR, you can use all Git commands to browse revisions history, commit and uncommit changes; to update the cloned subrepository with changes made on the main repository, cd into SUBDIR and run 'git pull'; to send changes made on the subrepository back to the main repository, run 'git push' from SUBDIR. Note that only one branch (the currently checked out branch) is created in the subrepository by deafult; it is possible to have several branches in a subrepository and do usual operations (checkout, merge, create, delete...) on these branches, but this is more difficult to manage them and sync them with the main repository, so this possibility is not detailed here. TECHNICAL BACKGROUND A number of Python scripts handle a part of the documentation translation process: * langdefs.py -- language definitions * check_translation.py -- show diff to update a translation * texi-langutils.py -- quickly and dirtily parse Texinfo files to make message catalogs and Texinfo skeleton files * texi-skeleton-update.py -- update Texinfo skeleton files * html-gettext.py -- translate node names, section titles and cross references in HTML files generated by makeinfo * add_html_footer.py (module called by www_post.py) -- add footer and tweak links in HTML pages * texi-gettext.py -- gettext node names, section titles and references before calling texi2pdf * mass-link.py -- link or symlink files between English documentation and documentation in other languages * update-snippets.py -- synchronize ly snippets with those from English docs * translations-status.py -- update translations status pages and word counts in the file you are reading