Internationisation tutorial

From MapbenderWiki

This is a tutorial for Mapbender 2.7 and newer (note: this equals trunk at the moment, November 2009).

Contents 1 Requirements 2 Objective 3 Preface 4 Your script 4.1 Define translatable content 4.2 Use translatable content 4.3 Translation 4.4 Updating your content 4.5 Real life example

Requirements

This tutorials build upon "How to Write a Mapbender module". Make sure to have read it.

Objective

Enhance a Mapbender module so its content is internationalized automatically when the locale is switched.

Preface

Make sure the module i18n is in your application. This SQL adds it to all your applications

INSERT INTO gui_element(fkey_gui_id, e_id, e_pos, e_public, e_comment, e_title, e_element, e_src, e_attributes, e_more_styles, e_content, e_closetag, e_js_file, e_mb_mod, e_target, e_requires, e_url) SELECT DISTINCT fkey_gui_id,'i18n',1,1,'Internationalization module, collects data from all elements and sends them to the server in a single POST request. The strings are translated via gettext only.','Internationalization','div','','','','','div','../plugins/mb_i18n.js','','','','http://www.mapbender.org/Gettext' FROM gui_element WHERE gui_element.fkey_gui_id NOT IN (SELECT fkey_gui_id FROM gui_element WHERE e_id = 'i18n');

This module collects content from other modules, and only performs a single AJAX request to retrieve the translations from the server side. In Mapbender 2.6, each module handled i18n individually.

Note: This module only handles gettext translations! 

      There is no solution for database solutions. 
      However, database translations are somehow deprecated.

Your script

Define translatable content

The simple way is to have two objects, one containing the default content, the other the translated content. The first serves as the key for translations, the second is used when actually displaying content.

These objects could look like this. Here's the default object

var originalI18nObject = {
   "labelNewOrOverwrite": "New \/ overwrite",
   "labelNewWmc": "(new WMC)",
   "labelName": "Name",
   "labelAbstract": "Abstract",
   "labelKeywords": "Keywords",
   "labelCategories": "Categories",
   "labelCancel": "Abort",
   "labelSave": "Save",
   "title": "Save workspace as web map context document"
};

the translated object is just a clone

var translatedI18nObject = Mapbender.cloneObject(originalI18nObject);

Use translatable content

You should avoid hard-wired content at all cost. All content should be added dynamically, for example via jQuery. Here's an example, remember we use the translated content here

var selectHtml = "<option>" + translatedI18nObject.labelNewWmc + "</option>";
.
. //  more markup
.

$(selector).html(selectHtml)

Translation

You have to register this object with the queue API method of the i18n module. There are three parameters

• module ID
• default content object
• callback function

Generally, options.id containes the current module ID. Here's a template

Mapbender.events.localize.register(function () {
	Mapbender.modules.i18n.queue(options.id, originalI18nObject, function (translatedObject) {
		if (typeof translatedObject !== "object") {
			return;
		}
		translatedI18nObject = translatedObject;
		try {
			//
			// Your code
			//
		}
		catch (exc) {
			new Mb_warning("Error when translating: " . exc.message);
		}
	});
});

Updating your content

You see that translatedI18nObj gets updated with the object coming from the i18n module. You can use it in the callback function to update your content. Here's an example what could be done in the your code segment

$(selector1).text(translatedI18nObject.labelCategories);
$(selector2).text(translatedI18nObject.labelKeywords);
.
. 
.

Real life example

This example has been compiled using the module savewmc. Take a look at the source code if you want to learn more.