.comment-link {margin-left:.6em;}

David @ Tokyo

Perspective from Japan on whaling and whale meat, a spot of gourmet news, and monthly updates of whale meat stockpile statistics



E17: Module Internationalization

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?"));
_("You requested to exit Enlightenment.<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.
$ 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 @@

+if test "x$LIBINTL" = "x"; then
# Checks for libraries.
AC_PATH_GENERIC(eet, 0.9.10, [
@@ -110,5 +119,6 @@
- src/Makefile])
+ src/Makefile
+ po/Makefile])

$ 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 "$@"

$ 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...


Comments: Post a Comment

<< Home


June 2004   July 2004   August 2004   September 2004   October 2004   November 2004   December 2004   January 2005   March 2005   April 2005   May 2005   June 2005   July 2005   August 2005   September 2005   October 2005   November 2005   December 2005   January 2006   February 2006   March 2006   April 2006   May 2006   June 2006   July 2006   August 2006   September 2006   October 2006   November 2006   December 2006   January 2007   February 2007   March 2007   April 2007   May 2007   June 2007   July 2007   August 2007   September 2007   October 2007   November 2007   December 2007   January 2008   February 2008   April 2008   May 2008   June 2008   July 2008   August 2008   September 2008   October 2008   November 2008   December 2008   January 2009   February 2009   March 2009   April 2009   May 2009   June 2009   July 2009   August 2009   September 2009   October 2009   November 2009   January 2010   February 2010   April 2010   May 2010   June 2010   July 2010   August 2010   September 2010   February 2011   March 2011   May 2013   June 2013  

This page is powered by Blogger. Isn't yours?