| [ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
| [ < Starting translation in a new language ] | [ Up : Translating the documentation ] | [ Files to be translated > ] | ||
5.8.2 Documentation translation details
Please follow all the instructions with care to ensure quality work.
All files should be encoded in UTF-8.
| Files to be translated | ||
| Translating the Web site and other Texinfo documentation | ||
| Adding a Texinfo manual |
Files to be translated
Translation of ‘Documentation/foo/bar’ should be ‘Documentation/LANG/foo/bar’. Unmentioned files should not be translated.
Priorities:
- 1. delivery,
- 2. 3. 4. 5. 6. later,
- 7. optional.
Files of priority 1 should be submitted along all files generated by starting a new language in the same commit and thus a unique patch, and the translation of files marked with priority 2 should be committed to Git at the same time and thus sent in a single patch. Files marked with priority 3 or more may be submitted individually. Word counts (excluding LilyPond snippets) are given for each file. For knowing how to commit your work to Git, then make patches of your new translations as well as corrections and updates, see Basic Git procedures.
-1- Web site 616 web.texi 4937 web/introduction.itexi 1201 web/download.itexi 1139 macros.itexi 7977 po/lilypond-doc.pot (translate to po/MY_LANGUAGE.po) 0 search-box.ihtml --- lilypond-texi2html.init (section TRANSLATIONS) 15870 total -2- Tutorial 1284 web/manuals.itexi 124 learning.tely 2578 learning/tutorial.itely 4396 learning/common-notation.itely 8382 total -3- Fundamental Concepts, starting of Usage and Community 11144 learning/fundamental.itely -- Fundamental concepts 135 usage.tely 4537 usage/running.itely 1484 usage/updating.itely 3073 web/community.itexi 20373 total -4- Rest of Learning manual and Suggestions on writing LilyPond files 16191 learning/tweaks.itely -- Tweaking output 372 learning/templates.itely -- Templates 2692 usage/suggestions.itely -- Suggestions on writing LilyPond files 19255 total -5- Notation reference 326 notation.tely 91 notation/notation.itely -- Musical notation 4990 notation/pitches.itely 6890 notation/rhythms.itely 1793 notation/expressive.itely 1050 notation/repeats.itely 2821 notation/simultaneous.itely 2476 notation/staff.itely 954 notation/editorial.itely 2816 notation/text.itely 81 notation/specialist.itely -- Specialist notation 5190 notation/vocal.itely 1972 notation/chords.itely 702 notation/piano.itely 811 notation/percussion.itely 826 notation/guitar.itely 66 notation/strings.itely 242 notation/bagpipes.itely 5375 notation/ancient.itely 10392 notation/input.itely -- Input syntax 2164 notation/non-music.itely -- Non-musical notation 12256 notation/spacing.itely -- Spacing issues 15289 notation/changing-defaults.itely -- Changing defaults 5187 notation/programming-interface.itely -- Interfaces for programmers 2176 notation/notation-appendices.itely -- Notation manual tables 252 notation/cheatsheet.itely -- Cheat sheet 87188 total -6- Rest of Application Usage 4137 usage/lilypond-book.itely -- LilyPond-book 1122 usage/converters.itely -- Converting from other formats 5259 total -7- Appendices whose translation is optional 326 essay/literature.itely 1222 learning/scheme-tutorial.itely (should be revised first) 1548 total
In addition, not listed above, Snippets’ titles and descriptions should be translated; they are a part of the Notation Reference and therefore their priority is 5.
| [ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
| [ < Files to be translated ] | [ Up : Documentation translation details ] | [ Adding a Texinfo manual > ] | ||
Translating the Web site and other Texinfo documentation
Every piece of text should be translated in the source file, except
Texinfo comments, text in @lilypond blocks and a few cases
mentioned below.
Node names are translated, but the original node name in English should
be kept as the argument of @translationof put after the section
title; that is, every piece in the original file like
@node Foo bar @section_command Bar baz
should be translated as
@node translation of Foo bar @section_command translation of Bar baz @translationof Foo bar
The argument of @rglos commands and the first argument of
@rglosnamed commands must not be translated, as it is the node
name of an entry in Music Glossary.
Every time you translate a node name in a cross-reference, i.e. the
argument of commands @ref, @rprogram, @rlearning, @rlsr,
@ruser or the first argument of their *named variants,
you should make sure the target node is defined in the correct source
file; if you do not intend to translate the target node right now, you
should at least write the node definition (that is, the @node
@section_commmand @translationof trio mentioned above) in the
expected source file and define all its parent nodes; for each node you
have defined this way but have not translated, insert a line that
contains @untranslated. That is, you should end up
for each untranslated node with something like
@node translation of Foo bar @section_command translation of Bar baz @translationof Foo bar @untranslated
Note: you do not have to translate the node name of a cross-reference to a node that you do not have translated. If you do, you must define an “empty” node like explained just above; this will produce a cross-reference with the translated node name in output, although the target node will still be in English. On the opposite, if all cross-references that refer to an untranslated node use the node name in English, then you do not have to define such an “empty” node, and the cross-reference text will appear in English in the output. The choice between these two strategies implies its particular maintenance requirements and is left to the translators, although the opinion of the Translation meister leans towards not translating these cross-references.
Please think of the fact that it may not make sense translating everything in some Texinfo files, and you may take distance from the original text; for instance, in the translation of the web site section Community, you may take this into account depending on what you know the community in your language is willing to support, which is possible only if you personally assume this support, or there exists a public forum or mailing list listed in Community for LilyPond in your language:
- Bug reports: this page should be translated only if you know that every bug report sent on your language’s mailing list or forum will be handled by someone who will translate it to English and send it on bug-lilypond or add an issue in the tracker, then translate back the reply from developers.
- Help us: this page should be translated very freely, and possibly not at all: ask help for contributing to LilyPond for tasks that LilyPond community in your language is able and going to handle.
In any case, please mark in your work the sections which do not result
from the direct translation of a piece of English translation, using
comments i.e. lines starting with ‘@c’.
Finally, press in Emacs <C-c C-u C-a> to update or generate
menus. This process should be made easier in the future, when the helper
script texi-langutils.py and the makefile target are updated.
Some pieces of text manipulated by build scripts that appear in the
output are translated in a ‘.po’ file – just like LilyPond output
messages – in ‘Documentation/po’. The Gettext domain is named
lilypond-doc, and unlike lilypond domain it is not managed
through the Free Translation Project.
Take care of using typographic rules for your language, especially in ‘macros.itexi’.
If you wonder whether a word, phrase or larger piece of text should be translated, whether it is an argument of a Texinfo command or a small piece sandwiched between two Texinfo commands, try to track whether and where it appears in PDF and/or HTML output as visible text. This piece of advice is especially useful for translating ‘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 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, starting with
@c KEEP LY
Otherwise the music snippet would be reset to the same content as the
English version at next make snippet-update run – see
Updating documentation translation.
When you encounter
@lilypondfile[<number of fragment options>,texidoc]{filename.ly}
in the source, open ‘Documentation/snippets/filename.ly’,
translate the texidoc header field it contains, enclose it with
texidocMY-LANGUAGE = " and ", and write it into
‘Documentation/MY-LANGUAGE/texidocs/filename.texidoc’.
Additionally, 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,
‘Documentation/MY-LANGUAGE/texidocs/filename.texidoc’
may contain
doctitlees = "Spanish title baz" texidoces = " Spanish translation blah "
@example blocks need not be verbatim copies, e.g. variable
names, file names and comments should be translated.
Finally, please carefully apply every rule exposed in Texinfo introduction and usage policy, and Documentation policy. If one of these rules conflicts with a rule specific to your language, please ask the Translation meister on translations@lilynet.net list and/or the Documentation Editors on lilypond-devel@gnu.org list.
Adding a Texinfo manual
In order to start translating a new manual whose basename is FOO, do
cd Documentation/MY-LANGUAGE cp ../FOO.tely . mkdir FOO cp web/GNUmakefile FOO
then append FOO to variable SUBDIRS in
Documentation/MY-LANGUAGE/GNUmakefile, then translate file
MY-LANGUAGE/FOO.tely and run skeleton-update:
cd Documentation/ make ISOLANG=MY-LANGUAGE TEXI_LANGUTIL_FLAGS=--head-only skeleton-update
Your are now ready to translate the new manual exactly like the web site or the Learning Manual.