widget_services_i18n
Factory for i18n widget service instances.
Contents
Module Members
Types
Module Members
create( context, configuration, optionalOptions )
Creates a widget-specific helper for didChangeLocale events.
The helper automatically observes the any changes to the locale that was configured under the i18n
feature, and can be asked for localization based on that locale. It also allows to track the current
language tag for all observed locale topics under the object i18n.tags. This object can be used to set
up value bindings and/or watchers so that other components may react to locale-changes in a data-driven
way.
The i18n helper is an AxI18nHandler for the feauture "i18n" by default, but allows to create
handlers for other feature-paths using the forFeature method.
Using release, it is possible to free the eventBus subscription held by an i18n helper instance and by
all feature-handlers created by it.
Parameters
| Property | Type | Description |
|---|---|---|
| context | AxContext |
the widget context/scope that the handler should work with. It uses the eventBus property there with which it can do the event handling |
| configuration | AxConfiguration |
the (global) configuration to use for supplying a default locale if the widget does not have an 'i18n' feature |
| optionalOptions | Object |
the fallback language tag to use when no localization is available for a locale's current language tag |
| optionalOptions.fallback | String |
the fallback language tag to use when no localization is available for a locale's current language tag |
| optionalOptions.strict | Boolean |
if true, localizations are only used if the language tags exactly match the current locale's tag (after normalizing case and dash/underscore). If false (default), specific requests can be satisfied by general localizations (e.g. a translation for 'en' may be used when missing 'en_GB' was requested). |
Returns
| Type | Description |
|---|---|
AxI18n |
an i18n instance |
Types
AxI18n
An i18n instance allows to create #AxI18nHandler instances for any feature, but is itself also
an i18n handler for the feature i18n.
So if the widget using the axI18n injection uses the recommended
name i18n for the localization feature, use this directly with the i18n handler API.
AxI18n.forFeature( featurePath )
Creates and returns an i18n handler for the loclization configuration under the given
feature path.
The configuration value is expected to be an object with the key locale that is configured with the
locale to use in the widget instance.
Parameters
| Property | Type | Description |
|---|---|---|
| featurePath | String |
the feature path localization configuration can be found at |
Returns
| Type | Description |
|---|---|
AxI18nHandler |
the i18n handler for the given feature path |
AxI18nHandler
AxI18nHandler.localize( i18nValue, optionalFallbackValue, languageTag )
Localize the given internationalized object using the given languageTag.
If i18n is configured to be strict, the currently active language tag is used to lookup a
translation.
If nothing is found, the languageTag argument is tried.
If still nothing is found, undefined is returned.
In the case strict is set to false, the behavior is the same as in strict mode if an exact
localization is available.
If not, the language tag is successively generalized by stripping off the rightmost sub-tags
until a localization is found.
Eventually, a fallback (default: 'en') is used.
This behavior is especially useful for controls (such as a datepicker), where we cannot
anticipate all required language tags, as they may be app-specific.
Parameters
| Property | Type | Description |
|---|---|---|
| i18nValue | * |
a possibly internationalized value: - when passing a primitive value, it is returned as-is - when passing an object, the languageTag is used as a key within that object |
| optionalFallbackValue | * |
a value to use if no localization is available for the given language tag |
| languageTag | String |
a language tag to override the current locale tag. Only available in strict mode |
Returns
| Type | Description |
|---|---|
* |
the localized value if found, the fallback (or undefined) otherwise |
AxI18nHandler.update( languageTag )
Updates the language tag for the configured locale by emitting the according changeLocaleRequest
event.
Parameters
| Property | Type | Description |
|---|---|---|
| languageTag | String |
the language tag to propagate |
Returns
| Type | Description |
|---|---|
Promise |
the promise of the event cycle |
AxI18nHandler.languageTag()
Returns the language tag set for the configured locale.
If no tag is available, undefined is returned.
Returns
| Type | Description |
|---|---|
String |
the active language tag or undefined |
AxI18nHandler.track( property=trackingProperty )
References the current i18n state as an object under the given property of the context.
If this method is not used, changes to the locale are still observed by the handler, but not tracked on the context object. Use this to react to locale-changes in a data-driven fashion, for example by using an AngularJS watcher.
By default, the i18n state is stored under the feature path used to create this i18n handler ("i18n" for the default handler provided by the "axI18n" widget service injection).
The tracking structure stored under the property is an object that has two properties:
- `locale` is the constant locale topic that was configured for the tracked feature - `tags` is an object mapping all locale names to their normalized current language tag
Note that tracked language tags are normalized, i.e. converted to lowercase with underscores (_)
replaced by dashes (-).
Parameters
| Property | Type | Description |
|---|---|---|
| property=trackingProperty | String |
name of the context property to store the state under, defaults to the feature path |
AxI18nHandler.format( i18nValue, optionalIndexedReplacements, optionalNamedReplacements )
Format an i18n value, by first localizing it and then applying substitutions.
These are equivalent:
string.format( axI18n.localize( i18nValue ), numericArgs, namedArgs )axI18n.format( i18nValue, numericArgs, namedArgs ).
Parameters
| Property | Type | Description |
|---|---|---|
| i18nValue | String |
the value to localize and then format |
| optionalIndexedReplacements | Array |
replacements for any numeric placeholders in the localized value |
| optionalNamedReplacements | Object |
replacements for any named placeholders in the localized value |
Returns
| Type | Description |
|---|---|
String |
the formatted string after localization |
AxI18nHandler.whenLocaleChanged( callback )
Registers a callback that is called whenever the new valid locale was received via event.
Parameters
| Property | Type | Description |
|---|---|---|
| callback | Function |
the function to call on locale change |