15,534
edits
Changes
→Textual reports
Coding guidelines to enable easy and correct translation of strings on the User Interface.
==Introduction==
Gramps has always been internationalized (see
for the user should always be flagged for translation.
In order to be considered for inclusion in the offical 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. For enabling, a language code must be set on the ''configure.in'' file into ''[[Template:Gramps_translations#ALL_LINGUAS |ALL_LINGUAS]]'' section.
==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.get_translation()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.
=== More complicated translations ===
In addition to <tt>gettext</tt>, GrampsTranslation offers two more specialized retrieval functions, <tt>ngettext</tt> and <tt>sgettext</tt>.
In some strings, it's necessary to specify different translations depending upon the number of an argument. For example,
We'd code that in python as follows:
_ = glocale.get_translation()translation.gettextngettext
_(George Smith and Annie Jones have %(num)d child, George Smith and Annie Jones have %(num)d children, n) % {num : n}
We're making sure that the translators know that this message id means "what's left" rather than "take a nap". When the file is translated, this is no problem, because the translation doesn't include the hint -- but if the user is working in English, we don't want him to see the hint, so we need to alias _ to sgettext:
_ = glocale.get_translation()translation.sgettext Often you need to combine them. While <tt>ngettext</tt> and <tt>sgettext</tt> can each handle plain strings, neither can handle the other's strings. Fortunately the <tt>intltool</tt> message extractor is pretty stupid, so any function name that ends in either <tt>_</tt> or <tt>gettext</tt> will work. This will work pretty well: _ = glocale.translation.gettext N_ = glocale.translation.ngettext S_ = glocale.translation.sgettext Obviously you would pass the translatable string to the right function.
=== Encoding ===
String handling can be a bit tricky in a localized environmentso it's important that developers understand Unicode string handling in both versions of the language. This is mostly a problem for Microsoft Windows™: Mac OSX and Linux use UTF8 for just about everything if the locale is set up correctly (and we try to do that when Grampsstarts up), so one can get away with a lot of encoding mistakes on those platforms. Windows™ on the other hand uses a slightly modified version of UTF16 for file names and retains the old DOS [http://en.wikipedia.org/wiki/Code_page code page] system for encoding output to cmd.exe. The take-away is that if you need to mess with input or output encoding, be sure to test on both Linux and Windows before deciding that you're done. If you're not set up for multiple-platform testing arrange with someone,, who can test for you on the platform you don't have. ====Python 2====Python 2.7 has two text classes, <tt>[https://docs.python.org/2.7/library/functions.html#str str]</tt> and <tt>[https://docs.python.org/2.7/library/functions.html#unicode unicode]</tt>. <tt>Unicode</tt> objects are encoded in UTF16 internally on most platforms, and most python '''output''s translation facility ' functions will do the right thing with them. One caveat here: passing both <tt>unicodes</tt> and <tt>strs</tt> to <tt>os.path.join()</tt> will always return Unicode-a <tt>str</tt>, so either make sure when constructing a path that all arguments are <tt>unicodes</tt> or convert the result. The bsddb module that ships with Python2 is stupid about paths and requires that they be encoded stringsin the file system encoding. For as long as it This is necessary handled in gramps/gen/db/write.py with _encode() and independently in a few other places. Strings from the operating system, including environment variables, are a problem on Windows™; The os module uses for input the [http://msdn.microsoft.com/en-us/library/windows/desktop/dd317766%28v=vs.85%29.aspx ANSI API] to the Windows SDK, which interprets the value of the environment variable according to support both Python2 the active code page and Python3produces a <tt>str</tt>, developers will need converting any codepoints > 0xff to ? and often misinterpreting those between 0x0f and 0xff if the encoding of the input happens to be something other than the active system codepage. Once this is done it is quite difficult to understand get non-ASCII pathnames back into a useable form, so gramps/gen/constfunc.py provides a get_env_var() function that uses the [http://msdn.microsoft.com/en-us/library/windows/desktop/dd374081(v=vs.85).aspx Unicode API] to instead. Always use that function to read environment variables which might include non-ASCII characters and avoid using os-module functions for reading paths. By default string handling constants in both versions of Python 2 are <tt>str</tt>. ====Python 3====Python 3 also provides two test classes, <tt>[https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str str]</tt> and <tt>[https://docs.python.org/3/library/stdtypes.html#binary-sequence-types-bytes-bytearray-memoryview bytes]</tt>. In Python 3, <tt>str</tt> is the languageunicode type and <tt>bytes</tt> is text encoded some other way. Everything pretty much "just works".
====For portable string handling on all platforms and for all locales====* Localized strings returned from gettext, ngettext, etc. are always unicode* Text files should always be encoded in UTF8. The easy and portable way to do this is to:*: <pre>import io</pre>*: <pre>fh = io.open(filepath, mode, encoding='utf8')</pre>*: where ''mode'' is one of r, rw, r+, or w+. ''Don't open these files in binary mode!'' Pass unicode-type strings to fh.write() and expect the same from fh.read().* Always read environment variables with <tt>constfuncs.get_env_var()</tt> if there's any chance that it will contain a non-ASCII character.* Use <tt>from __future__ import unicode_literals</tt> in any source file which might present strings to the user or to the operating system.*:When creating string literals, '''don'Notet do this: The '''*:<pre>print _(u"Eg, valid values are 12.0154, 50° 52′ 21.92″N")</pre>*:Because the <tt>u' </tt> prefix was removed from python3 with for Python 3.0-3.2. (It was restored in 3.0 and reintroduced 3 for backwards compatibility with 32.7, but it's not necessary.3)*:Instead, put in the first line of the module*:<pre># *-* coding: utf-8 *-*</pre>*:then in the imports section*:<pre>from __future__ import unicode_literals</pre>*:which makes all of the literals unicode.0'''Make sure that your editor is set up to save utf-8!'''
===Into glade fileGlade files===
Just enable the translatable attribute on an XML element.
See [[Accessibility]].
===Into addons pluginsAddons===
External addons often need to provide their own message catalogs. To pull one in, use
this instead of the usual.
from gramps.gen.const import import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext
or if you need more than one retrieval function:
_translation = glocale.get_addon_translator(__file__)
_ = _translation.gettext
S_ = _translation.sgettext
The addon translator is another instance of GrampsTranslation, so the rules for creating
translatable strings and for retrieving the translated values are the same as for internal modules.
See [[Addons_Development#Localization|Addons development]] for more details.
* [[Translation_environment20|2.0.x]]
* [[Translation_environment22|2.2.x to Gramps 3.4.x]]
* [[Translation_environment4|TrunkGramps 4.0.x to master (trunk)]]
There are two stages to getting a translation to work.
* [[Translation_environment22#Files_and_directory|2.2.x to Gramps 3.4.x]]
* [[Translation_environment4#Files_and_directory|TrunkGramps 4.0.x, master (trunk)]]
==Tips for writing a translatable Python module==
daughter: %s
which doesn't require genitive.
===Punctuation===
Use of commas, semicolons and spacing can be different than into english.
''todo''
==Changing translated text message in the source code==
One of the severities in our bug tracker is "text", which ranks up as easier than "tweak" and "minor", but more difficult than "trivial". If a bug is concerned with readability or correctness of a text that Gramps outputs, whether in GUI, in a console error message, or in a produced report, then "text" is the severity to use. So why is it more than "trivial"?
As described above, any translated text in the source code gets reflected into tens of *.po files, maintained by the translators. So every time you just change it in the source, ALL the translators need to do the translation again. Normally, the translation environment will give a prudent suggestion, but there is still a manual approval step. If you check in the change, the string will not be translated until the translators pick it up.
This is why, if what you change is just a couple of spelling mistakes, a missing comma in the middle, or maybe an extra space somewhere in the message, it's a good idea to save the translators' work, by doing a global search and replace of your source message text in the *.po files, and committing these along with your change.
For short enough messages, that don't span multiple lines in the *po files, you can do it by executing
perl -pi -e 's/YOUR MESSAGE BEFORE CORRECTION/your message after correction/g;' *.po *.pot
in the po/ directory. Make sure you do a "git diff" and observe the results make sense. (You'll probably have to escape some characters in the regular expression, such as | or .).
To make it easier to port your changes across multiple branches, it's a good idea to separate the changes in the source tree from the po/ ones. This way, you'll be able to quickly re-apply the source changes using normal cross-branch porting workflow (such as `git cherry-pick'), and then adjust and re-run the search-and-replace in the po/ on the new branch, because, most likely, it won't reapply due to the differences in the .po layout.
{{man note| Note |To stress it again, only do it for text change that didn't change how it is going to be translated. If you'd like your change to be somehow reflected in the translations, let the translators do the work instead.}}
==Textual reports==
Since Gramps-3.2 we are able to select the language for textual reports, see [http://wwwfeature {{bug|2371}}. For Gramps it was only available on Ancestor report (3.2.gramps-projectx) and detailed reports (3.org/bugs/view3.php?id=2371 this feature]x).
For providing this option:
self.__get_date(event.get_date_object())
self.__get_type(event.get_type())
[[Category:Translators/Categories]]
[[Category:Developers/Tutorials]]
[[Category:Developers/General]]
[[Category:Addons]]
