X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2FTRANSLATION;h=61b2e6d02d0cd796e682021639eaaa54c2eaa1c6;hb=e0ab7a37fa31290d42c9e5534ac5480c7d9f4a8f;hp=a34cd4b0ecc48e63c0779fb2eef7b6ac4a10fbb2;hpb=d6b4b8b0b781f6d004a5d969fd514cc58f63914f;p=lilypond.git diff --git a/Documentation/TRANSLATION b/Documentation/TRANSLATION index a34cd4b0ec..61b2e6d02d 100644 --- a/Documentation/TRANSLATION +++ b/Documentation/TRANSLATION @@ -5,7 +5,7 @@ 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 @@ -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 @@ -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/ @@ -75,6 +86,9 @@ Files marked with priority 3, 4 or 5 may be submitted individually. 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 @@ -95,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 @@ -160,7 +176,7 @@ All files should be encoded in UTF-8. 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 @@ -170,6 +186,8 @@ translated directly in the Texinfo source 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 @@ -181,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. @@ -198,6 +230,14 @@ 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 @@ -213,9 +253,9 @@ 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 page, run +revision of the translation. To check a single file, run - buildscripts/check-translation.py Documentation/user//foo/bar.itely + python buildscripts/check_translation.py buildscripts Documentation//user/foo.itely @@ -223,7 +263,7 @@ 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 shouldbe +whenever 'make check-translation' shows that such files should be updated, run from Documentation make ISOLANG= skeleton-update @@ -233,6 +273,29 @@ 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 @@ -240,12 +303,18 @@ 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 +* 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 +* 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 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