# Translating Solfege

Translating GNU Solfege consists of three task.

- The text displayed on buttons and menus, and other short messages are translated using the gettext tool and translating `.po` files, located in the `po/` directory.

- The users guide is made up of several docbook files, located in the `online-docs/` directory.

- Translate the lesson files.

## `.po`-files

- Edit `po/Makefile` and add your language to the LANGUAGES variable.

- Copy `po/solfege.pot` to `po/nn.po` where nn is the two character ISO 639 language code for your language. The language codes are listed in the gettext manual.

- You must set the charset in the .po file. This is done in the very first entry of the file, where charset and Last-Translator etc. are set.

For more info about translating GNU programs, you should have a look at the gettext documentation. Type `info gettext`, or read http://www.gnu.org/software/gettext.

### Ambiguous strings

When you translate the `.po` file, you will notice some msgid strings that look a little strange, for example `"interval|m9".` This is because very short strings can be ambiguous. So some times in the source code I might write `_("interval|m9")` and some other place `_("chord|m9")`. Both strings will be displayed as `"m9"` when you run with english messages. But for some languages the strings might be translated differently. In norwegian `"chord|m9"` is translated to `"m9"` and `"interval|m9"` is translated to `"l9"`. Notice that you should not include the word before "|" in the translated message.

### Strings to take special care of

The string `SOLFEGETRANSLATORS` should name the people that have translated Solfege to that particular language.

One entry starting with "Because not all documents..." contain the uppercase word "LANGUAGE". Here you must replace "LANGUAGE" with the language you are translating to.

The two strings `"notenameformat|%(notename)s"` and `"notenameformat|%(notename)s%(oct)s"` describe how notenames are displayed to the user. Add a translation of this string if you want to change any thing.

`%(unotename)s`

  Untranslated notename

`%(notename)s`

  Translated notename

`%(notename2)s`

  Translated notename. Capitalize the first letter in notename if the note is (in solfege internal format) `c,` or lower.

`%(oct)s`

  Zero or more comma (",") or apostrop ("'") chars that tell the octave.

`%(suboct)s`

  If the tone is b, or lower, this will return a number (1 for "c,", 2 for "c,,", 3 for "c,,," etc.) that will be displayed as small numbers below the line.

`%(supoct)s`

  If the tone is c' or higher, this will return a number (1 for "c'", 2 for "c''", 3 for "c'''" etc.) that will be displayed as small numbers above the line.

## `online-docs/`

Sorry, this section is not finished yet. Please see how things are done for the norwegian or russian translation. If you have questions, you can ask on the mailinglist. But one important thing to remember is to make a note in the top of the translated file on what version of the english (C locale) file the translation is based on. See the file `online-docs/no/chord-help.xml` for an example.

## Lesson files

Lessonfiles can be translated it two ways. Strings can be marked to be looked up in the message cataloges (.po-files):

    name = _("Major")

Or you can include the translation in the lessonfile:

    name = "Major"
    name(no) = "Dur"
    name(fr) = "Majeur"

Generally, for very common strings, like "major", "minor" etc, you can use .po-files, but for the rest, you should include the translation in the lessonfile.

Chord names in lesson files should follow the naming conventions in chord-names.html.

## docbook xml tips

If you have to change the encoding of a file, you can do `iconv -f YOUR_ENCODING -t utf8 thefile.xml`

Some ways to validate your file:

- `nsgmls -s -wxml /usr/lib/sgml/declaration/xml.dcl file.xml`

- `xmllint --dtdvalid /usr/share/sgml/dtd/xml/4.1.2/docbookx.dtd --noout file.xml`

To check if your translated file has the same markup as the english original, you can use the `sgmldiff` command.