User:Santhosh.thottingal/jQuery i18n Spec

jQuery i18n framework. Draft Specification.
(mainly by Santhosh Thottingal, Wikimedia Foundation Localisation team)

'''Implementation of this spec is available at https://github.com/santhoshtr/jquery.i18n

Note that this spec is not finalized and we are working on improving it'''

Message File Format

 * The message file format should be JSON files.
 * File name extension can be json or js
 * File names should be in the format of [prefix]-[localename]. For example following are valid file names:
 * myApp-en_US.js
 * myApp-en.json
 * myApp-ml.js

Eg: { "en" : { key1 : "message1" .. } It is also possible to mention a reference to other file here: eg: { "ml" : "i18n/myApp-ml.js" }
 * Messages are in key-value format in JSON.
 * Messages per locale can be placed in seperate locale files. Or all messages for all locales can be placed in a single message file. If it is single file, it is again locale: messages format.

Message File Loading

 * The default locale file(generally en locale) should be explicitly loaded along with jquery.i18n.js
 * The message files should be loaded using link tags. Eg:  or  
 * or, if the locale file contains all messages for all locales: 
 * link tags can be placed in the head of html, but it is not mandatory.
 * Other than link tag based message loading, the library should expose an API to load an object containing key value pair of messages. Eg: $.i18n.load(data)
 * Even if there are link tags for many languaes, it will not be loaded unless required
 * Message file loading is an ajax call (asynchronous)

jQuery Plugin

 * The jQuery plugin should be defined as jQuery extension $.i18n.
 * The same plugin will be available with the alias: $._
 * Developers can even use shorthand _=$.i18n (or anything they prefer) in their application scope.
 * The whole message map should be singleton and should be accessible for direct read and write by $.i18n.messages
 * The plugin instance will be a class I18N and will be attached to body of page.
 * There will be a jQuery function $.fn.i18n exposed. Usage explained below.

API

 * Localized text for current locale is available by using the api $.i18n. Some examples
 * $.i18n( 'message-key-sample1' )
 * $._( 'message-key-sample1' )
 * $._( 'Found $1 results', 10 ) # Message key itself is message text
 * $._( 'Showing $1 out of $2 results', 5,100 )


 * TODO: plural, gender syntax (considering adapting MediaWiki's JavaScript syntax here).

Data API

 * It is possible to display localized messages without any custom javascript. For the html tags, add an attribute data-i18n with value as the message key.For example 
 * Namespaces should be prefixed, to avoid key conflicts with other modules.
 * It is also possible to have the above li node with fallback text already in place. Fallback text
 * The framework will place the localized message corresponding to message-key as the text value of the node. Similar to $('selector').i18n(...)
 * This will not work for dynamically created elements

ECMA Standard
String.toLocaleString ( http://www.w3schools.com/jsref/jsref_tolocalestring.asp ) will be modified so that it returns the localized message using the framework. Provided the message key is existed in loaded translations.

Message Parser

 * Message parser should support place holder replacement using $n format
 * Plural support should be implemented.Eg: NaN undefineds
 * Gender support should be implemented. Eg:

Fallback
- Example: zh_TW -> zh_Hant -> en

Existing noteworthy attempts

 * http://www.ab-weblog.com/en/internationalization-how-to-localize-html5-projects/
 * https://github.com/eligrey/l10n.js/ ( The above spec borrows many ideas from this )

Demo implementation
Very early prototype of course: http://thottingal.in/projects/js/jquery.i18n/demo/