Editing Documentation/Maemo 5 Developer Guide/Application Development/Maemo Localization

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

= Maemo Localization =

== Overview ==

This section describes how to localize maemo applications. Localization is needed to provide native translations of the software. The section contains information on how to localize an application, how to ease extraction of message strings, how to make the translations, and how to test the localization.

Changes are presented with code examples to help the localization process. MaemoPad is used as an example here.

== Localization ==

Localization means translating the application to different languages. Maemo localization is based on the standard gettext package, and all the necessary tools are included in Scratchbox. For applications, localization requires a couple of files in the po/ directory. The following files will be used for localization:

Makefile.am
 en_GB.po
 fi_FI.po
 POTFILES.in

''POTFILES.in''  contains the list of source code files that will be localized. File ''en_GB.po''  includes translated text for target en_GB and file ''fi_FI.po''  for target fi_FI.

== Localizing Application ==

To localize an application, l10n needs to be set up before <code>gtk_init()</code> by including the following headers:

maemopad/src/main.c

#include <locale.h>
 #include <glib/gi18n.h>

To initialize the locale functions, the following lines need to be added:

maemopad/src/main.c

setlocale(LC_ALL, "");
 bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
 bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
 textdomain(GETTEXT_PACKAGE);

The most important of these are ''GETTEXT_PACKAGE''  and ''localedir'' , which come from configure.ac:

maemopad/configure.ac

AC_PROG_INTLTOOL([0.23])
 #PACKAGE=maemopad by default, defined by AM_INIT_AUTOMAKE
 GETTEXT_PACKAGE=$PACKAGE
 AC_SUBST(GETTEXT_PACKAGE)
 AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE], "${GETTEXT_PACKAGE}", [gettext pakname])
 ALL_LINGUAS="en_GB fi_FI"
 AM_GLIB_GNU_GETTEXT
 # Application locale install directory, /usr/share/locale by default
 localedir=`$PKG_CONFIG osso-af-settings -variable=localedir`

Of these, only GETTEXT_PACKAGE needs special attention, as it is the l10n domain that is to be used, and ALL_LINGUAS lists the available translations.

=== Easing Extraction of Strings ===

In the source code, there are multiple strings that eventually get shown in the user interface. For example:

maemopad_window_show_error ("maemopad_open_failed", self);

In order to make the strings localizable, they need to be wrapped in <code>gettext("String")</code> calls. In practice, writing <code>gettext()</code> for every string is tedious. The common practice is to set the following #define which is already done in included ''gi18n.h'':

#define _(String) gettext (String)

Thus, the i18n version of the example would be:

maemopad/src/main.c

maemopad_window_show_error (_("maemopad_open_failed"), self);

=== Creating Translation Files ===

Creating *.po files is quite straightforward. Maemopad has two localization files, ''en_GB.po'' and ''fi_FI.po''. Creating the Finnish translation is explained next. Localization .po files are filled with simple structures, defining the localization id and the actual text string, e.g.

#: src/maemopad-window.c:573 src/maemopad-window.c:580
 msgid "maemopad_open_failed"
 msgstr "Open failed!"

"msgid" defines the original string (key) used in code, and "msgstr" defines the translated string for localization.

First, a template file is created with all strings from sources for translation. GNU xgettext command is used to extract the strings from sources:
 
 [sbox-FREMANTLE_X86: ~/maemopad] &gt; xgettext -f po/POTFILES.in -C -a -o po/template.po

Option "-f po/POTFILES.in" uses POTFILES.in to get the files to be localized, "-C" is for C-code type of strings, "-a" is for ensuring that all the strings are received from sources, and "-o template.po" defines the output filename.

This may output some warnings. Usually they are not serious, but it is better to check them anyway.

If the translation in question is into Finnish, the edited ''po/template.po''  needs to be copied to ''po/fi_FI.po'' , and ''fi_FI.po''  needs to be added to ALL_LINGUAS in ''configure.ac''.

Now ''po/fi_FI.po''  will include lines such as the following:

#: src/maemopad-window.c:253
 msgid "maemopad_save_changes_made"
 msgstr "Save changes?"

All msgstrings should be translated into the desired language:

#: src/maemopad-window.c:253
 msgid "maemopad_save_changes_made"
 msgstr "Tallenna muutokset?"

Autotools should now automatically convert the .po file to .mo file during the build process, and install it to the correct location.

To do it manually:
 
 [sbox-FREMANTLE_X86: ~/maemopad] > msgfmt po/fi_FI.po -o debian/maemopad/usr/share/locale/fi_FI/LC_MESSAGES/maemopad.mo

Where "debian/maemopad/usr/share/locale/fi_FI/LC_MESSAGES/" is the directory where the software should be installed to.

== Testing ==

Inside scratchbox, the translated application should be tested by setting LC_ALL environment variable to contain the newly created locale (in this example case for Finnish translation, "fi_FI"):

[sbox-FREMANTLE_X86: ~] > LANGUAGE="fi_FI" run-standalone.sh maemopad

