[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Adding a Texinfo manual ] | [ Up : Translating the documentation ] | [ Check state of translation > ] |
5.9.3 Documentation translation maintenance
Several tools have been developed to make translations maintenance easier. These helper scripts make use of the power of Git, the version control system used for LilyPond development.
You should use them whenever you would like to update the translation in your language, which you may do at the frequency that fits your and your cotranslators’ respective available times. In the case your translation is up-do-date (which you can discover in the first subsection below), it is enough to check its state every one or two weeks. If you feel overwhelmed by the quantity of documentation to be updated, see Maintaining without updating translations.
Check state of translation | ||
Updating documentation translation | ||
Updating translation committishes |
Check state of translation
First pull from Git – see Pulling and rebasing, but DO NOT rebase
unless you are sure to master the translation state checking and
updating system – 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, cd into ‘Documentation/’ and run
make CHECKED_FILES=MY_LANGUAGE/manual/foo.itely check-translation
In case this file has been renamed since you last updated the
translation, you should specify both old and new file names, e.g.
CHECKED_FILES=MY_LANGUAGE/{manual,user}/foo.itely
.
To see only which files need to be updated, do
make ISOLANG=MY_LANGUAGE check-translation | grep 'diff --git'
To avoid printing terminal colors control characters, which is often desirable when you redirect output to a file, run
make ISOLANG=MY_LANGUAGE NO_COLOR=1 check-translation
You can see the diffs generated by the commands above as changes that you should make in your language to the existing translation, in order to make your translation up to date.
Note: do not forget to update the committish in each file you have completely updated, see Updating translation committishes.
Global state of the translation is recorded in ‘Documentation/translations.itexi’, which is used to generate 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, and update word counts of documentation files in this Guide.
See also
Maintaining without updating translations.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Check state of translation ] | [ Up : Documentation translation maintenance ] | [ Updating translation committishes > ] |
Updating documentation translation
Instead of running check-translation
, you may want to run
update-translation
, which will run your favorite text editor to
update files. First, make sure environment variable EDITOR
is
set to a text editor command, then run from ‘Documentation/’
make ISOLANG=MY_LANGUAGE update-translation
or to update a single file
make CHECKED_FILES=MY_LANGUAGE/manual/foo.itely update-translation
For each file to be updated, update-translation
will open your
text editor with this file and a diff of the file in English; if the
diff cannot be generated or is bigger than the file in English itself,
the full file in English will be opened instead.
Note: do not forget to update the committish in each file you have completely updated, see Updating translation committishes.
Texinfo skeleton files, i.e. ‘.itely’ files not yet translated,
containing only the first node of the original file in English 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 by issuing from ‘Documentation/’ or ‘Documentation/po/’
make po-update
Note: 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 that can do this odd job for you (run from ‘Documentation/’):
make ISOLANG=MY_LANGUAGE snippet-update
This script overwrites music snippets in
‘MY_LANGUAGE/foo/every.itely’ with music snippets from
‘foo/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. Always use this script
with a lot of care, i.e. run it on a clean Git working tree, and check
the changes it made with git diff
before committing; if you
don’t do so, some @lilypond
snippets might be broken or make
no sense in their context.
Finally, a command runs the three update processes above for all enabled languages (from ‘Documentation/’):
make all-translations-update
Use this command with caution, and keep in mind it will not be really useful until translations are stabilized after the end of GDP and GOP.
See also
Maintaining without updating translations, Adding and editing snippets.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Updating documentation translation ] | [ Up : Documentation translation maintenance ] | [ Translations management policies > ] |
Updating translation committishes
At the beginning of each translated file except PO files, there is a committish which represents the revision of the sources which you have used to translate this file from the file in English.
When you have pulled and updated a translation, it is very important to update this committish in the files you have completely updated (and only these); to do this, first commit possible changes to any documentation in English which you are sure to have done in your translation as well, then replace in the up-to-date translated files the old committish by the committish of latest commit, which can be obtained by doing
git rev-list HEAD |head -1
Most of the changes in the LSR snippets included in the documentation concern
the syntax, not the description inside texidoc=""
. This implies that
quite often you will have to update only the committish of the matching
.texidoc file. This can be a tedious work if there are many snippets to be
marked as up do date. You can use the following command to update the
committishes at once:
cd Documentation/LANG/texidocs sed -i -r 's/[0-9a-z]{40}/NEW-COMMITTISH/' *.texidoc
See also
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Updating documentation translation ] | [ Up : Documentation translation maintenance ] | [ Translations management policies > ] |