User:Santhosh.thottingal/jQuery i18n Spec

Jump to navigation Jump to search

jQuery i18n framework. Draft Specification.[edit]

(mainly by Santhosh Thottingal, Wikimedia Foundation Localisation team)

Implementation of this spec is available at

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


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


The plugin takes an option 'fallback' with default value 'en' ( To be considered: 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: