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

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:

Two kind of parser will be provided by the framework
 * Simple Message Parser - This can do only place holder replacement. Suitable for applications which does not provide plural, gender, grammar support.
 * Advanced Message Parser - This parser can handle placeholder replacement, gender, plural, grammar etc.

Applications using jquery.i18n library can extend and override these parsers to meet their requirements.

Plural, Gender, Grammar support

 * For plural, gender and grammar support, mediawiki like template syntax  -  will be used.
 * There will be a default implementation for all these in $.i18n.language['default']
 * The plural, gender, grammar methods in $.i18n.language['default'] can be overridden or extended in  $.i18n.language['languageCode']
 * language specific rules about Gender, Grammar can be written in languages/langXYZ. js files
 * Plural forms will be dynamically calculated using CLDR plural parser

Plugin files

 * jquery.i18n.js
 * jquery.i18n.parser.js
 * jquery.i18n.language.js
 * jquery.i18n.CLDRPluralParser
 * languages
 * ar.js
 * hi.js

Fallback
The plugin takes an option 'fallback' with default value 'en' ( To be considered: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4 An example        Accept-Language: da, en-gb;q=0.8, en;q=0.7 )

Existing noteworthy attempts

 * https://github.com/jquery/globalize jQuery UI localize project - in development, mainly focus on locale(or culture) definition for a language.
 * 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/