User:Santhosh.thottingal/jQuery i18n Spec
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]- 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
[edit]Very early prototype of course: http://thottingal.in/projects/js/jquery.i18n/demo/