Internationalization and localization with webapp2

In this tutorial we will learn how to get started with webapp2_extras.i18n. This module provides a complete collection of tools to localize and internationalize apps. Using it you can create applications adapted for different locales and timezones and with internationalized date, time, numbers, currencies and more.


If you don’t have a package installer in your system yet (like pip or easy_install), install one. See Installing packages.

Get Babel and Pytz

The i18n module depends on two libraries: babel and pytz (or gaepytz). So before we start you must add the babel and pytz packages to your application directory (for App Engine) or install it in your virtual environment (for other servers).

For App Engine, download babel and pytz and add those libraries to your app directory:

For other servers, install those libraries in your system using pip. App Engine users also need babel installed, as we use the command line utility provided py it to extract and update message catalogs. This assumes a *nix environment:

$ sudo pip install babel
$ sudo pip install gaepytz

Or, if you don’t have pip but have easy_install:

$ sudo easy_install babel
$ sudo easy_install gaepytz

Create a directory for translations

We need a directory inside our app to store a messages catalog extracted from templates and Python files. Create a directory named locale for this.

If you want, later you can rename this directory the way you prefer and adapt the commands we describe below accordingly. If you do so, you must change the default i18n configuration to point to the right directory. The configuration is passed when you create an application, like this:

config = {}
config['webapp2_extras.i18n'] = {
    'translations_path': 'path/to/my/locale/directory',

app = webapp2.WSGIApplication(config=config)

If you use the default locale directory name, no configuration is needed.

Create a simple app to be translated

For the purposes of this tutorial we will create a very simple app with a single message to be translated. So create a new app and save this as

import webapp2

from webapp2_extras import i18n

class HelloWorldHandler(webapp2.RequestHandler):
    def get(self):
        # Set the requested locale.
        locale = self.request.GET.get('locale', 'en_US')

        message = i18n.gettext('Hello, world!')

app = webapp2.WSGIApplication([
    ('/', HelloWorldHandler),
], debug=True)

def main():

if __name__ == '__main__':

Any string that should be localized in your code and templates must be wrapped by the function webapp2_extras.i18n.gettext() (or the shortcut _()).

Translated strings defined in module globals or class definitions should use webapp2_extras.i18n.lazy_gettext() instead, because we want translations to be dynamic – if we call gettext() when the module is imported we’ll set the value to a static translation for a given locale, and this is not what we want. lazy_gettext() solves this making the translation to be evaluated lazily, only when the string is used.

Extract and compile translations

We use the babel command line interface to extract, initialize, compile and update translations. Refer to Babel’s manual for a complete description of the command options.

The extract command can extract not only messages from several template engines but also gettext() (from gettext) and its variants from Python files. Access your project directory using the command line and follow this quick how-to:

1. Extract all translations. We pass the current app directory to be scanned. This will create a messages.pot file in the locale directory with all translatable strings that were found:

$ pybabel extract -o ./locale/messages.pot ./

You can also provide a extraction mapping file that configures how messages are extracted. If the configuration file is saved as babel.cfg, we point to it when extracting the messages:

$ pybabel extract -F ./babel.cfg -o ./locale/messages.pot ./

2. Initialize the directory for each locale that your app will support. This is done only once per locale. It will use the messages.pot file created on step 1. Here we initialize three translations, en_US, es_ES and pt_BR:

$ pybabel init -l en_US -d ./locale -i ./locale/messages.pot
$ pybabel init -l es_ES -d ./locale -i ./locale/messages.pot
$ pybabel init -l pt_BR -d ./locale -i ./locale/messages.pot

3. Now the translation catalogs are created in the locale directory. Open each .po file and translate it. For the example above, we have only one message to translate: our Hello, world!.

Open /locale/es_ES/LC_MESSAGES/messages.po and translate it to ¡Hola, mundo!.

Open /locale/pt_BR/LC_MESSAGES/messages.po and translate it to Olá, mundo!.

4. After all locales are translated, compile them with this command:

$ pybabel compile -f -d ./locale

That’s it.

Update translations

When translations change, first repeat step 1 above. It will create a new .pot file with updated messages. Then update each locales:

$ pybabel update -l en_US -d ./locale/ -i ./locale/messages.pot
$ pybabel update -l es_ES -d ./locale/ -i ./locale/messages.pot
$ pybabel update -l pt_BR -d ./locale/ -i ./locale/messages.pot

After you translate the new strings to each language, repeat step 4, compiling the translations again.

Test your app

Start the development server pointing to the application you created for this tutorial and access the default language:

Then try the Spanish version:

And finally, try the Portuguese version:

Voilà! Our tiny app is now available in three languages.

What else

The webapp2_extras.i18n module provides several other functionalities besides localization. You can use it to internationalize dates, currencies and numbers, and there are helpers to set the locale or timezone automatically for each request. Explore the API documentation to learn more.