README-translations

README for developers and translators
=====================================

Frescobaldi is translated using GNU Gettext.

The translations (in PO files) and the template file ('frescobaldi.pot') live in
the frescobaldi_app/po directory. The 'update-pot.py' script creates a POT file
from all the Python source files. This script must be run if new translatable
strings are added to Frescobaldi.


For developers:
===============

All translatable strings should be wrapped in a _( ... ) construct.
You can use this function with one up to four arguments:

_("String")

        Simply returns a translation for the given string.

_("Context", "String")

        Returns a translation for the string in the given context.

_("Singular text", "Plural text", count)

        Returns a suitable translation (singular/plural) depending on the count.

_("Context", "Singular text", "Plural text", count)

        Returns singular or plural translation within the given context.


The context makes it possible to have different translations for the same source
message.

E.g. _("The music view, noun", "View") can return something like "Weergave",
while _("Command to view the music, verb", "View") should return "Weergeven".

Additionally, when you write a comment starting with L10N (short for localisation),
just before the line containing the string to be translated, it will be included
as a comment in the POT file.

If translatable strings need arguments, you should use named variables, e.g:

_("About {appname}").format(appname = ...)


For translators:
================

You should create or update a PO file for your language.

If you want to translate Frescobaldi to your current locale, simply enter:

$ cd frescobaldi_app/po/
$ msginit -i frescobaldi.pot

otherwise specify the desired language with:

$ msginit -i frescobaldi.pot -l xx_CC

where 'xx_CC' is e.g. 'nl_NL' (or simply 'nl').

Now you can edit the xx.po file with a tool like Lokalize. If done, you can send
the translated po file to the Frescobaldi author if you like, to contribute it
to the Frescobaldi project.

Variables between brackets in the messages like "Viewing page {number} of {total}"
should not be translated but exactly copied to the translation.

If you finished editing the PO file, you can simply run 'make' in the po directory.
This will run the 'msgfmt' program to create a MO file that Frescobaldi can read.
Additionally the MO file will be checked for wrong variable names in translated
messages.