LocaleContext

LocaleContext may capture language and/or country in multilingual Applications.

Installation

yarn add @objectiv/plugin-locale-context

or

npm install @objectiv/plugin-locale-context

Implementation

Implements PluginInterface's enrich.

enrich

Creates a new instance of LocaleContext and sets its properties using the given factories.

isUsable

Always true.

Configuration

The Plugin constructor requires at least one of the following factories to be specified:

idFactoryFunction: () => string | null | undefined;
languageFactoryFunction: () => string | null | undefined;
countryFactoryFunction: () => string | null | undefined;
caution
  • languageFactoryFunction return value must be a valid ISO 639-1 language code.
  • countryFactoryFunction return value must be a valid ISO 3166-1 alpha-2 country code.

Values returned by either factory that do not conform to their respective ISO standard will be discarded, and the plugin will not generate a LocaleContext.

The issue is logged to the TrackerConsole during development.

Id generation

LocaleContext, like all other Global Contexts, must have an identifier.

It can be set directly by specifying the idFactoryFunction, or generated indirectly via languageCodeFactory and/or countryCodeFactory.

In the latter scenario the identifier is going to be a composition of the returning values of the languageCodeFactory and/or countryCodeFactory.

Id generation examples

{ idFactoryFunction: () => 'custom-id' }                             // id: 'custom-id'
{ languageCodeFactory: () => 'en' } // id: 'en'
{ countryCodeFactory: () => 'US' } // id: 'US'
{ languageCodeFactory: () => 'en', countryCodeFactory: () => 'US' } // id: 'en_US'
info

Identifiers are not used for modeling, but specifying an idFactoryFunction can be used to later transform the data and produce a fully functional LocaleContext, in the backend or the data pipeline.

This is particularly useful in applications that don't have the capability to provide valid language or country codes.

Usage examples

Locale from URL

Example URL: http://www.website.dev/en/slug2.
Expected LocaleContext id: en.

makeTracker({
applicationId: 'app-id',
endpoint: 'https://collector.app.dev',
plugins: [
new LocaleContextPlugin({
languageFactoryFunction: () => location.pathname.split('/')[1] ?? null
})
]
});

Non-standard language id

const someArbitraryState = {
language: 'lan1'
}

makeTracker({
applicationId: 'app-id',
endpoint: 'https://collector.app.dev',
plugins: [
new LocaleContextPlugin({
idFactoryFunction: () => someArbitraryState.language
})
]
});
info

As mentioned above, this custom identifier will not be usable directly for modeling, but it may be mapped server-side to its actual language and/or country via enrichment/transformations.

In the worst case scenario, it can be used just for simple filtering operations. That said, to fully leverage Locale based models, we definitely would recommend looking into standardizing your application languages.