Developer

Localizing the SDK

VERSION 2.1.2

Introduction

Maps encompass more than just roads and buildings; they reflect political boundaries and names that can differ from one country to another. Disputes over borders and land ownership exist globally, and the SDK allows for the configuration of a particular geopolitical view to manage how these disputed territories are represented. This view influences the presentation of map data, including place names, attributions, and border displays.

Navigation SDK provides the ability to configure a specific Locale, enabling to select the regional settings for receiving data. By defining a Locale, you can ensure that map data, such as place names, distances, and other region-specific attributes, align with the preferences and conventions of the users.

Geopolitical view

Default geopolitical view

If you do not specify a geopolitical view, the SDK defaults to a unified, international geopolitical view for navigation and for offline maps. In online scenarios, the country from which the request originates is considered for map visualization and search results.

Supported geopolitical views

Apart from the default view, the SDK supports at least the following geopolitical views:

  • TUR - Turkey
  • TWN - Taiwan

Additional geopolitical views may be introduced in future SDK versions or supported by specific backend services and modules.

Configuring geopolitical view

To specify a desired geopolitical view, provide an ISO 3166-1 alpha-3 country code as a String to the geopoliticalView field in SdkOptions.OnlineOnly().

1val sdkConfiguration = buildSdkConfiguration(
2    context = context,
3    apiKey = apiKey,
4    geopoliticalView = REQUIRED_GEOPOLITICAL_VIEW, // ISO-3166 Alpha-3 code
5)

If an invalid code is provided, the method will throw an IllegalArgumentException.

Additional localization settings

The TomTom SDK provides multiple options for configuring your Locale to enhance the experience across different components.

RoutePlanningOptions - Configure the language for guidance instructions and road name sections.

When planning a route, you can specify the language for a RoutePlanningOptions object using the buildRoutePlanningOptions method:

1routePlanner.planRoute(
2    routePlanningOptions = buildRoutePlanningOptions(
3        itinerary = Itinerary(origin, destination, waypoints),
4        language = Locale.ENGLISH,
5    ),
6    object : RoutePlanningCallback {
7        override fun onSuccess(result: RoutePlanningResponse) {
8            // Handle success
9        }
10

11        override fun onFailure(failure: RoutingFailure) {
12            // Handle failure
13        }
14    },
15)

SearchOptions

When performing a search, you can specify the language in which search results should be returned by setting the Locale in SearchOptions:

1SearchOptions(
2    query = query,
3    locale = Locale.ENGLISH,
4)

Navigation

To customize the unit system used during navigation, update the unitSystem as shown in the following snippet. This property should be modified after initializing the SDK using TomTomSdk.initialize(…​):

1TomTomSdk.navigation.configuration.update {
2    unitSystem = when (Locale.getDefault().isO3Country) {
3        ISO3_USA -> UnitSystemType.Fixed(UnitSystem.US)
4        ISO3_GBR -> UnitSystemType.Fixed(UnitSystem.UK)
5        else -> UnitSystemType.Fixed(UnitSystem.Metric)
6    }
7}

To configure the language used in navigation features like voice instructions and guidance messages, update the preferredLanguage property as shown in the following snippet:

TomTomSdk.navigation.preferredLanguage = Locale.ENGLISH

For detailed information on configuring Text-to-Speech voices, refer to the Voice Instructions guide.

Check the TomTom Example App

Find how to use all the relevant Navigation SDK APIs and built-in UI components to build a navigation application: