[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Updating translation committishes ]		[  Up : Translating the documentation ]	[ Maintaining without updating translations > ]

5.9.4 Translations management policies

These policies show the general intent of how the translations should be managed, they aim at helping translators, developers and coordinators work efficiently.

Maintaining without updating translations
Managing documentation translation with Git

---

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Translations management policies ]		[  Up : Translations management policies ]	[ Managing documentation translation with Git > ]

Maintaining without updating translations

Keeping translations up to date under heavy changes in the documentation in English may be almost impossible, especially as during the former Grand Documentation Project (GDP) or the Grand Organization Project (GOP) when a lot of contributors brings changes. In addition, translators may be — and that is a very good thing — involved in these projects too.

it is possible — and even recommended — to perform some maintenance 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 output 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 add the marker for untranslated status @untranslated on a single line. 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, keep obsolete (sub)subsections in the translation, marking them with a line @c obsolete just before the node.

   Emacs with Texinfo mode makes this step easier:

   • without Emacs AucTeX installed, <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.

     If you happen to have installed AucTeX, you can either call the macro by doing <M-x texinfo-show-structure> or create a key binding in your ‘~/.emacs’, by adding the four following lines:

     (add-hook 'Texinfo-mode-hook
               '(lambda ()
                  (define-key Texinfo-mode-map "\C-cs"
                   'texinfo-show-structure)))
     

     and then obtain the structure in the *Occur* buffer with <C-c s>.

   • Do not bother updating @menus when all menu entries are in the same file, just do <C-c C-u C-a> (“update all menus”) when you have updated all the rest of the file.
   • Moving to next or previous node using incremental search: press <C-s> and type node (or <C-s @node> if the text contains the word ‘node’) then press <C-s> to move to next node or <C-r> to move to previous node. Similar operation can be used to move to the next/previous section. Note that every cursor move exits incremental search, and hitting <C-s> twice starts incremental search with the text entered in previous incremental search.
   • Moving a whole node (or even a sequence of nodes): jump to beginning of the node (quit incremental search by pressing an arrow), press <C-SPACE>, press <C-s node> and repeat <C-s> until you have selected enough text, cut it with <C-w> or <C-x>, jump to the right place (moving between nodes with the previous hint is often useful) and paste with <C-y> or <C-v>.
4. Update sections finished in the English documentation; check sections status at

   http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination.

5. Update documentation PO. It is recommended not to update strings which come from documentation that is currently deeply revised in English, to avoid doing the work more than once.
6. Fix broken cross-references by running (from ‘Documentation/’)

   make ISOLANG=YOUR-LANGUAGE fix-xrefs
   

   This step requires a successful documentation build (with make doc). 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.
• This just makes translated documentation take advantage of the new organization, which is 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 ‘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.

---

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Maintaining without updating translations ]		[  Up : Translations management policies ]	[ Technical background > ]

Managing documentation translation with Git

This policy explains how to manage Git branches and commit translations to Git.

• Translation work is made on translation branch. This branch is merged on staging once a week, approximately. Then, master branch is merged on translation, where the check-translation script (see Check state of translation) shows changes in English docs which should be translated, and the cycle starts again.
• Translations may be pushed directly to staging only if they do not break compilation of LilyPond and its documentation. Those changes could be pushed to translation too, or alternatively translators could wait until they come from master the next time it is merged on translation. Similarly, changes matching stable/X.Y are preferably made on X.Ytranslation.
• translation Git branch may be merged into staging branch only if LilyPond (make all) and documentation (make doc) compile successfully.
• make and make doc are usually successful in master Git branch because those tests should have already succeeded in staging branch before merging. master branch may be merged into translation 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 Maintaining without updating translations.

---

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Maintaining without updating translations ]		[  Up : Translations management policies ]	[ Technical background > ]

<< Back to Documentation Index

LilyPond — Contributor’s Guide v2.21.0 (development-branch).