X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2FTRANSLATION;h=61b2e6d02d0cd796e682021639eaaa54c2eaa1c6;hb=9e7b53f94e1e3bd7b3f7a14ba11a6cae6c8e9a73;hp=fc770232dc3f1c4b1ee7eeb9ab8b018b91f5ee3d;hpb=fe99391d0473f537ca25822a8d3284e108af8c96;p=lilypond.git diff --git a/Documentation/TRANSLATION b/Documentation/TRANSLATION index fc770232dc..61b2e6d02d 100644 --- a/Documentation/TRANSLATION +++ b/Documentation/TRANSLATION @@ -5,12 +5,12 @@ 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 +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 + git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/lilypond/translation:lilypond/translation + git checkout -b mytranslations lilypond/translation GIT @@ -29,6 +29,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 +58,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 +66,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/ @@ -73,6 +84,10 @@ Files marked with priority 3, 4 or 5 may be submitted individually. 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 @@ -94,6 +109,8 @@ Files marked with priority 3, 4 or 5 may be submitted individually. 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 @@ -105,27 +122,71 @@ Files marked with priority 3, 4 or 5 may be submitted individually. * 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/@') +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 TRANSLATION DETAILED INSTRUCTIONS Please follow all these instructions with care to ensure quality work. +All files should be encoded in UTF-8. + * USER MANUAL 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 +199,27 @@ 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). + + +@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 +230,91 @@ please ask the Translation meister and/or the Documentation Editor on lilypond-devel@gnu.org. +* 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. + + * 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, run + + python buildscripts/check_translation.py buildscripts Documentation//user/foo.itely + UPDATE A TRANSLATION +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. 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