Editing Internationalize a Python application

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.

This page explains step by step how to add support for translations in a Python application for Maemo.

There are already some [http://www.learningpython.com/2006/12/03/translating-your-pythonpygtk-application/ tutorials online] about how to internationalize (i18n) Python applications, but I find them difficult to follow and they lack some needed code and final tricks to make everything work fine.

To support i18n we need to accomplish 5 tasks:
# Define correctly a function '<code>_()</code>' that translates strings
# Mark the strings in the code with that function
# Generate a template for the translators
# Add translations
# Include the translations in the installation

== The overall process ==

From the source code, using a command line tool, we will generate a "<code>.pot</code>" file. It is plain text file containing all strings that need translation in the project. This <code>.pot</code> file only needs to be generated/recreated when the strings change in the code (and ''not'' in every build!). There is only one <code>.pot</code> file per project.

Then, from the <code>.pot</code> files and using another command line tool, we will generate the <code>.po</code> files for each language. There is one <code>.po</code> file per language, and it is the file that the translators need to complete. Both <code>.pot</code> and all <code>.po</code> files should be committed in the repository.

But once your program is running, it doesn't use <code>.po</code> files directly, but a binary (compiled) version of them: the <code>.mo</code> files. These <code>.mo</code> files must be re-created on build time (when creating the package) and installed in the right location in the system. These are generated files, so don't commit them to the repository.

From the code point of view, you just need to call few functions to tell gettext where are the translation files, what language do you want to use (usually the locale of the environment), and then it will use its implementation to find the right string.

Ok, this is what we need to do. Let's code.

== Configure gettext Define the '_()' function ==

If you don't care too much about the details, just copy this [https://garage.maemo.org/plugins/ggit/browse.php/?p=mussorgsky;a=blob;f=src/i18n.py;hb=HEAD i18n.py] file in your src/ directory ('''change the APP_NAME''' variable there!), or copy the code block below into a file i18n.py:
<source lang="python">
# -*- coding: utf-8 -*-

import os, sys
import locale
import gettext

# Change this variable to your app name!
#  The translation files will be under
#  @LOCALE_DIR@/@LANGUAGE@/LC_MESSAGES/@APP_NAME@.mo
APP_NAME = "SleepAnalyser"

# This is ok for maemo. Not sure in a regular desktop:
#APP_DIR = os.path.join (sys.prefix, 'share')
LOCALE_DIR = os.path.join(APP_DIR, 'i18n') # .mo files will then be located in APP_Dir/i18n/LANGUAGECODE/LC_MESSAGES/

# Now we need to choose the language. We will provide a list, and gettext
# will use the first translation available in the list
#
#  In maemo it is in the LANG environment variable
#  (on desktop is usually LANGUAGES)
DEFAULT_LANGUAGES = os.environ.get('LANG', '').split(':')
DEFAULT_LANGUAGES += ['en_US']

lc, encoding = locale.getdefaultlocale()
if lc:
    languages = [lc]

# Concat all languages (env + default locale),
#  and here we have the languages and location of the translations
languages += DEFAULT_LANGUAGES
mo_location = LOCALE_DIR

# Lets tell those details to gettext
#  (nothing to change here for you)
gettext.install(True, localedir=None, unicode=1)

gettext.find(APP_NAME, mo_location)

gettext.textdomain (APP_NAME)

gettext.bind_textdomain_codeset(APP_NAME, "UTF-8")

language = gettext.translation(APP_NAME, mo_location, languages=languages, fallback=True)
</source>

And in '''every .py''' file that needs to translate any string, add these lines at the top:
<source lang="python">
import i18n
_ = i18n.language.ugettext #use ugettext instead of getttext to avoid unicode errors 
</source>
Done. If you are curious about what is going on there, the file has plenty of comments explaining every line.

== Mark strings for i18n ==

This is one of the easiest parts. Browse the source code files that show something on the screen, and wrap the visible strings (window titles, dialog titles, notifications, labels, button labels and so on) with the '<code>_()</code>' function.

For example:
<source lang="python">
# import the _() function!
import i18n
_ = i18n.language.gettext

class Example (hildon.StackableWindow):

def __init__ (self):
       hildon.StackableWindow.__init__ (self)
       self.set_title ( _("All music") )   <------- ADD THIS!
</source>
== How to add translations ==

Now you want to get a translation in an specific language. You need to generate a <code>.po</code> for it.

There are several ways to do it. I suggest to do it the easy way with poEdit:
=== With poEdit ===
Poedit is cross-platform gettext catalogs (.po files) editor. For more information, see its website http://www.poedit.net/.
Just start it and generate a new catalog from the generated .pot file.
In the option window you can select the translated language, your name, email address and so on. This is useful, so others know who created this translation.

Now you can start to translate all the text. If you modify your application and generate a new .pot file, you can easily import it. It will use all the existing translation and add the new/modified strings. If you changed the charset before like me, you will have to select it again.
Every time you save the file, poEdit will generate a .mo file. You can use it for testing the new translation.

=== Manual way ===
Go to the <code>po/</code> folder and run this command (again, inside/outside scratchbox doesn't matter):

msginit --input=PROJECTNAME.pot --locale=LOCALE

For instance, if I want a <code>.po</code> file for the Spanish translation of my project Mussorgsky, I write:

msginit --input=mussorgsky.pot --locale=es_ES

It will generate a file "<code>es.po</code>" and translators can/must work on that file.

'''IMPORTANT''': by default the generated <code>.po</code> file declares its charset as ASCII. This means that translations with non-ascii characters will provoke an error in the program. To solve this, set the charset to '<code>utf-8</code>':

"Language-Team: Spanish\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"  <--- THIS MUST BE UTF-8

If you don't know the locale of a language, can check [http://www.roseindia.net/tutorials/I18N/locales-list.shtml www.roseindia.net/tutorials/I18N/locales-list.shtml] or [http://people.w3.org/rishida/utils/subtags/ people.w3.org/rishida/utils/subtags].

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/Internationalize_a_Python_application"

Personal tools

Navigation

Views

Editing Internationalize a Python application

@@ Line 21: / Line 21: @@
 Ok, this is what we need to do. Let's code.
+== Configure gettext Define the '_()' function ==
+If you don't care too much about the details, just copy this [https://garage.maemo.org/plugins/ggit/browse.php/?p=mussorgsky;a=blob;f=src/i18n.py;hb=HEAD i18n.py] file in your src/ directory ('''change the APP_NAME''' variable there!), or copy the code block below into a file i18n.py:
+<source lang="python">
+# -*- coding: utf-8 -*-
+import os, sys
+import locale
+import gettext
+# Change this variable to your app name!
+#  The translation files will be under
+#  @LOCALE_DIR@/@LANGUAGE@/LC_MESSAGES/@APP_NAME@.mo
+APP_NAME = "SleepAnalyser"
+# This is ok for maemo. Not sure in a regular desktop:
+#APP_DIR = os.path.join (sys.prefix, 'share')
+LOCALE_DIR = os.path.join(APP_DIR, 'i18n') # .mo files will then be located in APP_Dir/i18n/LANGUAGECODE/LC_MESSAGES/
+# Now we need to choose the language. We will provide a list, and gettext
+# will use the first translation available in the list
+#
+#  In maemo it is in the LANG environment variable
+#  (on desktop is usually LANGUAGES)
+DEFAULT_LANGUAGES = os.environ.get('LANG', '').split(':')
+DEFAULT_LANGUAGES += ['en_US']
+lc, encoding = locale.getdefaultlocale()
+if lc:
+    languages = [lc]
+# Concat all languages (env + default locale),
+#  and here we have the languages and location of the translations
+languages += DEFAULT_LANGUAGES
+mo_location = LOCALE_DIR
+# Lets tell those details to gettext
+#  (nothing to change here for you)
+gettext.install(True, localedir=None, unicode=1)
+gettext.find(APP_NAME, mo_location)
+gettext.textdomain (APP_NAME)
+gettext.bind_textdomain_codeset(APP_NAME, "UTF-8")
+language = gettext.translation(APP_NAME, mo_location, languages=languages, fallback=True)
+</source>
+And in '''every .py''' file that needs to translate any string, add these lines at the top:
+<source lang="python">
+import i18n
+_ = i18n.language.ugettext #use ugettext instead of getttext to avoid unicode errors
+</source>
+Done. If you are curious about what is going on there, the file has plenty of comments explaining every line.
 == Mark strings for i18n ==