lb.base.template.i18n

Get a string computed by replacing data values in the most specific value found for given key, used as a string template.

When a function is found for the given key instead of a string template, it is called with the key, data and language code, replaced with their default values when omitted, and its return value is used as string template.  In case the call to the function template fails, null is returned instead.

Function templates may be used in place of string values in language properties to handle pluralization, for example:

function(key,data,languageCode){
  return data.number <= 1 ? "goose" : "geese";
}

The parameters to replace are surrounded by ‘#’ characters, e.g.  ‘#param-to-replace#’.  No space can appear in the name; only characters in the range [a-zA-Z0-9_\-\.] are allowed.

Replacement values are provided as properties of the data object, with the same name as the parameter:

{
  'param-to-replace': 'value'
}

Dotted parameter names, e.g.  ‘#section.subsection.name#’, are replaced with values nested within sections and subsections of the data object:

{
  section: {
    subsection: {
      name: 'value'
    }
  }
}

In case a property is not found in the given data object, getString() is called recursively to get the string value of the property for parameter replacement.

To summarize

1. the key is looked up in language properties of selected language.  A string is expected.  If no value is found, null is returned.  If a function is found, its return value is used instead; if the function fails, null is returned.

2. any parameter found in the string value is looked up, first in the given data, then in language properties of selected language, by calling getString() recursively.  A string is expected for parameter replacement.

3. the resulting string, with parameters replaced, is returned.

Parameters

• a property name: ‘name’ (at top level of language properties)
• a dotted name: ‘section.subsection.name’ (nested property)
• an array: [‘section’,’subsection’,’name’] (alternate form for nested properties)

Returns

• string, the value of corresponding property, in the most specific language available, with parameters replaced with the value of corresponding properties found in data object or as a fallback in the language properties of the most specific language available
• or null if the property is not found, or if the function template found throws an exception

Get a closure function that gets values of properties in data or, as a fallback, from language properties available for given language code.

This method is intended for use in combination with replaceParams(), to get a filter to replace parameters in a string or an HTML template with values from given data (first) or from language properties (then):

var filter = replaceParams(
  withValuesFromDataOrLanguageProperties(data,languageCode)
);

It calls getString() to retrieve values from language properties, which are treated as string templates where parameters are replaced with values from data or language properties.  See getString(key[,data[,languageCode]]): string for details.

Parameter

Returns

function, a closure wrapped around the given data and language code, with the following signature:

Function: getDataOrLanguagePropertiesValue(key): any
Get the value of a property, possibly nested, in wrapped data or,
as a fallback, from language properties of wrapped language code.

Parameter:
  key - string, the key identifying a property, which may be:
    * a string refering to the name of a property: 'name'
    * a dotted string for a nested property: 'section.name'

Returns:
  * any, the value of corresponding property, if found in data
  * any, the value of corresponding language property found in the
    most specific language available, as a fallback
  * null if neither is available

Return a filter function that removes HTML elements that do not match the given language code.

The signature of filter functions is filter(htmlElement).  In filter functions, the ‘lang’ attribute of HTML elements is compared to the given language code.  If the ‘lang’ is not an hyphenated substring of the given language code (case-insensitive), the element is removed from its parent.  Nothing happens in case the element has no parent.

No processing is done in filter functions to discover or set the language of elements without a ‘lang’ attribute.  These filters should be used in conjunction with setLanguage(htmlElement), which is intended for this purpose.

Parameter

Returns

function, a filter function for the given language code, or null if the language code was missing or not a string.

Compute and set the language of given HTML element.

This filter sets the ‘lang’ attribute of HTML elements explicitly.  When a ‘lang’ attribute is already specified, it is preserved.  When it is missing, the language inherited from ancestors is computed and set to the ‘lang’ property/attribute.

Parameter

Note

In current implementation, only the ‘lang’ attribute is set, not the ‘xml:lang’ attribute.  This may be added in a future implementation.

Replace parameters and trim nodes based on html ‘lang’ attribute.

This is a higher level filter, that applies a predefined selection of filters to the given HTML node:

• topDownParsing (from base HTML templates)
• filterByLanguage
• setLanguage
• replaceParams (from base HTML templates)

The given HTML node is modified in place.  You should clone it beforehand if you wish to preserve the original version.

The HTML node is filtered according to the languageCode argument, or if it is omitted, the language code of the application as returned by getSelectedLanguage().  Multiple translations may be included and only relevant translations will be kept, based on ‘lang’ attribute:

<div lang=''>
  <span lang='de'>Hallo #user.firstName#!</span>
  <span lang='en'>Hi #user.firstName#!</span>
  <span lang='fr'>Salut #user.firstName# !</span>
  <span lang='jp'>こんにちは#user.lastName#!</span>
</div>

Filtering the HTML from the above example for the language ‘en-GB’ would result in:

<div lang=''>
  <span lang='en'>Hi #user.firstName#!</span>
</div>

The ‘lang’ attribute is inherited from ancestors, including ancestors of the given HTML node, unless it has a ‘lang’ attribute itself.  The root element of the HTML node will be removed from its parent as well if its language does not match the language code used for filtering.  Elements within the scope of the empty language ‘’ or in the scope of no language attribute are preserved by the filtering.

Parameters of the form #param# found in text and attribute nodes are replaced in the same way as using lb.base.i18n.data.getString():

• the parameter format is based on following regular expression: /#([a-zA-Z0-9_\-\.]+)#/g
• data object contains values for the parameters to replace, which may be nested:

{
  user: {
    firstName: 'Jane',
    lastName: 'Doe'
  }
}

• when no property is found in data for the replacement of a parameter, a lookup is performed in language properties instead

After parameter replacement, the HTML node of the above example would end up as:

<div lang=''>
  <span lang='en'>Hi Jane!</span>
</div>

Parameters

Reference

Specifying the language of content: the lang attribute

• http://www.w3.org/TR/html401/struct/dirlang.html#h-8.1