Attention

You’re viewing an old version of the L’ART Research Assistant documentation. The project has moved to https://lart.readthedocs.io/projects/research-assistant.

lart.tr

On-the-fly client-side translation management for the L’ART Research Client.

This namespace implements functionality to facilitate the on-the-fly translation of user interface elements with strings loaded on-demand from the backend.

Attributes

lart.tr._activeObservers

type: object.<string, Set.<string>>

List of Node Id’s that are being actively observed for string translation.

lart.tr._callbackQueue

type: object.<string, Array.<function()>>

Queue of callbacks waiting to be called once a certain translation namespace becomes available.

lart.tr._observerQueue

type: object.<string, Set.<string>>

List of Node Id’s that should be observed for string translation after loading strings for a namespace.

lart.tr.missing

type: object.<string, object.<string, string>>

Dictionary-like object of translation IDs and innerHTML content for missing translation items.

You should not normally access the missing translation objects directly, but rather call {@link lart.tr.getMissing} to obtain the missing translation IDs and associated innerHTML for a specific translation namespace. To add missing translation objects use {@link lart.tr.addMissing}

See also

• {@link lart.tr.getMissing}

• {@link lart.tr.addMissing}

lart.tr.strings

type: object.<string, object.<string, object.<string, string>>>

Dictionary-like object holding translation identifiers and translations.

You should not normally access the translation strings directly, but rather call {@link lart.tr.get} to access the translation strings, as this implements additional logic and will be stable even if the internal structure of the string object should change in the future.

See also

• {@link lart.tr.get}

Functions

static lart.tr._activateObservers(ns)

Activate translation observers currently held in the queue.

Cycles through queued Node Id’s for translation observation. If the translation strings have been loaded already cycles through the nodes to translate them and then registers a MutationObserver on the node to monitor for changes. If translation strings are not available yet a timeout is set for 100ms, and translation and observer registration is done once the translation strings have been loaded.

Arguments:

• ns (string) – The namespace for which observers should be activated.

Returns:

null –

static lart.tr._addStrings(ns, strings)

Add translation strings from array to {@link lart.tr.strings}.

Arguments:

• ns (string) – The translation namespace to add the strings to.

• strings (object.<string, string>) – An associative array with translation strings labelled by section. Each section contains an associative array with a translation-string id, and a list of [1] the original untranslated string, and [2] the version-specific translation/adaptation.

Returns:

null –

static lart.tr._translateElement(ns, element)

Check, and if applicable, substitute a HTMLElement’s innerHTML with version-specific string.

Arguments:

• ns (string) – The translation namespace to be used.

• element (HTMLElement) – the HTMLElement to apply translation to.

Returns:

null –

static lart.tr._triggerCallbacks()

Trigger waiting callbacks once a translation space has become available.

Returns:

null –

static lart.tr.addMissing(ns, trId, innerHTML="'???'")

Add a missing translation IDs and associated innerHTML to the missing trId cache.

Arguments:

• ns (string) – The translation namespace to add the missing trId to.

• trId (string) – The translation string identifier.

• innerHTML (string) – The associated innerHTML, default is ‘???’.

Returns:

null –

static lart.tr.get(ns, trId)

Get a translation string by its translation ID.

Arguments:

• ns (string) – The translation namespace to get the translation string from.

• trId (string) – The translation identifier string.

Returns:

string – - The translated string for the identifier, or null if no string for the trId could be found in ns.

static lart.tr.getMissing(ns)

Get the missing translation IDs and associated innerHTML for missing translation items.

Results are returned as a JSON template, so that they can be copied easily into existing JSON task version translation files (or indeed used as the basis for a new one).

Arguments:

• ns (string) – The translation namespace to get missing strings for.

Returns:

string – Returns a JSON template of the missing translation IDs with their innerHTML.

static lart.tr.loadFromEel(ns, eelLoader, loaderParams=[])

Load translation/adaptation strings into a translation namespace.

Arguments:

• ns (string) – The translation namespace to be used.

• eelLoader (function) – The Python eel function (from eel.js) implementing the translation loader on the backend.

• loaderParams (Array.<any>) – The parameters that the eelLoader should be called with.

Returns:

null –

Examples:

<caption>Loads the LSBQe sections 'meta', 'base' and 'lsb' into the 'lsbq' namespace:</caption>
const instanceId = lart.utils.searchParams.get('instance');
lart.tr.loadFromEel('lsbq', eel._lsbq_load_version, [instanceId, ['meta', 'base', 'lsb']]);

static lart.tr.registerCallback(ns, callback, callbackParams)

Register a callback to be triggered when translations for a namespace become available.

This can be useful if certain UI functionality should be delayed until the translations for a specific namespace (specified by ns) have been loaded from the backend.

If the information depending on the translation is encodable as regular HTML content, it is often preferable to insert the HTML with a data-*ns*-tr attribute and use the regular {@lart.tr.registerObserver} method instead, as this will add less overhead where the targeted element or its parent might already be observed for changes.

Arguments:

• ns (string) – The translation namespace to monitor.

• callback (function) – The callback function to call once the specified translation namespace is available.

• callbackParams (any) – The parameters to pass back to callback when calling it.

Returns:

null –

static lart.tr.registerObserver(ns, nodeId)

Register a Node for translation observation for a specific namespace by a Node’s Id.

This will add an observer running translation on any HTMLElement or Node that is a child of the Node specified by nodeId. Any child node with a data-*ns*-tr attribute specifying the trId will be subject to translation from its namespace where a string with a matching trId is available.

Observers will automatically delay observation until the relevant namespace has been loaded. There is no need to (or point in) registering them separately as a callback with {@link lart.tr.registerCallback}.

Arguments:

• ns (string) – The namespace that should be observed for translation.

• nodeId (string) – The Id of the Node (and its children) to be observed.

Returns:

null –

static lart.tr.translateAttrs(ns, attrs)

Translate an attribute on one or more elements specified by their id.

If namespace ns has not been loaded yet, then translation will automatically be postponed until it is loaded. There is no need to manually register a callback.

Arguments:

• ns (string) – The translation namespace to be used.

• attrs (object.<string, Array.<string, string>>) – An associative array with Element Ids as key, and a two-member list as values, where the first is the attribute name and the second the translation ID.

Returns:

null –

static lart.tr.translateNode(ns, node)

Traverse through a DOM Node and translate all applicable HTMLElements.

Normally this will be called automatically after an observer has been registered for a Node or HTMLElement with {@link lart.tr.registerObserver}. However, you can call this manually passing a Node or HTMLElement to trigger a single pass of the string replacement algorithm for the namespace ns on that node and its children.

Arguments:

• ns (string) – The translation namespace to be translated on the nodes.

• node (Node|HTMLElement) – A DOM Node to be traversed and translated.

Returns:

null –