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
* 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
make ISOLANG=<MY-LANGUAGE> new-lang
-where <MY-LANGUAGE> is the ISO 639 language code
+where <MY-LANGUAGE> 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/
1 user/dedication.itely
1 user/cheatsheet.itely
1 index.html.in
+ po/<MY-LANGUAGE>.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
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
* 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
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.
lilypond-devel@gnu.org.
+* PROGRAM USAGE MANUAL
+
+Copy user/lilypond-program.tely into <MY-LANGUAGE>/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=<MY_LANGUAGE> 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/<MY-LANGUAGE>/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=<MY_LANGUAGE> 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=<MY_LANGUAGE> snippet-update
+
+This script overwrites music snippets in <MY_LANGUAGE>/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
projects / lilypond.git / blobdiff