158 lines
5.0 KiB
Markdown
158 lines
5.0 KiB
Markdown
jQuery Universal Language Selector
|
|
==================================
|
|
Universal Language Selector
|
|
|
|
[](http://travis-ci.org/wikimedia/jquery.uls)
|
|
|
|
This is a [Wikimedia Foundation Internationalization team project](https://www.mediawiki.org/wiki/Project_Milkshake).
|
|
|
|
|
|
|
|
|
|
Quick start
|
|
-----------
|
|
|
|
```bash
|
|
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:
|
|
```javascript
|
|
$( '.uls-trigger' ).uls( );
|
|
```
|
|
|
|
To use the selected language, you need define a selection Handler as shown below
|
|
|
|
```javascript
|
|
$( '.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 langauges, language suggestions based on Geo IP.
|
|
That can be done as follows
|
|
|
|
```javascript
|
|
$( '.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.
|
|
|
|
```javascript
|
|
$( '.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.
|
|
|
|
|
|
```javascript
|
|
$( '.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.
|
|
} );
|
|
```
|
|
|
|
Features
|
|
--------
|
|
jQuery.uls has an elaborative langauge 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
|
|
|
|
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
|
|
|
|
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:
|
|
|
|
```shell
|
|
git clone git://github.com/wikimedia/jquery.uls.git
|
|
```
|
|
|
|
Make sure you have `grunt` installed by testing:
|
|
|
|
```shell
|
|
grunt -version
|
|
```
|
|
|
|
If not, run:
|
|
|
|
```shell
|
|
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](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
|
|
|
|
Versioning
|
|
----------
|
|
|
|
For transparency and insight into the release cycle, and to upgrading easier,
|
|
we use the Semantic Versioning guidelines as much as possible.
|
|
|
|
Releases will be numbered with the following format:
|
|
|
|
`<major>.<minor>.<patch>`
|
|
|
|
And constructed with the following guidelines:
|
|
|
|
* Breaking backward compatibility bumps the major (and resets the minor and patch)
|
|
* New additions without breaking backward compatibility bumps the minor (and resets the patch)
|
|
* Bug fixes and misc changes bumps the patch
|
|
|
|
For more information on SemVer, please visit http://semver.org/.
|