Developer

Change Localization Settings

Last edit: 2024.01.18

Localization API overview

TomTom Digital Cockpit provides a comprehensive set of tools for changing the localization features of the in-vehicle system such as units of measurement and language. This allows for greater customisation and scalability across various regions, allowing the driver to interact with language and measurements which are familiar to them.

Currently the Localization API module platform_localization_api_service_settings allows for the following in-app customizations:

How to change the system language

Language changing API for switching the Android Locale at a system level.

The language change is called via the function LocalizationSettingsService.setSystemLocale by passing an Android Locale object initialised with the desired language and region fields as illustrated below.

1import com.tomtom.ivi.platform.localization.api.common.settings.setSystemLocale
2

3// Change the system locale to Spanish (language) US (region)
4val spanishLocale = Locale("es", "US")
5setSystemLocale(spanishLocale)
6

7// Change the system locale to Italian (language)
8val italianLocale = Locale("it")
9setSystemLocale(italianLocale)

Because this API switches the whole system Locale, the change in localization is also reflected in third-party apps.

Note: Triggering a system locale change by calling this API will cause all activities to restart.

Setting system locale with invalid locale

The Android Locale does not perform any validation of the language or region fields it is constructed with. It is possible to construct an instance of a Locale with an invalid language or region field not corresponding to any language or country, such as follows:

val invalidLocale = Locale("invalidLanguage", "invalidRegion")
setSystemLocale(invalidLocale)

In these instances it is worth noting that the typical behaviour of the Android system is to fallback to US English.

Setting system locale with same locale as current

If the user attempts to set a new Locale which is the same as the current one, the Android system will do nothing.

How to change the Distance Measurement System

TomTom Digital Cockpit provides an API for configuring the distance measurement system used by the platform. This API allows for easy switching between imperial and metric systems.

Setting the desired distance measurement system

To change the distance measurement system to the desired setting, call the function LocalizationSettingsService.setActiveDistanceMeasurementSystem, passing as a parameter the desired setting as a DistanceMeasurementSystem enum value:

1import com.tomtom.ivi.platform.localization.api.service.settings.LocalizationSettingsService
2

3// Create an instance of service's client API.
4private val localizationSettingsService =
5        LocalizationSettingsService.createApi(this, frontendContext.iviServiceProvider)
6...
7

8// Change distance measurement system to Imperial.
9localizationSettingsService.queueOrRun {
10    it.setActiveDistanceMeasurementSystemAsync(IMPERIAL)
11}
12

13// Change distance measurement system to Metric.
14localizationSettingsService.queueOrRun {
15    it.setActiveDistanceMeasurementSystemAsync(METRIC)
16}

Retrieving the current setting

The current distance measurement system can be retrieved using the property LocalizationSettingsService.activeDistanceMeasurementSystem.

How to change the Temperature Display Units

TomTom Digital Cockpit provides an API for configuring the temperature display unit used by the platform. This API allows for easy switching between Celsius and Fahrenheit temperature display units.

Setting the desired format

To change the temperature display units to the desired setting, call the function LocalizationSettingsService.setActiveTemperatureDisplayUnit, passing as parameter the desired setting as a Temperature.Unit enum value:

1import com.tomtom.ivi.platform.localization.api.service.settings.LocalizationSettingsService
2import com.tomtom.tools.android.api.quantity.Temperature
3

4// Create an instance of service's client API.
5private val localizationSettingsService =
6        LocalizationSettingsService.createApi(this, frontendContext.iviServiceProvider)
7...
8

9// Change temperature display unit to Celsius.
10localizationSettingsService.queueOrRun {
11    it.setActiveTemperatureDisplayUnitAsync(Temperature.Unit.CELSIUS)
12}
13

14// Change temperature display unit to Fahrenheit.
15localizationSettingsService.queueOrRun {
16    it.setActiveTemperatureDisplayUnitAsync(Temperature.Unit.FAHRENHEIT)
17}

Retrieving the current setting

The current temperature display units can be retrieved using the property LocalizationSettingsService.activeTemperatureDisplayUnit.

How to change the clock time format

TomTom Digital Cockpit provides an API which allows for customization of the Android system clock time format. It supports setting the desired time format as well as retrieving the current setting.

Setting the desired format

To change the clock time format to the desired setting, call the function LocalizationSettingsService.setClockTimeFormat passing as parameters the Context instance and the desired setting as a TimeFormat enum value:

It is also possible to call the API with the enum value TimeFormat.UNSET. In this case, the API will default to setting the 24-hour format.

1import com.tomtom.ivi.platform.localization.api.common.settings.setClockTimeFormat
2

3// Change the clock format to 12 hours, e.g. 2:20pm
4setClockTimeFormat(activityContext, TimeFormat.CLOCK_12H)
5

6// Change the clock format to 24 hours, e.g. 14:20
7setClockTimeFormat(activityContext, TimeFormat.CLOCK_24H)

Retrieving the current setting

To retrieve the current system time format, use the property LocalizationSettingsService.activeTimeFormat, which contains a TimeFormat enum representing the current system setting stored in [Settings.System.TIME_12_24] as either TimeFormat.CLOCK_24H, TimeFormat.CLOCK_12H or TimeFormat.UNSET in the case that no setting has yet been set with this API.