On the target device, a wrapper script is needed to accomplish this, if the device does not have a locale for the locale identifier used. The script can simply consist of:

#!/bin/sh
 LANGUAGE="fi_FI" /usr/bin/maemopad

The example above assumes that the installation package installs the executable into /usr/bin. This script needs then to be configured to be run in the application's .desktop file, instead of the actual executable.

[[Category:Development]]
[[Category:Documentation]]
[[Category:Fremantle]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Application_Development/Maemo_Localization"

Personal tools

Navigation

Views

Editing Documentation/Maemo 5 Developer Guide/Application Development/Maemo Localization

@@ Line 1: / Line 1: @@
-This section describes how to localize Maemo applications. Localization is needed to provide native translations of the software. The section contains information on how to localize an application, how to ease extraction of message strings, how to make the translations, and how to test the localization.
+= Maemo Localization =
-Changes are presented with code examples to help the localization process. [[Documentation/Maemo 5 Developer Guide/Porting Software/Porting MaemoPad|MaemoPad]] is used as an example here.
+== Overview ==
+This section describes how to localize maemo applications. Localization is needed to provide native translations of the software. The section contains information on how to localize an application, how to ease extraction of message strings, how to make the translations, and how to test the localization.
+Changes are presented with code examples to help the localization process. MaemoPad is used as an example here.
 == Localization ==
-Localization means translating the application to different languages. Maemo localization is based on the standard gettext package, and all the necessary tools are included in Scratchbox. For applications, localization requires a couple of files in the <code>po/</code> directory. The following files will be used for localization:
+Localization means translating the application to different languages. Maemo localization is based on the standard gettext package, and all the necessary tools are included in Scratchbox. For applications, localization requires a couple of files in the po/ directory. The following files will be used for localization:
+ Makefile.am
+ en_GB.po
+ fi_FI.po
+ POTFILES.in
-* Makefile.am
+''POTFILES.in''  contains the list of source code files that will be localized. File ''en_GB.po''  includes translated text for target en_GB and file ''fi_FI.po''  for target fi_FI.
-* en_GB.po
-** contains translated text for target en_GB
-* fi_FI.po
-** contains translated text for target fi_FI
-* POTFILES.in
-** contains the list of source code files that will be localized
 == Localizing Application ==
@@ Line 19: / Line 23: @@
 To localize an application, l10n needs to be set up before <code>gtk_init()</code> by including the following headers:
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemopad/src/main.c maemopad/src/main.c]
+maemopad/src/main.c
+ #include <locale.h>
+ #include <glib/gi18n.h>
-<source lang="c">
-#include <locale.h>
-#include <glib/gi18n.h>
-</source>
 To initialize the locale functions, the following lines need to be added:
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemopad/src/main.c maemopad/src/main.c]
+maemopad/src/main.c
-<source lang="c">
+ setlocale(LC_ALL, "");
-setlocale(LC_ALL, "");
+ bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
-bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
+ bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
-bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
+ textdomain(GETTEXT_PACKAGE);
-textdomain(GETTEXT_PACKAGE);
-</source>
-The most important of these are <code>GETTEXT_PACKAGE</code> and <code>localedir</code>, which come from <code>configure.ac</code>:
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemopad/src/configure.ac maemopad/configure.ac]
+The most important of these are ''GETTEXT_PACKAGE''  and ''localedir'' , which come from configure.ac:
-<source lang="autoconf">
+maemopad/configure.ac
-AC_PROG_INTLTOOL([0.23])
-#PACKAGE=maemopad by default, defined by AM_INIT_AUTOMAKE
-GETTEXT_PACKAGE=$PACKAGE
-AC_SUBST(GETTEXT_PACKAGE)
-AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE], "${GETTEXT_PACKAGE}", [gettext pakname])
-ALL_LINGUAS="en_GB fi_FI"
-AM_GLIB_GNU_GETTEXT
-# Application locale install directory, /usr/share/locale by default
-localedir=`$PKG_CONFIG osso-af-settings --variable=localedir`
-</source>
-Of these, only <code>GETTEXT_PACKAGE</code> needs special attention, as it is the l10n domain that is to be used, and <code>ALL_LINGUAS</code> lists the available translations.
+ AC_PROG_INTLTOOL([0.23])
+ #PACKAGE=maemopad by default, defined by AM_INIT_AUTOMAKE
+ GETTEXT_PACKAGE=$PACKAGE
+ AC_SUBST(GETTEXT_PACKAGE)
+ AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE], "${GETTEXT_PACKAGE}", [gettext pakname])
+ ALL_LINGUAS="en_GB fi_FI"
+ AM_GLIB_GNU_GETTEXT
+ # Application locale install directory, /usr/share/locale by default
+ localedir=`$PKG_CONFIG osso-af-settings -variable=localedir`
+Of these, only GETTEXT_PACKAGE needs special attention, as it is the l10n domain that is to be used, and ALL_LINGUAS lists the available translations.
 === Easing Extraction of Strings ===
@@ Line 59: / Line 59: @@
 In the source code, there are multiple strings that eventually get shown in the user interface. For example:
