Localization Module


Version 0.8.0

Overview

Methods for accessessing location and language preferences

OpenRPC

Firebolt APIs are maintained in the rdkcentral/firebolt-core-sdk GitHub repository.

You can see this API in the localization.json OpenRPC JSON-Schema document.

Table of Contents

Usage

To use the Localization module, you can import it into your project from the Firebolt SDK:

import { Localization } from '@firebolt-js/sdk'

Methods

additionalInfo

Get any platform-specific localization information, in an Map<string, string>

function additionalInfo(): Promise<object>

Promise resolution:

Type Description
object the additional info

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.additionalInfo()
    .then(info => {
        console.log(info)
    })

Value of info:

{}
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.additionalInfo",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}

countryCode

Get the ISO 3166 code for the counrty device is located in

To get the value, call the method with no parameters:

function countryCode(): Promise<CountryCode>

Promise resolution:

Type Description
CountryCode the device country code

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.countryCode()
    .then(code => {
        console.log(code)
    })

Value of code:

"US"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.countryCode",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "US"
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function countryCode(subscriber: (code: CountryCode) => void): Promise<boolean>

Parameters:

Param Type Required Summary
subscriber Function Yes A callback that gets invoked when the value for countryCode changes

Promise resolution:

Type Summary
listenerId The id of the listener that can be used with Localization.clear(listenerId) to unsubscribe

Callback parameters:

Param Type Required Summary
code CountryCode Yes the device country code

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.countryCode(code => {
  // property value was changed
  console.log(code)
}).then(listenerId => {
  // you can clear this listener w/ Localization.clear(listenerId)
})

value of code:

"US"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.onCountryCodeChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "US"
}

language

Get the ISO 639 1/2 code for the preferred language

To get the value, call the method with no parameters:

function language(): Promise<Language>

Promise resolution:

Type Description
Language the device language

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.language()
    .then(lang => {
        console.log(lang)
    })

Value of lang:

"en"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.language",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "en"
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function language(subscriber: (lang: Language) => void): Promise<boolean>

Parameters:

Param Type Required Summary
subscriber Function Yes A callback that gets invoked when the value for language changes

Promise resolution:

Type Summary
listenerId The id of the listener that can be used with Localization.clear(listenerId) to unsubscribe

Callback parameters:

Param Type Required Summary
lang Language Yes the device language

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.language(lang => {
  // property value was changed
  console.log(lang)
}).then(listenerId => {
  // you can clear this listener w/ Localization.clear(listenerId)
})

value of lang:

"en"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.onLanguageChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "en"
}

latlon

Get the approximate latitude and longitude coordinates of the device location

function latlon(): Promise<[number, number]>

Promise resolution:

Type Description
[number, number] lat/long tuple

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.latlon()
    .then(latlong => {
        console.log(latlong)
    })

Value of latlong:

[
  39.9549,
  75.1699
]
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.latlon",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    39.9549,
    75.1699
  ]
}

listen

Listen for events from this module.

To listen to a specific event pass the event name as the first parameter:

Localization.listen(event: string, (data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. Localization.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

Localization.listen((event: string, data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. Localization.clear(id)

See Listening for events for more information and examples.


locale

Get the full BCP 47 code, including script, region, variant, etc., for the preferred langauage/locale

To get the value, call the method with no parameters:

function locale(): Promise<Locale>

Promise resolution:

Type Description
Locale the device locale

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.locale()
    .then(locale => {
        console.log(locale)
    })

Value of locale:

"en-US"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.locale",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "en-US"
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function locale(subscriber: (locale: Locale) => void): Promise<boolean>

Parameters:

Param Type Required Summary
subscriber Function Yes A callback that gets invoked when the value for locale changes

Promise resolution:

Type Summary
listenerId The id of the listener that can be used with Localization.clear(listenerId) to unsubscribe

Callback parameters:

Param Type Required Summary
locale Locale Yes the device locale

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.locale(locale => {
  // property value was changed
  console.log(locale)
}).then(listenerId => {
  // you can clear this listener w/ Localization.clear(listenerId)
})

value of locale:

"en-US"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.onLocaleChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "en-US"
}

locality

Get the locality/city the device is located in

function locality(): Promise<Locality>

Promise resolution:

Type Description
Locality the device city

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.locality()
    .then(locality => {
        console.log(locality)
    })

Value of locality:

"Philadelphia"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.locality",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Philadelphia"
}

once

Listen for only one occurance of an event from this module. The callback will be cleared after one event.

To listen to a specific event pass the event name as the first parameter:

Localization.once(event: string, (data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. Localization.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

Localization.once((event: string, data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. Localization.clear(id)

See Listening for events for more information and examples.


postalCode

Get the postal code the device is located in

To get the value, call the method with no parameters:

function postalCode(): Promise<string>

Promise resolution:

Type Description
string the device postal code

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.postalCode()
    .then(postalCode => {
        console.log(postalCode)
    })

Value of postalCode:

"19103"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.postalCode",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "19103"
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function postalCode(subscriber: (postalCode: string) => void): Promise<boolean>

Parameters:

Param Type Required Summary
subscriber Function Yes A callback that gets invoked when the value for postalCode changes

Promise resolution:

Type Summary
listenerId The id of the listener that can be used with Localization.clear(listenerId) to unsubscribe

Callback parameters:

Param Type Required Summary
postalCode string Yes the device postal code

Examples

Default Example

JavaScript:

import { Localization } from '@firebolt-js/sdk'

Localization.postalCode(postalCode => {
  // property value was changed
  console.log(postalCode)
}).then(listenerId => {
  // you can clear this listener w/ Localization.clear(listenerId)
})

value of postalCode:

"19103"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "localization.onPostalCodeChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "19103"
}

Events

Additional events

The following events are documented as part of a related set of method APIs.

For more information, follow the links under the “Documentation” column.

JavaScript RPC Payload Documentation
postalCodeChanged onPostalCodeChanged string postalCode
countryCodeChanged onCountryCodeChanged CountryCode countryCode
languageChanged onLanguageChanged Language language
localeChanged onLocaleChanged Locale locale

Schemas

LatLon

type LatLon = [number, number]

Go To Top