David @ Tokyo

Enlightenment DR17 has had internationalization support for the best part of a year now. Thus, providing a appropriate translation is available, it's possible to have the entire window manager's interface displayed in almost any given language.

However, due to the underlying gettext-based implementation that e17's internationalization support is built on, there are issues for module developers wishing to include internationalization as a feature of their 3rd party modules.

First a quick word about how the gettext-based internationalization support works.
1) Strings throughout the e17 code base that require translation are marked accordingly. Enlightenment uses a common method of wrapping strings to be translated in _(). For example:

e_dialog_title_set(exit_dialog, _("Are you sure you want to exit?"));
e_dialog_text_set(exit_dialog,
        _("You requested to exit Enlightenment.<br>"
          "<br>"
          "Are you sure you want to exit?"
          ));

2) This _() technique isn't magic of course - it's actually a macro, which is defined in e17/apps/e/src/bin/e_intl.h as follows:

#include <libintl.h>

#define _(str) gettext(str)
#define d_(str, dom) dgettext(PACKAGE dom, str)

So when the C pre-processor runs over the code before compiliation, all those _("string") occurances are replaced with gettext("string") calls. gettext and other related functions (like dgettext, which we'll see more of later) are declared in libintl.h.

What does gettext do? It takes the input string, and uses it as a key to search in a message catalog for a translation. Which catalog is searched in is determined by the users locale / language environment settings. If it doesn't find a translation, then it just returns the key string as the result.

3) How are the message catalogs created? There are three steps:
a) When the autogen.sh script runs it executes the command xgettext to extract all the marked strings from the source code out in to a message catalog template.
b) Next, a translator copies the template, and creates a PO file, and does the translation exercise
c) When make is run to build e, msgfmt is used to compile the text based translation catalog into a binary format for use during run-time.

4) This isn't quite enough yet. In a basic program, the following needs to be done to trigger gettext operations.

setlocale (LC_ALL, "");
bindtextdomain (domain-name, path);
textdomain (domain-name);

Enlightenment actually does things a bit differently (see e_intl.c) but basically there has to be a setlocale call of some kind. The next two function calls are more interesting for module writers. bindtextdomain is used to specify the base directory for which message catalogs should be searched from, for a given domain (or namespace). For Enlightenment the domain would be "enlightenment", and for a module, we would just use whatever our module is called, i.e., "mymodule".
The path specified should be the path up to "locale". For example, Enlightenment would use "<prefix>/lib/locale"
The binary message catalogs are later to be installed to <path>/<locale>/LC_MESSAGES/domain-name.mo
For example, a Japanese (locale = ja) catalog for the "moon" module, installed to the user's home directory would be located under ~/.e/e/locale/ja/LC_MESSAGES/moon.mo
The final function, textdomain sets the domain-name as the domain to be used for all subsequent calls to the gettext function. Using this saves the programmer from having to specify the domain to be used for every single gettext call throughout the entire source code.

So how do modules fit in?

Issue 1: As 3rd party modules are developed, maintained and distributed independently of e17 itself, they can't be translated in the same message catalog as what enlightenment itself uses. Modules therefore will have to use their own message catalogs.
-> Modules must include a call to bindtextdomain to specify the path where the modules' message catalogs are stored
Issue 2: As 3rd party modules can't use enlightenment's message catalog, but the modules are dynamically loaded as part of the enlightenment, modules can't use textdomain and gettext. If they do, all the message translations in enlightenment that rely on the default domain being "enlightenment" will stop working. This would not be a popular module!
-> Modules must use dgettext, which is the same as gettext except that the domain is specified explicitly along with the string to translate.

Now for an example of module internationalization, using the moon module.
NOTE THAT THIS IS JUST "Proof of concept" QUALITY, NOT THE FINAL VERSION

$ cd ~/src/moon/trunk
$ mkdir po
$ cp ~/src/e17/apps/e/po/Makefile.am po
$ vi Makefile.am

--- Makefile.am ( 31)
+++ Makefile.am (篏キ)
@@ -1,4 +1,4 @@
-SUBDIRS = src data
+SUBDIRS = src data po

$ vi configure.ac

--- configure.ac        ( 31)
+++ configure.ac        (篏キ)
@@ -18,6 +18,15 @@
fi
AC_PROG_LIBTOOL

+ALL_LINGUAS="ja"
+AC_SUBST(ALL_LINGUAS)
+
+AM_GNU_GETTEXT([external])
+AM_GNU_GETTEXT_VERSION(0.12.1)
+if test "x$LIBINTL" = "x"; then
+  LIBINTL="$INTLLIBS"
+fi
+
# Checks for libraries.
AC_PATH_GENERIC(eet, 0.9.10, [
AC_SUBST(eet_libs)
@@ -110,5 +119,6 @@
      data/Makefile
      data/themes/Makefile
      data/themes/images/Makefile
-                 src/Makefile])
+                 src/Makefile
+                po/Makefile])
AC_OUTPUT

$ vi autogen.sh
--- autogen.sh  ( 31)
+++ autogen.sh  (篏キ)
@@ -11,6 +11,22 @@
echo "Running libtoolize..." ; (libtoolize --copy --automake || glibtoolize --automake) || exit 1
echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1

+echo "Generating gettext moon.pot template";
+xgettext +--output moon.pot +--output-dir=po +--language=C +--add-location +--keyword=d_ +--indent +--sort-by-file +--copyright-holder="Your N. Here" +--foreign-user +`find . -name "*.[ch]" -print` || exit 1
+
if [ -z "$NOCONFIGURE" ]; then
./configure "$@"
fi

$ vi src/e_mod_main.c

--- src/e_mod_main.c    ( 31)
+++ src/e_mod_main.c    (篏キ)
@@ -43,9 +43,12 @@
{
Moon *moon;

+   bindtextdomain(PACKAGE, "/home//.e/e/modules/share/locale");
+   bind_textdomain_codeset(PACKAGE, "UTF-8");

moon = _moon_new(module);


@@ -89,8 +92,8 @@
/*
* FIXME - need to gettextise this properly
*/
-   e_module_dialog_show("Moon Clock Module",
-                        "Display current phase of the moon ala e16 E-MoonClock");
+   e_module_dialog_show(d_("Moon Clock Module", ""),
+                        d_("Display current phase of the moon ala e16 E-MoonClock", ""));
return 1;
}


$ cp ~/src/e17/apps/e/ABOUT-NLS .
$ ./autogen.sh
$ cp po/moon.pot po/ja.po
$ vi po/ja.po

--- po/moon.pot 2005-11-26 17:47:09.903525000 +0900
+++ po/ja.po    2005-11-26 17:54:37.469484632 +0900
@@ -11,16 +11,16 @@
"Last-Translator: FULL NAME <email address="">\n"
"Language-Team: LANGUAGE <ll org="">\n"
"MIME-Version: 1.0\n"
-       "Content-Type: text/plain; charset=CHARSET\n"
+       "Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: src/e_mod_main.c:95
msgid  "Moon Clock Module"
-msgstr ""
+msgstr "月の相モジュール"

#: src/e_mod_main.c:96
msgid  "Display current phase of the moon ala e16 E-MoonClock"
-msgstr ""
+msgstr "e16のE-MoonClockのように月の満ち欠け状態を表示します"


$ make
...
$ make install
$ enlightenment_remote -module-load moon
$ enlightenment_remote -module-enable moon

And now if we pull up the About menu for the module...

Labels: enlightenment