X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2FTRANSLATION;h=c78cb8a8a98c0014e95087e6e08b6e6828596342;hb=67ee4a04a1f1aacc046beb0befe32e83944425b7;hp=fc770232dc3f1c4b1ee7eeb9ab8b018b91f5ee3d;hpb=2b5cabd0f53c8fc3e553fee7b3aa5c3352e1106a;p=lilypond.git diff --git a/Documentation/TRANSLATION b/Documentation/TRANSLATION index fc770232dc..c78cb8a8a9 100644 --- a/Documentation/TRANSLATION +++ b/Documentation/TRANSLATION @@ -3,14 +3,21 @@ LILYPOND DOCUMENTATION TRANSLATION SOURCES -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 -run +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 - git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/master:remotemaster - git checkout -b master remotemaster + 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 + + git fetch trans + git checkout -b lilypond/translation origin/lilypond/translation GIT @@ -29,6 +36,16 @@ Working on LilyPond documentation translations requires: * 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 @@ -48,7 +65,7 @@ Cd into Documentation and run: make ISOLANG= new-lang -where is the ISO 639 language code +where is the ISO 639 language code. Add a language definition for your language in buildscripts/langdefs.py. @@ -56,6 +73,7 @@ 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/ @@ -63,69 +81,103 @@ 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 - --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 +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 -3 user/putting.itely -- Putting it all together -3 user/working.itely -- Working on LilyPond files -3 user/tweaks.itely -- Tweaking output +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 -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/running.itely -- Running LilyPond -5 user/lilypond-book.itely -- LilyPond-book -5 user/converters.itely -- Converting from other formats +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 -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 | sed 's@^@site/@') - -LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2 | sed 's@^@site/@') +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. -* USER MANUAL +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 @top @majorheading +@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 @@ -138,13 +190,43 @@ In any section which looks like 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. -Make sure to keep *verbatim* copies of music snippets (in @lilypond blocs). -@example blocs do not have to be verbatim copies, e.g. variable names, + +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. @@ -155,34 +237,218 @@ 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 -*** This section is a draft and should be overhauled *** -- J. Mandereau - -When starting a translation, texi-langutils.py quickly parses -lilypond.tely and the included .itely's, and generates a skeleton with -node and sectionning commands. When translating a .itely file, the -skeleton file is replaced with the real translation, in exception of -the the node, sectioning and glossary reference commands, which -remains in English. All this ensures easy navigation between nodes in -different languages in HTML docs, i.e.: there is automatic language -selection on lilypond.org, all sections and cross-references are -always available, at least in English (for example, see the "Other -languages: xxx" menu at bottom of tutorial pages). From the user's -point of view, docs in his native language with node and sections in -English are painful, so texi-langutils generates a .po of node and -section names; this .po file is used to translate the section titles -in the HTML generated docs. +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