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 ON GIT
+DEALING WITH SEVERAL GIT BRANCHES
+
SOURCES
396 user/lilypond-learning.tely
5593 user/tutorial.itely
23 user/dedication.itely
+100 user/macros.itexi
216 index.html.in
2022 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.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
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
@lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}
-in the source, open input/lsr/FILENAME.ly, translate the texidoc
-string it contains, enclose it with 'texidoc<MY-LANGUAGE> = "' 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
+in the source, open input/lsr/FILENAME.ly, translate the `texidoc'
+header field it contains, enclose it with 'texidoc<MY-LANGUAGE> = "'
+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
"
make translation-status
This will also leave out/translations-status.txt, which contains
-up-to-dateness percentages for each translated file.
+up-to-dateness percentages for each translated file, and update word
+counts of documentation files in this file.
UPDATE A TRANSLATION
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 put the usual tricky line
+'UNTRANSLATED NODE: IGNORE ME'. 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, kee
+obsolete (sub)subsections in the translation.
+
+* Hints for Emacs users (without Emacs AucTeX installed)
+
+Texinfo Emacs mode makes this step easier:
+
+- 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.
+
+- 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.
+
+
+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=<YOUR-LANGUAGE> 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 be 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 ON 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'.
+
-MISCELLANEOUS: DEALING WITH SEVERAL GIT BRANCHES
+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
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 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 is more difficult to manage
-them and sync them with the main repository, so this possibility is
-not detailed here.
+delete...) on these branches, but this possibility is not detailed
+here.
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
* 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
+counts in the file you are reading.
projects / lilypond.git / commitdiff