qLabel: Technical description

In the Semantic Web, every object of interest has a URI, a unique identifier. These URIs can be resolved in order to look up more data about the object, for example its label in different languages.

This is exactly what qLabel does. These labels are then used to replace the text content of the annotated element, when so requested by the user.

One frequent issue with the approach sketched above is that resolving every single URI one after the other simply takes a lot of time and resources. qLabel provides a mechanism to register different loaders, and even three example loaders (for Wikidata, Freebase, and the fallback Semantic Web loader). These loaders can be implemented much more efficiently (e.g. the Wikidata and Freebase loaders cut down the number of web requests by an order of magnitude and more). They also don't require the rdfquery library, so that you don't have to parse RDF/XML in the browser, which could further reduce your footprint.

Documentation

The qLabel library adds the $.qlabel object that has the following public interface.

switchLanguage(lang)

Sets the language to lang (which is a ISO 639 language code) and changes the displayed text on the Website. It will first gather all annotating URIs from all elements that have class qlabel, check if these URIs are already known, load the unknown ones, and once they are all loaded, the text content of the elements changes if a label in the requested language exists. The function returns a promise that will resolve once the language has switched.

getLanguage()

Returns the ISO 639 language code that was set last.

setClassName(clsName)

Sets the class name used to find the elements that should be translated. The default class name is qlabel

getClassName()

Returns the class name used to find the elements that should be translated which was set last or qlabel if nothing was set.

getLabel(URI, lang)

Returns a label for the requested URI and language. If the URI is unknown, or if there is no label for the specified language for the requested URI, undefined is returned.

getLabels(URI)

Returns an object where the keys are the language codes and the values are the labels, for the requested URI. If the URI is unknown, undefined will be returned.

setLabel(URI, lang, label)

Provide qLabel with a Label for the given URI and language. Now, the URI is known (and will not be loaded when calling switchLanguage). setLabel can be used to set the labels manually and not load the labels for every user, and can thus safe resources.

loadLabels(URIs)

The parameter is optional. URIs is a list of URIs for which labels will be loaded. If they are already known, they will not be loaded. If URIs is empty, all annotating URIs on elements with the class qlabel will be loaded. The function returns a promise that will be resolved once the labels are loaded.

getKnownURIs()

Returns an array with all URIs that are known.

setLoader(tester, loader)

Sets a loader. A loader consists of two functions, a tester and a loader. The tester takes a single string and returns a (possibly normalized) string if the loader is able to load the given URI (and returns undefined else). The loader takes an array of strings that the loader will load. The loader should use the setLabel function to set all loaded labels, and return a promise which will be resolved once the loader is finished.

There are three loaders already available: a Freebase loader, a Wikidata loader, and a generic Semantic Web loader using Linked Data principles.

setFreebaseKey(key)

Sets the Google Freebase API key to be used when calling Freebase.

getFreebaseKey()

Returns the previously set Google Freebase API key, or an empty string if none is set.

Open tasks and future of qLabel

I am not particularly keen on maintaining qLabel. The library is Open Source and I am happy if someone wants to take over maintenance and further development.

A few open issues: