UNPKG

@firebolt-js/sdk

Version:
1,658 lines (1,180 loc) 26.2 kB
--- title: Localization --- # Localization Module --- Version Localization 1.5.0 ## Table of Contents - [Table of Contents](#table-of-contents) - [Usage](#usage) - [Overview](#overview) - [Methods](#methods) - [additionalInfo](#additionalinfo) - [countryCode](#countrycode) - [language](#language) - [latlon](#latlon) - [listen](#listen) - [locale](#locale) - [locality](#locality) - [once](#once) - [postalCode](#postalcode) - [preferredAudioLanguages](#preferredaudiolanguages) - [Events](#events) - [countryCodeChanged](#countrycodechanged) - [languageChanged](#languagechanged) - [localeChanged](#localechanged) - [localityChanged](#localitychanged) - [postalCodeChanged](#postalcodechanged) - [preferredAudioLanguagesChanged](#preferredaudiolanguageschanged) - [Private Events](#private-events)<details ontoggle="document.getElementById('private-events-details').open=this.open"><summary>Show</summary> - [languageChanged](#languagechanged-1) - [localeChanged](#localechanged-1) - [localityChanged](#localitychanged-1) - [postalCodeChanged](#postalcodechanged-1) - [preferredAudioLanguagesChanged](#preferredaudiolanguageschanged-1) </details> - [Types](#types) - [LatLon](#latlon-1) ## Usage To use the Localization module, you can import it into your project from the Firebolt SDK: ```javascript import { Localization } from '@firebolt-js/sdk' ``` ## Overview Methods for accessessing location and language preferences ## Methods ### additionalInfo Get any platform-specific localization information ```typescript function additionalInfo(): Promise<object> ``` Promise resolution: Capabilities: | Role | Capability | | ---- | ---------------------------------------------------- | | uses | xrn:firebolt:capability:localization:additional-info | #### Examples Default Example JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let info = await Localization.additionalInfo() console.log(info) ``` Value of `info`: ```javascript { } ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.additionalInfo", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": {} } ``` </details> --- ### 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: ```typescript function countryCode(): Promise<CountryCode> ``` Promise resolution: [CountryCode](../Localization/schemas/#CountryCode) Capabilities: | Role | Capability | | ---- | ------------------------------------------------- | | uses | xrn:firebolt:capability:localization:country-code | #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let code = await Localization.countryCode() console.log(code) ``` Value of `code`: ```javascript 'US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.countryCode", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "US" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let code = await Localization.countryCode() console.log(code) ``` Value of `code`: ```javascript 'US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.countryCode", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "UK" } ``` </details> --- To subscribe to notifications when the value changes, call the method like this: ```typescript function countryCode(callback: (value) => CountryCode): Promise<number> ``` Promise resolution: ``` number ``` #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await countryCode((value) => { console.log(value) }) console.log(listenerId) ``` Value of `code`: ```javascript 'US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onCountryCodeChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "US" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await countryCode((value) => { console.log(value) }) console.log(listenerId) ``` Value of `code`: ```javascript 'US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onCountryCodeChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "UK" } ``` </details> --- ### language Get the ISO 639 1/2 code for the preferred language To get the value of `language` call the method like this: ```typescript function language(): Promise<Language> ``` Promise resolution: [Language](../Localization/schemas/#Language) Capabilities: | Role | Capability | | ---- | --------------------------------------------- | | uses | xrn:firebolt:capability:localization:language | #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let lang = await Localization.language() console.log(lang) ``` Value of `lang`: ```javascript 'en' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.language", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "en" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let lang = await Localization.language() console.log(lang) ``` Value of `lang`: ```javascript 'en' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.language", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "es" } ``` </details> --- To subscribe to notifications when the value changes, call the method like this: ```typescript function language(callback: (value) => Language): Promise<number> ``` Promise resolution: ``` number ``` #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await language((value) => { console.log(value) }) console.log(listenerId) ``` Value of `lang`: ```javascript 'en' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onLanguageChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "en" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await language((value) => { console.log(value) }) console.log(listenerId) ``` Value of `lang`: ```javascript 'en' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onLanguageChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "es" } ``` </details> --- ### latlon Get the approximate latitude and longitude coordinates of the device location ```typescript function latlon(): Promise<LatLon> ``` Promise resolution: [LatLon](#latlon-1) Capabilities: | Role | Capability | | ---- | --------------------------------------------- | | uses | xrn:firebolt:capability:localization:location | #### Examples Default Example JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let latlong = await Localization.latlon() console.log(latlong) ``` Value of `latlong`: ```javascript ;[39.9549, 75.1699] ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.latlon", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [39.9549, 75.1699] } ``` </details> --- ### listen To listen to a specific event pass the event name as the first parameter: ```typescript listen(event: string, callback: (data: any) => void): Promise<number> ``` Parameters: | Param | Type | Required | Summary | | ---------- | ---------- | -------- | ------------------------------------------------------ | | `event` | `string` | Yes | The event to listen for, see [Events](#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](#events). | To listen to all events from this module pass only a callback, without specifying an event name: ```typescript 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](#events). | Callback parameters: | Param | Type | Required | Summary | | ------- | -------- | -------- | ------------------------------------------------------------------------------ | | `event` | `string` | Yes | The event that has occured listen for, see [Events](#events). | | `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](#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](../../docs/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: ```typescript function locale(): Promise<Locale> ``` Promise resolution: [Locale](../Localization/schemas/#Locale) Capabilities: | Role | Capability | | ---- | ------------------------------------------- | | uses | xrn:firebolt:capability:localization:locale | #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let locale = await Localization.locale() console.log(locale) ``` Value of `locale`: ```javascript 'en-US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.locale", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "en-US" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let locale = await Localization.locale() console.log(locale) ``` Value of `locale`: ```javascript 'en-US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.locale", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "es-US" } ``` </details> --- To subscribe to notifications when the value changes, call the method like this: ```typescript function locale(callback: (value) => Locale): Promise<number> ``` Promise resolution: ``` number ``` #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await locale((value) => { console.log(value) }) console.log(listenerId) ``` Value of `locale`: ```javascript 'en-US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onLocaleChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "en-US" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await locale((value) => { console.log(value) }) console.log(listenerId) ``` Value of `locale`: ```javascript 'en-US' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onLocaleChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "es-US" } ``` </details> --- ### locality Get the locality/city the device is located in To get the value of `locality` call the method like this: ```typescript function locality(): Promise<Locality> ``` Promise resolution: [Locality](../Localization/schemas/#Locality) Capabilities: | Role | Capability | | ---- | --------------------------------------------- | | uses | xrn:firebolt:capability:localization:locality | #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let locality = await Localization.locality() console.log(locality) ``` Value of `locality`: ```javascript 'Philadelphia' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.locality", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "Philadelphia" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let locality = await Localization.locality() console.log(locality) ``` Value of `locality`: ```javascript 'Philadelphia' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.locality", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "Rockville" } ``` </details> --- To subscribe to notifications when the value changes, call the method like this: ```typescript function locality(callback: (value) => Locality): Promise<number> ``` Promise resolution: ``` number ``` #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await locality((value) => { console.log(value) }) console.log(listenerId) ``` Value of `locality`: ```javascript 'Philadelphia' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onLocalityChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "Philadelphia" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await locality((value) => { console.log(value) }) console.log(listenerId) ``` Value of `locality`: ```javascript 'Philadelphia' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onLocalityChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "Rockville" } ``` </details> --- ### once To listen to a single instance of a specific event pass the event name as the first parameter: ```typescript 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](#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](#events). | To listen to the next instance only of any events from this module pass only a callback, without specifying an event name: ```typescript 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](#events). | Callback parameters: | Param | Type | Required | Summary | | ------- | -------- | -------- | ------------------------------------------------------------------------------ | | `event` | `string` | Yes | The event that has occured listen for, see [Events](#events). | | `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](#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](../../docs/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: ```typescript function postalCode(): Promise<string> ``` Promise resolution: Capabilities: | Role | Capability | | ---- | ------------------------------------------------ | | uses | xrn:firebolt:capability:localization:postal-code | #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let postalCode = await Localization.postalCode() console.log(postalCode) ``` Value of `postalCode`: ```javascript '19103' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.postalCode", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "19103" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let postalCode = await Localization.postalCode() console.log(postalCode) ``` Value of `postalCode`: ```javascript '19103' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.postalCode", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "20850" } ``` </details> --- To subscribe to notifications when the value changes, call the method like this: ```typescript function postalCode(callback: (value) => string): Promise<number> ``` Promise resolution: ``` number ``` #### Examples Default example #1 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await postalCode((value) => { console.log(value) }) console.log(listenerId) ``` Value of `postalCode`: ```javascript '19103' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onPostalCodeChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "19103" } ``` </details> Default example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await postalCode((value) => { console.log(value) }) console.log(listenerId) ``` Value of `postalCode`: ```javascript '19103' ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onPostalCodeChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "20850" } ``` </details> --- ### 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: ```typescript function preferredAudioLanguages(): Promise<ISO639_2Language[]> ``` Promise resolution: Capabilities: | Role | Capability | | ---- | --------------------------------------------- | | uses | xrn:firebolt:capability:localization:language | #### Examples Default Example JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let languages = await Localization.preferredAudioLanguages() console.log(languages) ``` Value of `languages`: ```javascript ;['spa', 'eng'] ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.preferredAudioLanguages", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": ["spa", "eng"] } ``` </details> Default Example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let languages = await Localization.preferredAudioLanguages() console.log(languages) ``` Value of `languages`: ```javascript ;['spa', 'eng'] ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.preferredAudioLanguages", "params": {} } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": ["eng", "spa"] } ``` </details> --- To subscribe to notifications when the value changes, call the method like this: ```typescript function preferredAudioLanguages( callback: (value) => ISO639_2Language[], ): Promise<number> ``` Promise resolution: ``` number ``` #### Examples Default Example JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await preferredAudioLanguages((value) => { console.log(value) }) console.log(listenerId) ``` Value of `languages`: ```javascript ;['spa', 'eng'] ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onPreferredAudioLanguagesChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": ["spa", "eng"] } ``` </details> Default Example #2 JavaScript: ```javascript import { Localization } from '@firebolt-js/sdk' let listenerId = await preferredAudioLanguages((value) => { console.log(value) }) console.log(listenerId) ``` Value of `languages`: ```javascript ;['spa', 'eng'] ``` <details> <summary>JSON-RPC:</summary> Request: ```json { "jsonrpc": "2.0", "id": 1, "method": "Localization.onPreferredAudioLanguagesChanged", "params": { "listen": true } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": ["eng", "spa"] } ``` </details> --- ## Events ### countryCodeChanged See: [countryCode](#countrycode) ### languageChanged See: [language](#language) ### localeChanged See: [locale](#locale) ### localityChanged See: [locality](#locality) ### postalCodeChanged See: [postalCode](#postalcode) ### preferredAudioLanguagesChanged See: [preferredAudioLanguages](#preferredaudiolanguages) ## Private Events <details id="private-events-details"> <summary>View</summary> ### countryCodeChanged See: [countryCode](#countrycode) ### languageChanged See: [language](#language) ### localeChanged See: [locale](#locale) ### localityChanged See: [locality](#locality) ### postalCodeChanged See: [postalCode](#postalcode) ### preferredAudioLanguagesChanged See: [preferredAudioLanguages](#preferredaudiolanguages) </details> ## Types ### LatLon ```typescript type LatLon = [ number, // undefined item number, // undefined item ] ``` ---