Changes

Jump to: navigation, search

Coding for translation using weblate

2,310 bytes added, 29 June
no edit summary
Coding guidelines to enable easy and correct translation of strings on the User Interface.
==Introduction== 
Gramps has always been internationalized (see: https://gramps-project.org/introduction-WP/2006/04/looking-back-over-5-years/ ) Therefore, all strings meant for the user should always be flagged for translation.
In order to be considered for inclusion in the official Gramps release, any piece of code must support internationalization. What this means is that the Python module must support [[Translating Gramps|translations]] into different languages. Gramps provides support to make this as easy as possible for the developer.
==Adding a new language== 
To add a new language, navigate to the "gramps" component in Weblate and click on the '''Tools -> Start new translation''' menu option. Then select a language code. You need to be a Weblate administrator to do this.
An entry must also be made in the <code>_LOCALE_NAMES</code> dictionary in the [https://github.com/gramps-project/gramps/blob/master/gramps/gen/utils/grampslocale.py#L70 grampslocale.py] file.
 
= How to allow translations =
 
Gramps is a fully-internationalized application with translations in many languages. All code which presents text to users must provide for that text to be translated. Fortunately, Gramps provides an extension of [http://docs.python.org/3/library/gettext.html gettext] which makes this fairly painless. First, alias the gettext function from the single localization instance:
from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.translation.gettext
This statement imports the <code>gettext</code> function and aliases it as <code>_</code>. The translation tools treat strings wrapped in _() as translatable and assemble them into catalogs for the translators to work with; by aliasing it to gettext(), we also enable python to retrieve the translation appropriate for the user's locale.
 
Example 1:
print("Hello world!")
 
In this example, the string will always be printed as specified.
 
Example 1 internationalized:
print _("Hello world!")
 
In this example, Gramps will attempt to translate the string. If a translation exists, the call to the function will return the translation. If a translation does not exist, the original string is returned.
 
= Plurals =
 
In some strings, it's necessary to specify different translations depending upon the number of an argument. For example,
George Smith and Annie Jones have 1 child
George Smith and Annie Jones have 3 children
 
We'd code that in python as follows:
_ = glocale.translation.ngettext
_(George Smith and Annie Jones have %(num)d child, George Smith and Annie Jones have %(num)d children, n) % {num : n}
 
= Context =
 
Sometimes a word in English can have different meanings, for example, "rest" can mean either "what's left" or "take a nap".
In such cases, we can provide the context by passing a second optional parameter:
_("rest", "Remaining names")
 
We're making sure that the translators know the context of the string. The context is made available to the translators in Weblate, but is not displayed to the user.
 
= Comments =
 
A note can be passed to the translators by including a comment in the code on the line before the translated string. This comment must begin with the string "Translators:" and may be multi-line.
 
# Translators: Keep your translation short
_("short string")

Navigation menu