X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2FTRANSLATION;h=2cb3c94c5298ae640ce5ec7adbbafd08d1459319;hb=f41cda4ec41e017c27a6e1d7893a7ce6fb87b1a8;hp=cc999b6dd0de72c753cf5cd042c79c5003908c53;hpb=6140a9a56be5b96dcfa6d448d258488bd43cdedb;p=lilypond.git diff --git a/Documentation/TRANSLATION b/Documentation/TRANSLATION index cc999b6dd0..2cb3c94c52 100644 --- a/Documentation/TRANSLATION +++ b/Documentation/TRANSLATION @@ -1,16 +1,44 @@ LILYPOND DOCUMENTATION TRANSLATION +TABLE OF CONTENTS SOURCES +GIT +REQUIREMENTS +WHICH DOCUMENTATION CAN BE TRANSLATED +STARTING A TRANSLATION IN A NEW LANGUAGE +FILES TO BE TRANSLATED +TRANSLATION DETAILED INSTRUCTIONS +* LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION +* REFERENCE NOTATION AND PROGRAM USAGE MANUAL +* DOCUMENTATION INDEX index.html.in +CHECK STATE OF TRANSLATION +UPDATE A TRANSLATION +POLICY DURING GDP PROCESS +MANAGING TRANSLATIONS WITH GIT +SOME GIT TIPS +DEALING WITH SEVERAL GIT BRANCHES +GIT PUSH ACCESS +TECHNICAL BACKGROUND + -The sources live in a GIT repository. Git 1.4.4.1 or newer is -required, and Git 1.5.x is highly recommended. To get a fresh version -of LilyPond sources run +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/remotes + +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 - mkdir lily ; cd lily - git init-db - git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/lilypond/translation:lilypond/translation - git checkout -b mytranslations lilypond/translation + git fetch trans + git checkout -b lilypond/translation origin/lilypond/translation GIT @@ -74,95 +102,77 @@ 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. +Priorities: + 1. delivery + 2. 3. 4. 5. later + 6. optional Files marked with priority 3, 4 or 5 may be submitted individually. - --1- Documentation index, Tutorial and Cheat Sheet -1 user/lilypond.tely -1 user/tutorial.itely -1 user/dedication.itely -1 user/cheatsheet.itely -1 index.html.in - po/.po - -In addition, user/macros.itexi may be translated in case typographic -rules used in this file are different in your language. - --2- User manual introduction -2 user/preface.itely -2 user/introduction.itely +Word counts (excluding lilypond snippets) are given for each file. + +-1- Documentation index and Tutorial +412 user/lilypond-learning.tely +6362 user/tutorial.itely +23 user/dedication.itely +409 user/macros.itexi +224 index.html.in +3473 po/lilypond-doc.pot (translate to po/.po) +10903 total + +-2- Introduction and beginning of Application Usage +411 user/preface.itely +3855 user/introduction.itely +390 user/lilypond-program.tely +1846 user/install.itely (partial translation) +1057 user/setup.itely +2877 user/running.itely +10436 total -3- Learning manual -3 user/putting.itely -- Putting it all together -3 user/working.itely -- Working on LilyPond files -3 user/tweaks.itely -- Tweaking output +10254 user/fundamental.itely -- Fundamental concepts +12328 user/tweaks.itely -- Tweaking output +3005 user/working.itely -- Working on LilyPond files +483 user/templates.itely -- Templates +26070 total -4- Notation reference -4 user/basic-notation.itely -- Basic notation -4 user/instrument-notation.itely -- Instrument-specific notation -4 user/advanced-notation.itely -- Advanced notation -4 user/changing-defaults.itely -- Changing defaults -4 user/non-music.itely -- Non-musical notation -4 user/spacing.itely -- Spacing issues -4 user/programming-interface.itely -- Interfaces for programmers -4 user/scheme-tutorial.itely -- Scheme tutorial - --5- Program usage -5 user/lilypond-program.tely -5 user/install.itely -- How to install or compile -5 user/running.itely -- Running LilyPond -5 user/lilypond-book.itely -- LilyPond-book -5 user/converters.itely -- Converting from other formats +674 user/lilypond.tely +91 user/notation.itely -- Musical notation +3084 user/pitches.itely +6714 user/rhythms.itely +1119 user/expressive.itely +556 user/repeats.itely +1276 user/simultaneous.itely +1536 user/staff.itely +902 user/editorial.itely +2303 user/text.itely +73 user/specialist.itely -- Specialist notation +2795 user/vocal.itely +1326 user/chords.itely +702 user/piano.itely +806 user/percussion.itely +826 user/guitar.itely +66 user/strings.itely +242 user/bagpipes.itely +3474 user/ancient.itely +5603 user/input.itely -- Input syntax +2164 user/non-music.itely -- Non-musical notation +7949 user/spacing.itely -- Spacing issues +10605 user/changing-defaults.itely -- Changing defaults +5218 user/programming-interface.itely -- Interfaces for programmers +1155 user/notation-appendices.itely -- Notation manual tables +250 user/cheatsheet.itely -- Cheat sheet +61509 total + +-5- Application usage +3175 user/lilypond-book.itely -- LilyPond-book +1147 user/converters.itely -- Converting from other formats +4322 total -6- Appendices whose translation is optional -6 user/literature.itely -6 user/templates.itely -6 user/notation-appendices.itely - -* WORD COUNTS FOR CATEGORIES - -LANG=C wc --words $(grep ^1 TRANSLATION | cut -d ' ' -f 2) - 777 user/lilypond.tely - 6322 user/tutorial.itely - 63 user/dedication.itely - 632 user/cheatsheet.itely - 361 index.html.in - 8155 total - -LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2) - 451 user/preface.itely - 4170 user/introduction.itely - 4621 total - -LANG=C wc --words $(grep ^3 TRANSLATION | cut -d ' ' -f 2) - 2230 user/putting.itely - 3232 user/working.itely - 2327 user/tweaks.itely - 7789 total - -LANG=C wc --words $(grep ^4 TRANSLATION | cut -d ' ' -f 2) - 12391 user/basic-notation.itely - 15779 user/instrument-notation.itely - 9530 user/advanced-notation.itely - 7386 user/changing-defaults.itely - 3884 user/non-music.itely - 8318 user/spacing.itely - 4781 user/programming-interface.itely - 915 user/scheme-tutorial.itely - 62984 total - -LANG=C wc --words $(grep ^5 TRANSLATION | cut -d ' ' -f 2) - 3566 user/running.itely - 3549 user/lilypond-book.itely - 1062 user/converters.itely - 8177 total - -LANG=C wc --words $(grep ^6 TRANSLATION | cut -d ' ' -f 2) - 339 user/literature.itely - 4648 user/templates.itely - 836 user/notation-appendices.itely - 5823 total +310 user/literature.itely +960 user/scheme-tutorial.itely (needs to be revised first) +1270 total TRANSLATION DETAILED INSTRUCTIONS @@ -171,7 +181,7 @@ Please follow all these instructions with care to ensure quality work. All files should be encoded in UTF-8. -* USER MANUAL +* 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 @@ -204,6 +214,10 @@ separately in a .po file (just as well as LilyPond output messages). This .po file should be in Documentation/po. +Take care of using typographic rules for your language, especially in +user/macros.itexi. + + 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 @@ -214,10 +228,31 @@ beginning with @c KEEP LY -Otherwise the music snippet would be reset to the same contents as the +Otherwise the music snippet would be reset to the same content 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' +header field it contains, enclose it with 'texidoc = "' +and '"', and write it into input/texidocs/FILENAME.texidoc -- please +keep possibly existing translations in other languages! +Additionnally, you may translate the snippet's title in `doctitle' +header field, in case `doctitle' is a fragment option used in +@lilypondfile; you can do this exactly the same way as `texidoc'. For +instance, input/texidocs/FILENAME.texidoc may contain + +doctitlees = "Spanish title baz" +texidoces = " +Spanish translation blah +" +doctitlede = "German title bar" +texidocde = "German translation foo +" + @example blocs need not be verbatim copies, e.g. variable names, file names and comments should be translated. @@ -230,12 +265,13 @@ please ask the Translation meister and/or the Documentation Editor on lilypond-devel@gnu.org. -* PROGRAM USAGE MANUAL +* REFERENCE NOTATION AND PROGRAM USAGE MANUAL -Copy user/lilypond-program.tely into /user, then -translate this file and run skeleton-update (see UPDATE A TRANSLATION -below). Your are now ready to translate program usage manual exactly -like the user 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 @@ -253,14 +289,46 @@ 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, run +revision of the translation. To check a single file, cd into +Documentation and run + + make CHECKED_FILES=/user/foo.itely check-translation + - python buildscripts/check_translation.py Documentation//user/foo.itely +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, and update word +counts of documentation files in this 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 @@ -280,7 +348,7 @@ 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): +a script that can do this odd job for you (run from Documentation): make ISOLANG= snippet-update @@ -295,22 +363,312 @@ enabled languages (from Documentation): make all-translations-update -This command is mainly intended to be used by the Translation meister. +Use this command with caution, and keep in mind it will not be really +useful until translations are stabilized after the end of GDP. + + +POLICY DURING GDP PROCESS +or "How to maintain translations without updating them" + +During GDP progress, documentation changes so much, and translators are +often involved in GDP too, so keeping translations up to date is very +difficult. However, it is possible -- and even recommended -- to +perform some maintaining that keeps translated documentation usable +and eases future translation updating. The rationale below the tasks +list motivates this plan. + +The following tasks are listed in decreasing priority order. + +1) Update macros.itexi. For each obsolete macro definition, if it is +possible to update macro usage in documentation with an automatic text +or regexp substitution, do it and delete the macro definition from +macros.itexi; otherwise, mark this macro definition as obsolete with a +comment, and keep it in macros.itexi until the documentation +translation has been updated and no longer uses this macro. + +2) Update *.tely files completely with make check-translation -- you +may want to redirect ouptput to a file because of overwhelming output, +or call check-translation.py on individual files, see CHECK STATE OF +TRANSLATION. + +3) in .itelys, match sections and .itely file names with those from +English docs, which possibly involves moving nodes contents in block +between files, without updating contents itself. In other words, the +game is catching where has gone each section. In Learning manual, and +in Notation Reference sections which have been revised in GDP, there +may be completely new sections: in this case, copy @node and +@section-command from English docs, and add the marker for +untranslated status '@untranslated' on a single line. Note that it is +not possible to exactly match subsections or subsubsections of +documentation in English, when contents has been deeply revised; in +this case, keep obsolete (sub)subsections in the translation, marking +them with a line '@c obsolete' just before the node. + +4) update sections finished in GDP; check sections status at GDP website. + + +* Hints for Emacs users + +Emacs with Texinfo mode makes this step easier: + +- without Emacs AucTeX installed, C-c C-s shows structure of current +Texinfo file in a new buffer *Occur*; to show structure of two files +simultaneously, first split Emacs window in 4 tiles (with C-x 1 and +C-x 2), press C-c C-s to show structure of one file (e.g. the translated +file), copy *Occur* contents into *Scratch*, then press C-c C-s for the +other file. +If you happen to have installed AucTeX, you can either call the macro +by doing M-x texinfo-show-structure or create a key binding in your +~/.emacs, by adding the four following lines: + (add-hook 'Texinfo-mode-hook + '(lambda () + (define-key Texinfo-mode-map "\C-cs" + 'texinfo-show-structure))) +and then obtain the structure in the *Occur* buffer with C-c s + + +- Do not bother updating @menus when all menu entries are in the same +file ; make sure there is at least a (possibly empty) @menu block +everywhere it is needed, then do C-c C-u C-a ("update all menus") when +you have updated all the rest of the file. + +- Moving to next or previous node: press C-s and type node (or C-s +@node if the text contains the word 'node') then press C-s to move to +next node or C-r to move to previous node. Similar operation can be +used to move to the next/previous section. + +- Moving a whole node (or even a sequence of nodes): jump to beginning +of the node (quit incremental search by pressing an arrow), press +C-SPACE, press C-s node and repeat C-s until you have selected enough +text, cut it with C-w or C-x, jump to the right place (moving between +nodes with the previous hint is often useful) and paste with C-y or +C-v. + + +4) update documentation PO. Unless you have special interest in +having all titles translated in the next development release, it is +better to wait until step 3) has been completed, to avoid doing the +work more than once. + +5) Fix broken cross-references by running (from Documentation/) + + make ISOLANG= fix-xrefs + +This step requires a sucessful documentation build (with 'make web'). +Some cross-references are broken because they point to a node that +exists in the documentation in English, which has not been added to +the translation; in this case, do not fix the cross-reference but keep +it "broken", so that the resulting HTML link will point to an existing +page of documentation in English. + +Rationale + +You may wonder if it would not be better to leave translations as-is +until you can really start updating translations. There are several +reasons to do these maintenance tasks right now. + +- This will have to be done sooner or later anyway, before updating +translation of documentation contents, and this can already be done +without needing to be redone later, as sections of documentation in +English are mostly revised once. However, note that not all +documentation sectioning has been revised in one go, so all this +maintenance plan has to be repeated whenever a big reorganization is +made. Currently (in May 2008), only chapters 3-7 in Notation Reference +and Application Usage have not been reorganized yet. + +- This just makes translated documentation take advantage of the new +organization, which is far better than the old one. + +- Moving and renaming sections to match sectioning of documentation in +English simplify future updating work: it allows updating the +translation by side-by-side comparison, without bothering whether +cross-reference names already exist in the translation. + +- Each maintenance task (except 4) updating PO files) can be done by +the same person for all languages, which saves overall time spent by +translators to achieve this task: the node names and section titles +are in English, so you can do. It is important to take advantage of +this now, as it will be more complicated (but still possible) to do +step 3) in all languages when documentation is compiled with +texi2html and node names are directly translated in source files. + + +MANAGING TRANSLATIONS WITH GIT + +This policy explains how to manage Git branches and commit +translations to Git. + +* Translation changes matching master branch are preferably made on +lilypond/translation branch; they may be pushed directly on master +only if they do not break compilation of LilyPond and its +documentation, and in this case they should be pushed to +lilypond/translation too. Similarly, changes matching stable/X.Y are +preferably made on lilypond/X.Ytranslation. + +* lilypond/translation Git branch may be merged into master only if +LilyPond ('make all') and documentation ('make web') compile +succesfully. + +* master Git branch may be merged into lilypond/translation whenever +'make' and 'make web' are succesful (in order to ease documentation +compilation by translators), or when significant changes had been made +in documentation in English in master branch. + +* General maintenance may be done by anybody who knows what he does +in documentation in all languages, without informing translators +first. General maintenance include simple text substitutions +(e.g. automated by sed), compilation fixes, updating Texinfo or +lilypond-book commands, updating macros, updating ly code, fixing +cross-references, and operations described in 'POLICY DURING GDP +PROCESS'. + + +SOME GIT TIPS + +* Saving uncommited changes in the working tree: + + git diff > foo.diff + +This does not save untracked or ignored files. If you prefer to +include changes added to the index with 'git add', replace 'git diff' +with 'git diff HEAD'. +Then, you may try to apply foo.diff on a source tree with + + patch -p1 < foo.diff + + +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 out 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 default; it is possible to have several branches in a +subrepository and do usual operations (checkout, merge, create, +delete...) on these branches, but this possibility is not detailed +here. + +Note that when you push BRANCH from SUBDIR to the main repository, +and BRANCH is checked out in the main repository, you must save +uncommitted changes (see SOME GIT TIPS) and do 'git reset --hard' in +the main repository in order to apply pushed changes in the working +tree of the main repository. + + +GIT PUSH ACCESS + +If you have permission to push to Git with login USER, please start a +new Git repository from scratch to avoid polluting history with +duplicate commits; follow the usual instructions, except that every +file you write in .git/remotes should contain instead + +URL: ssh://USER@git.sv.gnu.org/srv/git/lilypond.git +Push: BRANCH:refs/heads/BRANCH +Pull: BRANCH:refs/remotes/origin/BRANCH + +Then, you can use .git/remotes/NAME to push BRANCH with + + git push NAME + +which works regardless of the branch checked out. TECHNICAL BACKGROUND A number of Python scripts handle a part of the documentation -translation process: +translation process. All are located in buildscripts/, except +langdefs.py which is in python/ -* langdefs.py -- language definitions +* buildlib.py -- module containing common functions (read piped output +of a shell command, use Git) +* langdefs.py -- language definitions module * 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 +* add_html_footer.py (module imported 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 @@ -318,3 +676,5 @@ before calling texi2pdf 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.