This is the technical design document of Universal Language Selector. It explains the structure of both jQuery.uls and how it is used by the MediaWiki Universal Language Selector extension.
jQuery extension function $.fn.uls is used for adding ULS to a trigger. A trigger is an html element – it can be a link, button, image or theoretically anything. On click of that element ULS will be shown.
On binding ULS with a trigger, an instance of ULS will be associated to that trigger using data-uls html attribute.
$.fn.uls is defined jquery.uls.core.js.
An example showing integration of ULS with an element is given below. Clicking on the element will open ULS. This example uses onSelect option to show the autonym of the selected language as text for element #pageLanguage.
// Bind the ULS to jQuery element with id uls-trigger
$( '#uls-trigger' ).uls( {
onSelect: function( language ) {
// Do something with the selected language
var languageName = $.uls.data.autonym( language ); // get the language autonym
$( '#pageLanguage' ).text( languageName );
}
} );
$.uls.data.autonyms()). If you want to work with a subset of languages pass that list here. The value should be an object with key as language code, value as language name to be displayed in the list.
Language filter is responsible for text based search of language names. Languages can be searched based on its autonym, written in current UI language, script name, ISO 639-2 language code. It uses the ULS data module to get all the information for search. All passed results will be passed to the result target.
The result target is a jquery object. In ULS it is the lcd component(see below). But it can be any element in the page. For example, it can be a div, ul , ol etc. languagefilter calls append() method on that object, and does not know about the rendering mechanism of target. ie, Language filter knows how to do search and rendering of results is not its responsibility.
If the searchAPI is given as option, language filter will use that API for getting results. Since API call is asynchronous, once results are obtained it will again call append methods on target. Note that every time append method is called once for each passed search.
Optionally, language filter takes two result handlers - a success handler to be called when atleast one result found and a no-result handler when no results found. These callback methods can be passed to the language filter. In ULS, the core component set these callbacks to the language filter.
Region filter: $.fn.regionselector[edit]Region selector handles updating the language list when regions are selector and updating active region when language list is scrolled. Just like language filter, this filter also works on the data provided by uls.data. Since the number of regions are finite, the region filter results are cached.
Region filters are bind to each region and not to the full map. And it is not mandatory that it should be a map. Even a link will do. Based on data-region or data-regiongroup, filtering will happen. In ULS, each of the map sections are region filters. And in no results page, we give links to regions, they are also region filters.
Just like language filter, this also calls append method on target and target in ULS is lcd component(see below).
Region filters expose a next() method that loads the next region. This is triggered at the scroll end at lcd component.
Language category display: $.fn.lcd[edit]Used for showing the search results. Languages are grouped by world regions, subregions and finally by scripts. Languages are displayed on columns and the columns are sorted alphabetically.
This component receives the language results from regionfilter or languagefilter. And this manages arranging the results in columns, and grouping by script groups. Results are also put into the appropriate regions.
The handler for click events on the languages are attached to the language links in this component.
If there is no results found, this component shows the quick list of languages as suggestion and a help text for search.
ULS comes with an extensive repository of language information. It has
The data is generated from a php script and it downloads the data from CLDR. It converts the data to javascript based format for ULS.
Around this data, there are a number of utility method to get languages based on script, regions etc. And there are utility methods to get autonym, script, territory etc. It can also sort the languages based on acronym.
Modules: $.uls.data and present in jquery.uls.data.js and jquery.uls.data.utils.js
MediaWiki Universal Language Selector extension (ULS) is implementation of jQuery.uls integrated with MediaWiki. It enhances jQuery.uls with additional features like search API, language change integration, preferences integration and limiting the languages to those supported by MediaWiki. Currently ULS only does MediaWiki interface language selection and webfonts support. In the future it will be extended to support content language selection (interwiki links and page translation) and language selection as form input.
This is a generic language settings jquery plugin. It provides a popup with settings items listed and a content pane where the specific language setting modules can render content. Language settings has a module system where specific language settings modules(for eg: input tool setting, display setting etc) can register as language settings module.
From the registered modules, language settings plugin expects the following:
This settings module is for selecting the UI language and selecting the webfonts for language. It uses jquery.webfonts for working with webfonts and uses ULS preferences system(see below) for persisting the preferences.
ULS is triggered from this module to get the additional languages for UI. See the ... button the screen.
Input method settings[edit]This language settings module integrate jquery.ime with webfonts and provides input method preferences for ULS
Language settings are available for both anonymous and logged in users. For logged in users the preferences will be saved in back end preferences system. For anonymous users, preferences are saved in browser local storage where possible. ULS preference system abstracts the different ways of retrieving and storing the preferences. The preference instance is singleton and any updates to the preferences from any component in the screen is always in sync.
Module: mw.uls.preferences, defined in ext.uls.preferences.js
The translations of language names to other languages are based on CLDR. We use Extension:CLDR for getting the language name translations. This is a big data set. If we have 1000 languages to support, we will have 1000 language names translated to all other 1000 languages resulting a matrix of 1000 X 1000 entries.
To do a cross language search in this matrix, and that search being triggered by a key press from the search window, should be really fast. For that we use a special indexing algorithm.
Indexing language names[edit]The language name matrix is very big to search. To make the search very fast we index the language names. Language names will be placed in a lot of buckets, indexed with a key the unicode point of starting letter mod 1000. This is based on the following facts and assumptions
The index is version controlled and need to be updated very rarely(may be when a new CLDR version released). But we have a php script to do this. data/LanguageNameIndexer.php. The output is a serialized index file - data/langnames.ser ( it is around 8,99,726 bytes for some CLDR version 21)
Searching for a language[edit]The following steps are involved in searching
API : LanguageNameSearch::search( $searchKey, $typos = 0 )
The language name comparison is based on . Basically it tells how many typos has a word compared to the other word. We allow one typo in the search criteria. That make 'finnish' match with a search with a typo 'finish'.
PHP's native Levenshtein distance implementation does not support multi byte characters, but in our case we need to do this search in all possible languages of the world defined in Unicode. So we wrote a custom function for Levenshtein algorithm that support multi byte unicode characters.
All jquery plugin components that are not dependent on mediaWiki is named with a prefix jquery.uls. For example jquery.uls.core.js jquery.uls.css etc.
Mediawiki specific customization and extension of jquery.uls is in the files with prefix ext.uls.
jQuery.uls follows jQuery core coding guidelines.
MediaWiki specific parts (ext.uls.*) follor MediaWiki coding conventions, which are similar to above but with less exceptions for whitespace.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4