Difference between revisions of "I18N"

Revision as of 19:18, 6 September 2019

This section collects some notes for developers/programmers on how to correctly prepare their code for translations.

General Thoughts

Which strings translation need

* Obvisious strings presented to the user should be translatable,

* but strings, which go into the log, should not. At least some of us have problems to read log entries in CJK writing.

Avoid Ambiguity

This can be achieved in several ways:

• Use of full sentences, i.e. for tooltips.
• Use of context for short messages like column headers.
• Adding translator comments.
• Add an entry to the glossary, if a term needs explanation and is used more than once.

How to make strings in code translatable

Strings in Glade files

In Glade files translatable strings have the form:

   <property name="label"
      translatable="yes"
      context="infinitive" 
      comments="Additional infos for the translator">Some translatable text with _mnemonic</property>
   <property name="visible">True</property>
   <property name="can_focus">True</property>
   <property name="receives_default">False</property>
   <property name="use_underline">True</property>

Note

The linebreaks were inserted for legability.

Attributes

translatable

required for translation,

context

Optional to restrict the context,

comments

Optional for additional infos.

For the mnemonic property use_underline see Translation#Special_characters_and_other_tips.

Strings in C files

Preparation

Each C module

• having translated C strings or
• containing printf()/fprintf()/... calls with a format string that could be a translated C string

#include <libintl.h>

Source

https://www.gnu.org/software/gettext/manual/html_node/Importing.htm.

#include <glib/gi18n.h>

Details

https://developer.gnome.org/glib/stable/glib-I18N.html

Direct translation

Normally, strings in C code just need to be enclosed with the function _( ). Well, actually it is a macro declared as #define _(String) gettext (String), but this is usually just an implementation detail. For example,

 func("A translatable string!");

should instead be written as

 func(_("A translatable string!"));

However, it is important to keep in mind that _( ) is a function; this means that in certain situations it cannot be used. For example,

 gchar* array_of_strings[] = {_("first string"), _("second string"), _("third string")};

would cause a compiler error.

Delayed translation

Instead, these strings should be wrapped with the N_( ) macro, which is declared as #define N_(String) gettext_noop(String). Then, whenever one of the strings is actually used (as opposed to declared), it should be wrapped with the _( ) function again:

gchar* array_of_strings[] = {N_("first string"), N_("second string"), N_("third string")};
:
func(_(array_of_strings[0]));

gchar* msg = N_("Something went wrong!");   /* Tell xgettext to insert the string into gnucash.pot */
PWARN (msg);   /* Record it untranslated in the trace file */
/* pop up a window with ... */
   _(msg)   /* Inform the user with the translated message */

For more macros search your IncludeDir for Glib and that for gi18n.h.

See also: #Distinguish Contexts

Strings in C Preprocessor Macros

Xgettext doesn't run cpp and can't see inside macros. Call gettext in the macro, not on the macro.

Wrong

#define EXPLANATION "The list below shows ..."
/* snip */
gnc_ui_object_references_show( _(EXPLANATION), list);

Right

#define EXPLANATION  _("The list below shows ...")
/* snip */
gnc_ui_object_references_show(EXPLANATION, list);

Strings in C++ files

For strings in C++ files the same techniques as for C files can be used. The drawback of this is one could only work with C-style strings (char*), which means one would not be able to benefit from the many advantages of C++.

A better alternative is to use boost::locale's message translation functionality.

In order to use this, one needs to add the following near the top of the C++ source file:

#include <boost/locale.hpp>
// Optionally:
namespace bl = boost::locale;
// to be able to use bl::translate and bl::format instead of boost::locale::translate and boost::locale::format

After that using boost::locale essentially means using boost::locale::translate() instead of gettext(). This function is designed to be used in a stream and work with the locale imbued in the stream, so one would usually

• create a stringstream
• imbue the desired locale
• stream the result of boost::locale::translate into this stream
• when completely done, copy the string from the stringstream.

The link above gives some more elaborate examples and you can find some examples in the gnucash code already as well, like in filepathutils.cpp.

The biggest hurdle at the time of this writing is imbuing a locale in the stream. For most of the uses in gnucash this should simply be the global locale. However we don't set this yet in the C++ environment (where to do this still has to be determined). So the few spots in the code where we use this feature are generating a locale on the spot to imbue and that continues to be required until we set a global C++ locale.

