Translating the website 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 not translated, only the section titles are. That is, every piece in the original file like

@node Foo bar
@section_command Bar baz

should be translated as

@node Foo bar
@section_command translation of Bar baz

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 the Music Glossary.

Every time you translate a node name in a cross-reference, i.e., the argument of commands like @ref or @rprogram (see Cross-references for the complete list) 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 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 Foo bar
@section_command translation of Bar baz

@untranslated

(the new-lang target does this in the skeleton files).

Please consider that it may not make sense to translate everything in some Texinfo files, and that you may deviate from the original text if necessary or useful. For instance, in the translation of the website section “Community”, you may add information on the community in your language and give links to existing public forums or mailing lists.

• 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 to bug-lilypond or add an issue in the tracker, then translate back the reply from developers. [Today, with the help of automatic translators available in the internet, this is less of a concern.]
• Help us: this page should be translated very freely, and possibly not at all – a translation makes only sense if there are enough people interested in contributing language-specific documentation work. For actually working on the code you have to communicate with the developers in English.

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’.

Don’t forget to update Texinfo menus, see Regenerating menus.

Some pieces of text manipulated by build scripts that appear in the output are translated in a .po file; this has been discussed in the previous section.

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 blocks). 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[...,texidoc,...]{filename.ly}

in the source, open Documentation/snippets/filename.ly, translate the texidoc header field it contains, wrap it with texidocMY-LANGUAGE = "...", and write it into Documentation/MY-LANGUAGE/texidocs/filename.texidoc. Additionally, you may translate the snippet’s title in the 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/es/texidocs/filename.texidoc may contain

doctitlees = "Spanish title baz"
texidoces = "
Spanish translation blah
"

@example blocks need not be verbatim copies; it often makes sense to translate variable names, file names, and comments.

Finally, please carefully apply every rule exposed previously; see Texinfo introduction and usage policy, and Documentation policy. If one of these rules conflicts with a rule specific to your language, please ask on the lilypond-devel@gnu.org list.