-<source lang="c">
+ maemopad_window_show_error ("maemopad_open_failed", self);
-maemopad_window_show_error ("maemopad_open_failed", self);
-</source>
-In order to make the strings localizable, they need to be wrapped in <code>gettext("String")</code> calls. In practice, writing <code>gettext()</code> for every string is tedious. The common practice is to set the following #define which is already done in included <code>gi18n.h</code>:
-<source lang="c">
+In order to make the strings localizable, they need to be wrapped in <code>gettext("String")</code> calls. In practice, writing <code>gettext()</code> for every string is tedious. The common practice is to set the following #define which is already done in included ''gi18n.h'':
-#define _(String) gettext (String)
-</source>
+ #define _(String) gettext (String)
 Thus, the i18n version of the example would be:
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemopad/src/main.c maemopad/src/main.c]
+maemopad/src/main.c
+ maemopad_window_show_error (_("maemopad_open_failed"), self);
-<source lang="c">
-maemopad_window_show_error (_("maemopad_open_failed"), self);
-</source>
 === Creating Translation Files ===
-Creating *.po files is quite straightforward. Maemopad has two localization files, <code>en_GB.po</code> and <code>fi_FI.po</code>. Creating the Finnish translation is explained next. Localization .po files are filled with simple structures, defining the localization id and the actual text string, e.g.
+Creating *.po files is quite straightforward. Maemopad has two localization files, ''en_GB.po'' and ''fi_FI.po''. Creating the Finnish translation is explained next. Localization .po files are filled with simple structures, defining the localization id and the actual text string, e.g.
   #: src/maemopad-window.c:573 src/maemopad-window.c:580
@@ Line 89: / Line 86: @@
 First, a template file is created with all strings from sources for translation. GNU xgettext command is used to extract the strings from sources:
-  [sbox-FREMANTLE_X86: ~/maemopad] > xgettext -f po/POTFILES.in -C -a -o po/template.po
+  [sbox-FREMANTLE_X86: ~/maemopad] &gt; xgettext -f po/POTFILES.in -C -a -o po/template.po
-Option "-f po/POTFILES.in" uses <code>POTFILES.in</code> to get the files to be localized, "-C" is for C-code type of strings, "-a" is for ensuring that all the strings are received from sources, and "-o template.po" defines the output filename.
+Option "-f po/POTFILES.in" uses POTFILES.in to get the files to be localized, "-C" is for C-code type of strings, "-a" is for ensuring that all the strings are received from sources, and "-o template.po" defines the output filename.
 This may output some warnings. Usually they are not serious, but it is better to check them anyway.
-If the translation in question is into Finnish, the edited <code>po/template.po</code> needs to be copied to <code>po/fi_FI.po</code> , and <code>fi_FI.po</code> needs to be added to <code>ALL_LINGUAS</code> in <code>configure.ac</code>.
+If the translation in question is into Finnish, the edited ''po/template.po''  needs to be copied to ''po/fi_FI.po'' , and ''fi_FI.po''  needs to be added to ALL_LINGUAS in ''configure.ac''.
-Now <code>po/fi_FI.po</code>  will include lines such as the following:
+Now ''po/fi_FI.po''  will include lines such as the following:
   #: src/maemopad-window.c:253
@@ Line 115: / Line 112: @@
   [sbox-FREMANTLE_X86: ~/maemopad] > msgfmt po/fi_FI.po -o debian/maemopad/usr/share/locale/fi_FI/LC_MESSAGES/maemopad.mo
-Where <code>debian/maemopad/usr/share/locale/fi_FI/LC_MESSAGES/</code> is the directory where the software should be installed to.
+Where "debian/maemopad/usr/share/locale/fi_FI/LC_MESSAGES/" is the directory where the software should be installed to.
 == Testing ==
-Inside scratchbox, the translated application should be tested by setting LANGUAGE environment variable to contain the newly created locale (in this example case for Finnish translation, <code>fi_FI</code>):
+Inside scratchbox, the translated application should be tested by setting LC_ALL environment variable to contain the newly created locale (in this example case for Finnish translation, "fi_FI"):
   [sbox-FREMANTLE_X86: ~] > LANGUAGE="fi_FI" run-standalone.sh maemopad
@@ Line 125: / Line 123: @@
 On the target device, a wrapper script is needed to accomplish this, if the device does not have a locale for the locale identifier used. The script can simply consist of:
-<source lang="bash">
+ #!/bin/sh
-#!/bin/sh
+ LANGUAGE="fi_FI" /usr/bin/maemopad
-LANGUAGE="fi_FI" /usr/bin/maemopad
-</source>
-The example above assumes that the installation package installs the executable into <code>/usr/bin</code>. This script needs then to be configured to be run in the application's .desktop file, instead of the actual executable.
+The example above assumes that the installation package installs the executable into /usr/bin. This script needs then to be configured to be run in the application's .desktop file, instead of the actual executable.
 [[Category:Development]]
 [[Category:Documentation]]
 [[Category:Fremantle]]