jQuery.i18n

[![npm][npm]][npm-url]

NOTE: For jquery independent version of this library, see https://github.com/wikimedia/banana-i18n

jQuery.i18n is a jQuery based JavaScript internationalization library. It helps you to internationalize your web applications easily.

This is a project by Wikimedia foundation's Language Engineering team and used in some of the Wikimedia Foundation projects like Universal Language Selector.

The jquery.i18n library uses a json based localization file format, "banana", which is used as the localization file format for MediaWiki and other projects.

Features

• Simple file format - JSON. Easily readable for humans and machines.
• Author and metadata information is not lost anywhere. There are other file formats using comments to store this.
• Uses MediaWiki convention for placeholders. Easily readable and proven convention. Example: There are $1 cars
• Supports plural conversion without using extra messages for all plural forms. Plural rule handling is done using CLDR. Covers a wide range of languages
• Supports gender. By passing the gender value, you get correct sentences according to gender.
• Supports grammar forms. jquery.i18n has a basic but extensible grammar conversion support
• Fallback chains for all languages.
• Data api- the message key. Example: <li data-i18n="message-key"></li>.
• Dynamic change of interface language without refreshing a webpage.
• Nestable grammar, plural, gender support. These constructs can be nested to any arbitrary level for supporting sophisticated message localization
• Message documentation through special language code qqq
• Extensible message parser to add or customize magic words in the messages. Example: {sitename} or [[link]]

Quick start

git clone https://github.com/wikimedia/jquery.i18n.git
cd jquery.i18n
git submodule update --init

Testing

npm install

To run tests locally, run npm test, and this will run the tests.

Running demo

# If you're using python3, open demo as a local server using port 8000
python -m http.server
# If you're using python2, use this command instead
# python -m SimpleHTTPServer  

Open localhost:8000/demo in your browser, you can see the demo index page.

Message File Format

The message files are json formatted. As a convention, you can have a folder named i18n inside your source code. For each language or locale, have a file named like languagecode.json.

Example:

App
	|--src
	|--doc
	|--i18n
		|--ar.json
		|--de.json
		|--en.json
		|--he.json
		|--hi.json
		|--fr.json
		|--qqq.json

A simple en.json file example is given below

{
	"@metadata": {
		"authors": [
			"Alice",
			"David",
			"Santhosh"
		],
		"last-updated": "2012-09-21",
		"locale": "en",
		"message-documentation": "qqq",
		"AnotherMetadata": "AnotherMedatadataValue"
	},
	"appname-title": "Example Application",
	"appname-sub-title": "An example application with jquery.i18n",
	"appname-header-introduction": "Introduction",
	"appname-about": "About this application",
	"appname-footer": "Footer text"
}

The json file should be a valid json. The @metadata holds all kind of data that are not messages. You can store author information, copyright, updated date or anything there.

Messages are key-value pairs. It is a good convention to prefix your appname to message keys to make the messages unique. It acts as the namespace for the message keys. It is also a good convention to have the message keys with - separated words, all in lower case.

If you are curious to see some real jquery.i18n message file from other projects:

• message files of MediaWiki https://github.com/wikimedia/mediawiki/tree/master/languages/i18n
• message files from jquery.uls project https://github.com/wikimedia/jquery.uls/tree/master/i18n

Single message file for all languages

There are some alternate message file formats supported for different use cases. If your application is not big, and want all the translation in a single file, you can have it as shown in the below example:

{
	"@metadata": {
		"authors": [
			"Alice",
			"David",
			"Santhosh"
		],
		"last-updated": "2012-09-21",
		"locale": "en",
		"message-documentation": "qqq",
		"AnotherMetadata": "AnotherMedatadataValue"
	},
	"en": {
		"appname-title": "Example Application",
		"appname-sub-title": "An example application with jquery.i18n",
		"appname-header-introduction": "Introduction",
		"appname-about": "About this application",
		"appname-footer": "Footer text"
		},
	"ml": {
		"appname-title": "അപ്ലിക്കേഷന്‍ ഉദാഹരണം",
		"appname-sub-title": "jquery.i18n ഉപയോഗിച്ചുള്ള അപ്ലിക്കേഷന്‍ ഉദാഹരണം",
		"appname-header-introduction": "ആമുഖം",
		"appname-about": "ഈ അപ്ലിക്കേഷനെപ്പറ്റി",
		"appname-footer": "അടിക്കുറിപ്പു്"
	}
}

