From: John Mandereau Date: Sat, 24 May 2008 07:48:38 +0000 (+0200) Subject: Update TRANSLATION X-Git-Tag: release/2.11.47-1~5^2~13 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=21909c38e32367b9fc06161a69cd7bb0ca251d64;p=lilypond.git Update TRANSLATION * add policy for using Git branches, * add temporary maintenance policy (valid throughout GDP process), * fix some typos and nitpicks, * also update langdefs.py path in Documentation/GNUmakefile. --- diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 7d30c8533f..15b6a6f297 100644 --- a/Documentation/GNUmakefile +++ b/Documentation/GNUmakefile @@ -47,7 +47,7 @@ new-lang: mv $(outdir)/*.*tely $(ISOLANG)/user msgmerge -U po/lilypond-doc.pot $(outdir)/doc.pot cp po/lilypond-doc.pot po/$(ISOLANG).po - @echo "*** Please add a language definition for $(ISOLANG) in buildscripts/langdefs.py ***" + @echo "*** Please add a language definition for $(ISOLANG) in python/langdefs.py ***" CHECKED_FILES = $(ISOLANG)/index.html.in $(shell find $(ISOLANG)/user/ -maxdepth 1 -name '*.*te??') diff --git a/Documentation/TRANSLATION b/Documentation/TRANSLATION index c78cb8a8a9..e0929cf1e2 100644 --- a/Documentation/TRANSLATION +++ b/Documentation/TRANSLATION @@ -1,5 +1,23 @@ 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 @@ -93,13 +111,11 @@ Word counts (excluding lilypond snippets) are given for each file. 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/.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 @@ -195,6 +211,10 @@ separately in a .po file (just as well as LilyPond output messages). 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 @@ -213,15 +233,20 @@ 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 +in the source, open input/lsr/FILENAME.ly, translate the `texidoc' +header field it contains, enclose it with 'texidoc = "' +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 " @@ -279,7 +304,8 @@ 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. +up-to-dateness percentages for each translated file, and update word +counts of documentation files in this file. UPDATE A TRANSLATION @@ -334,10 +360,141 @@ enabled languages (from Documentation): 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= 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 @@ -423,26 +580,28 @@ 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 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 @@ -451,4 +610,4 @@ 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 +counts in the file you are reading.