bag.web.transecma module

Transecma is a Python solution for javascript internationalization.

It was written in 2012 by Nando Florestan.

Babel already has a javascript extractor (a function that goes through javascript code finding translation strings and writing them to a .POT translation template file).

In this module there is a jquery template extractor, so if you use jquery templates, they can be internationalized using traditional gettext tools.

The .pot file can be converted to .po files using Babel or GNU gettext. Each of these .po files is to contain a translation to one language. These .po files are edited by translators in special utilities such as poedit or gtranslator.

This module also contains po2json, a command that converts .po translation files into javascript files, so the translation may finally happen on the client, in a browser, through javascript code.

The final part of the solution is transecma.js, a javascript file that contains functions to perform translations based on the translation dictionary discussed above, as well as interpolate them with values from your application.

So how do I set this up?

In your javascript files and jquery template files, mark some strings for internationalization:

alert(_("This is supposed to be translated."));
// You may use tr() and gettext() in addition to _().

Install bag and Babel:

easy_install -UZ bag Babel

In the locale/ directory of your web application, add a “js_mapping.conf” file with contents like these:

[javascript: **.js]
[jquery_templates: **.tmpl.html]

The above tells Babel what extractor to use for what file extensions. Now we start using pybabel according to

Refer to the above documentation in order to understand the following commands.

First use pybabel extract to generate a js.pot translation template file:

pybabel extract -k tr --omit-header --sort-by-file
-F app/locale/js_mapping.conf -o app/locale/js.pot app/static/js/

(If you are using Pyramid, this is similar to extract_messages, however it focuses on javascript and creates a separate .pot file.)

Now and then you may create a new translation. Example for Portuguese:

pybabel init -l pt -D js -i app/locale/js.pot -d app/locale/

You will frequently use pybabel update to refresh the translations based on new .pot contents:

pybabel update -D js -i app/locale/js.pot -d app/locale/

(This is similar to update_catalog.)

Now you can use tools such as gtranslator or poedit to fill in the .po translation files:

gtranslator app/locale/pt/LC_MESSAGES/js.po

Finally use the po2json command (available if you installed the bag package) to “compile” translations into .js files:

po2json -i -d app/locale -o app/static/js/i18n/

(This is similar to compile_catalog.)

Transecma does not help you with the problem of adding to your pages a <script> tag that loads the javascript file that contains the translations that correspond to your user’s locale. This problem depends on which web framework you are using, but it should be very easy to solve. Here is an example using Pyramid and Genshi:

<script py:if="not locale_code.startswith('en')" type='text/javascript'
<script py:if="locale_code.startswith('en')" type='text/javascript'

In the above example, we assume the default language of the application is English. So, for languages other than English, we load the corresponding translations file (which may include the transecma library). For English, we only load the library itself, otherwise we would miss its functions, especially interpol().

bag.web.transecma.compile_dir(dir, domain, out_dir, variable_name=None, use_fuzzy=None, encoding='utf8', include_lib=False)[source]

Given a dir, goes through all locale subdirectories in it, reads the .po translation files pertaining to domain, and then converts the translations to javascript files, which are written out to the directory out_dir and assigned to a variable_name.

If include_lib is True, the contents of transecma.js are appended to the end of each of the output files.


Test whether a path exists. Returns False for broken symbolic links.

bag.web.transecma.extract_jquery_templates(fileobj, keywords, comment_tags, options)[source]

Extract translation messages from query template files.

This is a plugin to Babel, written according to
  • fileobj – the file-like object the messages should be extracted from
  • keywords – a list of keywords (i.e. function names) that should be recognized as translation functions
  • comment_tags – a list of translator tags to search for and include in the results
  • options – a dictionary of additional options (optional)

an iterator over (lineno, funcname, message, comments) tuples

Return type:


bag.web.transecma.make_json(structure, variable_name=None, indent=1, **k)[source]

Converts something into a json string, optionally attributing the result to a variable.

It also escapes the forward slash, making the result suitable to be included in an HTML <script> tag.

bag.web.transecma.po2dict(stream, locale, use_fuzzy=False)[source]

Given a stream (a file-like object) and a locale, returns a dictionary of the message IDs and translation strings.

bag.web.transecma.po2json(po_path, locale, variable_name=None, use_fuzzy=None)[source]

Compiles one .po file into JSON and returns the resulting string.


This function is an entry point; it is turned into a console script when the package is installed.

po2json is a command that converts .PO translation files into javascript JSON files. This is a step in web application internationalization.

Example usage:

po2json -i -d $OUTDIR -o $JS_DIR

For help with the arguments, type:

po2json -h