runt18 / jquery.uls

Universal Language Selector

jQuery Universal Language Selector

Universal Language Selector

This is a Wikimedia Foundation Language Engineering team project.

Quick start

git clone https://github.com/wikimedia/jquery.uls.git

Documentation

The quick and easy way to learn usage of jquery.uls is trying out the examples/index.html in some webserver. Try it from here: http://thottingal.in/projects/js/jquery.uls/examples/

The jQuery.uls provides a jQuery extension $.fn.uls that can be attached to a trigger element. The expected behavior is, when you click on the trigger, the language selector opens up.

The trigger can be a link, button or any valid jQuery element.

Example:

$( '.uls-trigger' ).uls( );

To use the selected language, you need define a selection Handler as shown below

$( '.uls-trigger' ).uls( {
  onSelect : function( language ) {
  // language is a ISO 639 language code. eg: en, hi, fi, he etc
  // Your selection handler code goes here.
  }
} );

In some usecases, you may need to provide a quick list of languages to select before going through all languages. For eg, it can a list of recently selected languages, language suggestions based on Geo IP. That can be done as follows

$( '.uls-trigger' ).uls( {
  onSelect : function( language ) {
  // language is a ISO 639 language code. eg: en, hi, fi, he etc
  // Your selection handler code goes here.
  },
  quickList: [ 'en', 'ml', 'hi' ] // An array of language codes. Can be a function that returns this array too.
} );

If the search needs to be more complex(such as cross language search, spelling error tolerating etc), a search API option can be provided.

$( '.uls-trigger' ).uls( {
  onSelect : function( language ) {
  // language is a ISO 639 language code. eg: en, hi, fi, he etc
  // Your selection handler code goes here.
  },
  searchAPI: apiURL,
  quickList: [ 'en', 'ml', 'hi' ] // An array of language codes. Can be a function that returns this array too.
} );

Example for such an api is used in Wikipedia: http://en.wikipedia.org/w/api.php?action=languagesearch&search=Te

ULS knows about 500 languages. If you dont want to use that many languages for your usecase, use languages option.

$( '.uls-trigger' ).uls( {
  onSelect : function( language ) {
  // language is a ISO 639 language code. eg: en, hi, fi, he etc
  // Your selection handler code goes here.
  },
  languages: { languageCode1: languageName, languageCode2: languageName2 , .... },
  searchAPI: apiURL,
  quickList: [ 'en', 'ml', 'hi' ] // An array of language codes. Can be a function that returns this array too.
} );

Other Options

Option	Description
left	left position of ULS. eg: 100px, 20%
top	top position of ULS. eg: 100px, 20%
onCancel	function to be handled when language selection is not done. ie. language selector is closed without selecting any
showRegions	Regions to be shown in the language selector. Default: ['WW', 'AM', 'EU', 'ME', 'AF', 'AS', 'PA']
itemsPerColumn	Number of languages per column. Default is 8
languageDecorator	Callback function to be called when a language link is prepared - for custom decoration. Arguments: (a) the $language - the language link jQuery object (b) languageCode. The function can do any styling, changing properties etc on the passed link. See examples/decorator.html for example usage.

Features

jQuery.uls has an elaborative language information collection. It knows about

1. The script in which a language is written.
2. The script code
3. The language code
4. The regions in which the language is spoken
5. The autonym - language name written in its own script
6. The directionality of the text

With all these information the search becomes very effective. Based on the spoken regions, the UI organize the languages. In side regions the language is again organized based on scripts.

A user can search for a language based on script name.

ULS can autocomplete a language name search.

An advanced usage of jQuery.uls can be tried out from wikimedia sites. For eg, see the language icon at the top of http://mediawiki.org or the cog icon near to the languages list in wikipedia in any language

More details

• Technical design - https://www.mediawiki.org/wiki/Universal_Language_Selector/Design
• UX Design https://www.mediawiki.org/wiki/Universal_Language_Selector/Design

How to build and test jQuery ULS

First, get a copy of the git repo by running:

git clone git://github.com/wikimedia/jquery.uls.git

Make sure you have grunt installed by testing:

grunt -version

If not, run:

npm install

To run tests locally, run grunt test. This will run the tests in PhantomJS.

You can also run the tests in a browser by navigating to the test/ directory, but first run grunt to install the submodules.

Coding style

Please follow jQuery coding guidelines