Formatted strings

Some strings come have placeholders in that can only be completed at runtime, like a number of transactions in a selection, or the name of a file to be opened. The C world has a whole set of functions that work with such format strings (printf and all variants).

For C++ a more elegant method exists as well in the form of boost's localized text formatting. These have several advantages over the C based format functions, so in C++ it's recommended to use the boost::locale::format features.

Plural Forms

Not all languages have the same simple kind of plural forms as english. See gettexts Plural-forms for details.

Empty Strings

There is no need, to mark an empty string as translatable. The gettext tools use the empty string for their message catalog header. So it will confuse translators to have your preceding comment in the header of their .po file.

Avoid underline

Because Underline _marks mnemonics in the GUI, do not use it for other purposes. It would confuse msgfmt -c --check-accelerators="_" else. Use the normal dash - instead.

Avoid Markups and Other Formating

It is annoying, if you have to translate "number", "number:", "number: ", "<b>number</b>", "Number", "NUMBER" all separate. In many cases you can move the formating elements outside of the translatable string or use functions for case conversion.

Mask Unintended Line Breaks

   (_ "This report is useful to calculate periodic business tax payable/receivable from
 authorities. From 'Edit report options' above, choose your Business Income and Business Expense accounts.
 Each transaction may contain, in addition to the accounts payable/receivable or bank accounts,
 a split to a tax account, e.g. Income:Sales -$1000, Liability:GST on Sales -$100, Asset:Bank $1100.")

#: gnucash/report/standard-reports/income-gst-statement.scm:43
msgid ""
"This report is useful to calculate periodic business tax payable/receivable "
"from\n"
" authorities. From 'Edit report options' above, choose your Business Income "
"and Business Expense accounts.\n"
" Each transaction may contain, in addition to the accounts payable/"
"receivable or bank accounts,\n"
" a split to a tax account, e.g. Income:Sales -$1000, Liability:GST on Sales -"
"$100, Asset:Bank $1100."

Watch all the "\n"s, which get inserted by xgettext and the leading spaces in the next line. While the newlines are ignored by the HTML renderer, the translators get confused.

   (_ "This report is useful to calculate periodic business tax payable/receivable from \
authorities. From 'Edit report options' above, choose your Business Income and Business Expense accounts. \
Each transaction may contain, in addition to the accounts payable/receivable or bank accounts, \
a split to a tax account, e.g. Income:Sales -$1000, Liability:GST on Sales -$100, Asset:Bank $1100.")

#: gnucash/report/standard-reports/income-gst-statement.scm:43
msgid ""
"This report is useful to calculate periodic business tax payable/receivable "
"from authorities. From 'Edit report options' above, choose your Business "
"Income and Business Expense accounts. Each transaction may contain, in "
"addition to the accounts payable/receivable or bank accounts, a split to a "
"tax account, e.g. Income:Sales -$1000, Liability:GST on Sales -$100, Asset:"
"Bank $1100."

How to give the translators a clue

Sometimes it is useful to give the translators some additional information about the meaning of a string. To achieve this effect, you can insert a section of comment lines direct before the related string, where the first comment starts with "Translators:". There must not be any control statement between comment and string.

In C based files

 /* Translators: the following string deals about:
    The Answer to Life, the Universe and Everything
    Source:
    http://en.wikipedia.org/wiki/Phrases_from_The_Hitchhiker%27s_Guide_to_the_Galaxy */
 func(_("42"));

In the pot and po files, this comment will show up as follows:

#. Translators: the following string deals about:
#. The Answer to Life, the Universe and Everything
#. Source:
#. http://en.wikipedia.org/wiki/Phrases_from_The_Hitchhiker%27s_Guide_to_the_Galaxy
#: foo/bar.c:123
msgid "42"
msgstr ""

Note: An empty comment line will end the process. If the string " Source:" were missing, the URL were not part of the output.

In SCM files

If the first expression has a translatable string and the file has a long header comment, split the line before the string and insert a translator comment. Otherwise the POT file will be flooded with file headers.

;; Boston, MA  02110-1301,  USA       gnu@gnu.org
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


(define GNC_COMMODITY_NS_CURRENCY
;; Translators: Namespaces of commodities
   (gettext "CURRENCY"))

In glade files

In glade 3.16, using the edit button for a label, one can set the translatable flag, enter translation comments and if required, define a context. From intltool fails to extract comments from glade-type files when not last attributes:

 <property name="label" translatable="yes" context="infinitive" comments="my comment">

Distinguish Contexts

See https://bugs.gnucash.org/show_bug.cgi?id=797349#c22 for the current state of the discussion.

Disambiguation Prefix

At some places, GnuCash uses "disambiguation prefixes" in translatable strings. Here is an old explanation: https://lists.gnucash.org/pipermail/gnucash-devel/2005-October/014236.html ; more explanation is also here: http://live.gnome.org/GnomeI18nDeveloperTips .

There are at least 2 use cases:

• Abbreviations, i.e. for columns and their headers:

msgid "Reconciled"
msgstr "Abgeglichen"
:
msgid "Reconciled:R"
msgstr "Reconciled:A"

• Sample text to determinate the size of the output cell. Here is no translation required, but the "worst case" of expected text. For the following example the german tranlators copied the longest path of account names from their business account templates as shown in the accounts tab of Gnucash:

msgid "sample:Expenses:Automobile:Gasoline"
msgstr "sample:Aufwendungen 2/4:Reparatur/Instandhaltung:4805 Reparatur u. Instandh. von Anlagen/Maschinen u. Betriebs- u. Geschäftsausst."

@Developers: In the normal source code of a gtk-based program, this feature is available by simply using the Q_( ) macro instead of the _( ) macro.

This would be used e.g. as follows

  /* Translators: This string has a disambiguation prefix */
  func(Q_("Noun|Transfer"));

where the string that shows up in the GUI is simply "Transfer", but the translators need the prefix to be able to choose the correct translation of the noun vs. the verb.

In the latest gettext versions, this disambiguation is solved in yet another way by introducing an additional "context string" in addition to the translatable string, see below. As this is still a relatively new feature, we don't use this in GnuCash yet.

Context by Particular Gettext

A more recent method is "particular gettext" pgettext().

Example:

 pgettext("account status: not cleared", "n")

would result in a msgid like:

#: src/app-utils/gnc-ui-util.c:656
msgctxt "account status: not cleared"
msgid "n"
msgstr ""

See Gettext Manual: Contexts for details.

Introducing new terms

If you introduce new terms which are more than once used, you should include them to Translation#The_glossary_file. The instruction is in Translation#Terms missing or inadequate in the glossary file.

Borrowing Code

Ideally they would use their own text domain like in our use of ISOcode.

If not - like in 2.7 /borrowed/goffice - we should consider some msgcat magic with their po files to

• update our existing po files
• create new po files.

At present a bash script was written to take care of the first part: import-goffice-translations.sh in contrib/.

This script can be used to import translations from the goffice source directory into our po files. Note this script will run over all of our existing po files in one go, so it can only be used to update all po files at once.

There is no code to create new po files. I think this can be done in a few steps as well, as in

1. create the new po file as we would normally do for gnucash (see msginit elsewhere on this page)
2. run the script mentioned above to import goffice translations
3. this may change more files than needed, use git checkout to undo the changes to files you didn't want to alter
4. continue as usual with translation work.

Using Other Programming Languages

1. Adapt https://www.gnu.org/software/gettext/manual/gettext.html#Sources for your source language.

   Note

   The initialization is done in gnucash/gnucash-bin.c, search #ifdef HAVE_GETTEXT.

2. Add the file extensions of the source files, which contain translatable strings, to the list of make_gnucash_potfiles in po/CMakeLists.txt.

   Verify the ${path} in the next section is still correct.

3. Are changes required in po/gnucash-pot.cmake, i.e. additional --keyword or --flag options for xgettext?
4. If there are files in the search path, which should be skipped, add them with the reason to po/POTFILES.skip
5. Write down your experience as a subsection here.

Python

Python gettext seems to need a separate initialization in addition to that in gnucash/gnucash-bin.c. There is a developmental Pull Request dealing with that: [1].

Further Reading

If you want to read more about this topic, GnomeI18nDeveloperTips might be a good starting point.

Follow the rules of the Gnome Human Interface Guide like Writing style and Typography.

More technical and historical details can be found in Gettext Manual: The Programmer’s View,

Guile/Scheme

Guile Reference Manual: Support for Internationalization,

Python

The Python Standard Library: Internationalization.