Here the json file contains language code as key-value and messagekey-message pairs as the value for all language pairs. You can choose this format or per-language file formats depending on your use case. Per-language files are more convenient for collaboration, version controlling, scalability, etc.

In this approach, it is also possible to give a file name as the value of language code.

{
	"@metadata": {
		"authors": [
			"Alice",
			"David",
			"Santhosh"
		],
		"last-updated": "2012-09-21",
		"locale": "en",
		"message-documentation": "qqq",
		"AnotherMetadata": "AnotherMedatadataValue"
	},
	"en": {
		"appname-title": "Example Application",
		"appname-sub-title": "An example application with jquery.i18n",
		"appname-header-introduction": "Introduction",
		"appname-about": "About this application",
		"appname-footer": "Footer text"
		},
	"ml": "path/to/ml.json"
}

Translation

To translate the jquery.i18n application, depending on the expertise of the translator, there are multiple ways.

• Editing the json files directly - Suitable for translators with technical background. Also suitable if your application is small and you want to work with only a small number of languages
• Providing a translation interface along with your application: Suitable for proprietary or private applications with significant amount of translators
• Using open source translation platforms like translatewiki.net. The MediaWiki and jquery.uls from previous examples use translatewiki.net for crowdsourced message translation. Translatewiki.net can update your code repo at regular intervals with updated translations. Highly recommended if your application is opensource and want it to be localized to as many as languages possible with maximum number of translators.

Usage

Switching locale

While initializing the jquery.i18n, the locale for the page can be given using the locale option. For example

$.i18n( {
    locale: 'he' // Locale is Hebrew
} );

In case locale option is not given, jquery.i18n plugin will use the language attribute given for the html tag. For example

<html lang="he" dir="rtl">

In this case, the locale will be he(Hebrew). If that lang attribute is also missing, it will try to use the locale specified by the browser.

It is possible to switch to another locale after plugin is initialized. See below example:

$.i18n({
    locale: 'he' // Locale is Hebrew
});
$.i18n( 'message-hello' ); // This will give the Hebrew translation of message key `message-hello`.
$.i18n().locale = 'ml'; // Now onwards locale is 'Malayalam'
$.i18n( 'message-hello' ); // This will give the Malayalam translation of message key `message-hello`.

Message Loading

JSON formatted messages can be loaded to the plugin using multiple ways.

Dynamic loading using load method.

Following example shows loading messages for two locales- localex, and localey. Here localex and localey are just examples. They should be valid IS0 639 language codes(eg: en, ml, hi, fr, ta etc)

$.i18n().load( {
	'localex' : {
		'message-key1' : 'message1' // Message for localex.
	},
	'localey' : {
		'message-key1' : 'message1'
	}
} );

If we want to load the messages for a specific locale, it can be done like this:

$.i18n().load({
    'message-hello': 'Hello World',
    'message-welcome': 'Welcome'
}, 'en');

Note the second argument for the load method. It should be a valid language code.

It is also possible to refer messages from an external URL. See below example

$.i18n().load( {
	en: {
		'message-hello': 'Hello World',
		'message-welcome': 'Welcome'
	},
	hi: 'i18n/messages-hi.json', // Messages for Hindi
	de: 'i18n/messages-de.json'
} );

Messages for a locale can be also loaded in parts. Example

$.i18n().load( {
	en: {
		'message-hello': 'Hello World',
		'message-welcome': 'Welcome'
	}
} );

$.i18n().load( {
    	// This does not remove the previous messages.
	en: {
		'message-header' : 'Header',
		'message-footer' : 'Footer',
		// This will overwrite message-welcome message
		'message-welcome' : 'Welcome back'
	}
} );

Since it is desirable to render interface messages instantly and not after a delay of loading the message files from a server, make sure that the messages are present at client side before using jQuery.i18n.

The library should expose an API to load an object containing key-value pair of messages. Example: $.i18n.load(data). This will return a jQuery.Promise.

jquery.i18n plugin

The jQuery plugin defines $.i18n() and $.fn.i18n()

$.i18n( 'message-key-sample1' );
$.i18n( 'message-key-sample1' );
$.i18n( 'Found $1 {{plural:$1|result|results}}', 10 ); // Message key itself is message text
$.i18n( 'Showing $1 out of $2 {{plural:$2|result|results}}', 5,100 );
$.i18n( 'User X updated {{gender|his|her}} profile', 'male'