Localization Module

Version Localization 1.4.1

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'

Overview

Methods for accessessing location and language preferences

Methods

additionalInfo

Get any platform-specific localization information

function additionalInfo(): Promise<object>

Promise resolution:

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:additional-info

Examples

Default Example

JavaScript:

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

let info = await Localization.additionalInfo()
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-1 alpha-2 code for the country device is located in

To get the value of countryCode call the method like this:

function countryCode(): Promise<CountryCode>

Promise resolution:

CountryCode

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:country-code

Examples

Default example #1

JavaScript:

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

let code = await Localization.countryCode()
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"
}

Default example #2

JavaScript:

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

let code = await Localization.countryCode()
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": "UK"
}

To subscribe to notifications when the value changes, call the method like this:

function countryCode(callback: (value) => CountryCode): Promise<number>

Promise resolution:

number

Examples

Default example #1

JavaScript:

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

let listenerId = await countryCode((value) => {
  console.log(value)
})
console.log(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": "US"
}

Default example #2

JavaScript:

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

let listenerId = await countryCode((value) => {
  console.log(value)
})
console.log(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": "UK"
}

language

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

To get the value of language call the method like this:

function language(): Promise<Language>

Promise resolution:

Language

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:language

Examples

Default example #1

JavaScript:

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

let lang = await Localization.language()
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"
}

Default example #2

JavaScript:

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

let lang = await Localization.language()
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": "es"
}

To subscribe to notifications when the value changes, call the method like this:

function language(callback: (value) => Language): Promise<number>

Promise resolution:

number

Examples

Default example #1

JavaScript:

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

let listenerId = await language((value) => {
  console.log(value)
})
console.log(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": "en"
}

Default example #2

JavaScript:

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

let listenerId = await language((value) => {
  console.log(value)
})
console.log(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": "es"
}

latlon

Get the approximate latitude and longitude coordinates of the device location

function latlon(): Promise<LatLon>

Promise resolution:

LatLon

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:location

Examples

Default Example

JavaScript:

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

let latlong = await Localization.latlon()
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

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

listen(event: string, callback: (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:

listen(callback: (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 of locale call the method like this:

function locale(): Promise<Locale>

Promise resolution:

Locale

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:locale

Examples

Default example #1

JavaScript:

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

let locale = await Localization.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"
}

Default example #2

JavaScript:

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

let locale = await Localization.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": "es-US"
}

To subscribe to notifications when the value changes, call the method like this:

function locale(callback: (value) => Locale): Promise<number>

Promise resolution:

number

Examples

Default example #1

JavaScript:

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

let listenerId = await locale((value) => {
  console.log(value)
})
console.log(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": "en-US"
}

Default example #2

JavaScript:

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

let listenerId = await locale((value) => {
  console.log(value)
})
console.log(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": "es-US"
}

locality

Get the locality/city the device is located in

To get the value of locality call the method like this:

function locality(): Promise<Locality>

Promise resolution:

Locality

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:locality

Examples

Default example #1

JavaScript:

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

let locality = await Localization.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"
}

Default example #2

JavaScript:

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

let locality = await Localization.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": "Rockville"
}

To subscribe to notifications when the value changes, call the method like this:

function locality(callback: (value) => Locality): Promise<number>

Promise resolution:

number

Examples

Default example #1

JavaScript:

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

let listenerId = await locality((value) => {
  console.log(value)
})
console.log(listenerId)

Value of locality:

'Philadelphia'
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Localization.onLocalityChanged",
  "params": {
    "listen": true
  }
}

Response:

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

Default example #2

JavaScript:

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

let listenerId = await locality((value) => {
  console.log(value)
})
console.log(listenerId)

Value of locality:

'Philadelphia'
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Localization.onLocalityChanged",
  "params": {
    "listen": true
  }
}

Response:

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

once

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

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

The once method will only pass the next instance of this event, and then dicard the listener you provided.

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 the next instance only of any events from this module pass only a callback, without specifying an event name:

once(callback: (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 of postalCode call the method like this:

function postalCode(): Promise<string>

Promise resolution:

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:postal-code

Examples

Default example #1

JavaScript:

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

let postalCode = await Localization.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"
}

Default example #2

JavaScript:

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

let postalCode = await Localization.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": "20850"
}

To subscribe to notifications when the value changes, call the method like this:

function postalCode(callback: (value) => string): Promise<number>

Promise resolution:

number

Examples

Default example #1

JavaScript:

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

let listenerId = await postalCode((value) => {
  console.log(value)
})
console.log(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": "19103"
}

Default example #2

JavaScript:

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

let listenerId = await postalCode((value) => {
  console.log(value)
})
console.log(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": "20850"
}

preferredAudioLanguages

A prioritized list of ISO 639 1/2 codes for the preferred audio languages on this device.

To get the value of preferredAudioLanguages call the method like this:

function preferredAudioLanguages(): Promise<ISO639_2Language[]>

Promise resolution:

Capabilities:

Role Capability
uses xrn:firebolt:capability:localization:language

Examples

Default Example

JavaScript:

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

let languages = await Localization.preferredAudioLanguages()
console.log(languages)

Value of languages:

;['spa', 'eng']
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Localization.preferredAudioLanguages",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ["spa", "eng"]
}

Default Example #2

JavaScript:

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

let languages = await Localization.preferredAudioLanguages()
console.log(languages)

Value of languages:

;['spa', 'eng']
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Localization.preferredAudioLanguages",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ["eng", "spa"]
}

To subscribe to notifications when the value changes, call the method like this:

function preferredAudioLanguages(
  callback: (value) => ISO639_2Language[],
): Promise<number>

Promise resolution:

number

Examples

Default Example

JavaScript:

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

let listenerId = await preferredAudioLanguages((value) => {
  console.log(value)
})
console.log(listenerId)

Value of languages:

;['spa', 'eng']
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Localization.onPreferredAudioLanguagesChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ["spa", "eng"]
}

Default Example #2

JavaScript:

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

let listenerId = await preferredAudioLanguages((value) => {
  console.log(value)
})
console.log(listenerId)

Value of languages:

;['spa', 'eng']
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Localization.onPreferredAudioLanguagesChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ["eng", "spa"]
}

Events

countryCodeChanged

See: countryCode

languageChanged

See: language

localeChanged

See: locale

localityChanged

See: locality

postalCodeChanged

See: postalCode

preferredAudioLanguagesChanged

See: preferredAudioLanguages

Types

LatLon

type LatLon = [
  number, // undefined  item
  number, // undefined  item
]