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 i18n directory. The user guide has its own template file
('userguide.pot').

The 'update-pot.py' script creates both template files from all Python source
files in 'frescobaldi_app', from a couple of files in 'linux' and from the
userguide pages in MarkDown format located in 'frescobaldi_app/userguide'.

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 = ...)

Always use full text sentences, without whitespace around it.

Use:        _("The file '{name}' can't be found.")
and not:    _("The file '") + name + _("' can't be found.")

Use:        _("The command exited with an error message:") + "\n\n" + errmsg
and not:    _("The command exited with an error message:\n\n") + errmsg

(You could write:

    _("The command exited with an error message:\n\n{msg}").format(msg=errmsg)

in the last case, but the first solution is the preferred one.)

Don't use empty or numbered format braces; always have a meaningful variable
name, because in other languages the order of the arguments could be different.

Use:        _("Printing page {num} of {total}...").format(num=num, total=count)
and not:    _("Printing page {} of {}...").format(num, count)

Be sure the string is translated first, then formatted. The following won't
work, although syntactically correct, because the formatted string can't be
found in the translation database:

    _("Can't find file: '{name}'".format(name=filename))

Instead, you should write:

    _("Can't find file: '{name}'").format(name=filename)



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

If your language is not present already, you should create the PO files.
The translation of the userguide, separated from the main application, is
optional but recommended. In order to add the language 'xx_CC', enter:

$ cd i18n
$ msginit -i frescobaldi.pot -l xx_CC -o frescobaldi/xx_CC.po
$ msginit -i userguide.pot -l xx_CC -o userguide/xx_CC.po

where 'xx_CC' is your language, e.g. 'nl_NL' (or simply 'nl').
Then add your 'xx_CC' language code to the respective LINGUAS file in
each subdirectory.

Now you can edit the xx_CC.po files in each directory with a tool like
Lokalize or Poedit. When done, you can send the translated po file(s)
to the Frescobaldi author or open a PR on Github, to contribute it to the
Frescobaldi project.

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

Updating an existing translation requires updating the template files (.pot)
and then the .po files.  While the 'make' command without argoments will do
this for all the available languages, you'll probably want to update only
your language files:

$ cd i18n
$ make pot
$ make frescobaldi/xx_CC.po
$ make userguide/xx_CC.po

You can now update the .po files.

Finally you may want to see how your changes look in the application.
You should generate a MO (Message Object) file that Frescobaldi can read.
Simply run:

$ make ../frescobaldi_app/i18n/xx_CC.mo

The generated MO file contains the translations from both the application
and the userguide. It will be checked for wrong variable names in translated
messages.

MO files are placed in the 'frescobaldi_app/i18n/' directory, so they
are packaged and installed along with Frescobaldi.