Change Localization Settings

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_common_settings allows for the following in-app customisations:

How to use the API 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 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 use the API to change the clock time format between 12 hours and 24 hours

TomTom Digital Cockpit provides an API which allows for customisation of the Android system clock time format. The tool allows both for setting the desired time format and for retrieving the current time format setting.

Setting the desired time format

To change the clock time format to the desired setting, a call should be made to the function setClockTimeFormat. by passing as parameters the Context instance and the desired setting in the following enum format:

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.setSystemLocale
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 system time format

To retrieve the current system time format, simply call getClockTimeFormat and pass in the Context. The API will return 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.