User:Santhosh.thottingal/jQuery i18n Spec

From mediawiki.org

jQuery i18n framework. Draft Specification.[edit]

(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[edit]

  • 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
  • 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.

Eg: { "en" : { key1 : "message1" .. } It is also possible to mention a reference to other file here: eg: { "ml" : "i18n/myApp-ml.js" }

Message File Loading[edit]

  • 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: <link rel="localization" hreflang="en" href="i18n/demo-en.json" type="application/l10n+json"/> or <link rel="localization" hreflang="ml" href="i18n/demo-ml.json" type="application/l10n+json"/>
  • or, if the locale file contains all messages for all locales: <link rel="localizations" href="i18n/demo-en.json" type="application/l10n+json"/>
  • 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[edit]

  • 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[edit]

  • Localized text for current locale is available by using the api $.i18n. Some examples
$.i18n( 'message-key-sample1' )
$._( 'message-key-sample1' )
$._( 'Found $1 {{plural:$1|result|results}}', 10 ) // Message key itself is message text
$._( 'Showing $1 out of $2 {{plural:$2|result|results}}', 5,100 )
$.i18n(' User X updated {{gender|his|her}} profile' , 'male')

Data API[edit]

  • 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 <li data-i18n="message-key" ></li>
  • 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[edit]

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[edit]

  • Message parser should support place holder replacement using $n format
  • Plural support should be implemented.Eg: {{plural:...}}
  • Gender support should be implemented. Eg: {{GENDER:..}}

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[edit]

  • 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[edit]

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

Fallback[edit]

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[edit]

Demo implementation[edit]

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

Retrieved from "https://www.mediawiki.org/w/index.php?title=User:Santhosh.thottingal/jQuery_i18n_Spec&oldid=4173380"