Localization and internationalization

Join the Mapbox Developers Discord Communityarrow-right

Mapbox Navigation SDK enables you to customize the language and units of measurement used by both text and voice instructions.

There are several default behaviors built into the SDK:

• Language: The SDK generates banner and voice instructions based on the language provided via options. See guides bellow.
• Distance: The SDK gives distances in the predominant measurement system of the device system's region, which might not necessarily be the same region in which the device is traveling.
• Time: The SDK will express units of time in the predominant system (either twelve or twenty-four-hour based) of the device system's region, which might not necessarily be the same region in which the device is traveling.
• Local place names: The upcoming road or ramp destination is named according to the local or national language. In some regions, the SDK may give the name multiple languages.

You can override these defaults in the Navigation SDK, including:

• Manually setting the language used in text and voice instructions.
• Changing the units of distance used.
• Changing how units of time are formatted.

If no language is specified, the SDK receives the defaults described above. To customize the language or units of measurement used in text and voice instructions, use the NavigationRoute.Builder class.

Supported languages

The following table lists the languages that are supported for user interface elements and spoken instructions.

Language	User interface	Spoken instructions	More info
Arabic	✅	✅	Depends on the device; might require third-party text-to-speech
Bengali	✅	—
Burmese	✅	✅	Depends on the device; might require third-party text-to-speech
Chinese	-	✅ Mandarin	Depends on the device; might require third-party text-to-speech
Czech	✅	-
Danish	✅	✅
English	✅	✅
Esperanto	—	✅	Depends on the device; might require third-party text-to-speech
Finnish	—	✅	Depends on the device; might require third-party text-to-speech
French	✅	✅
Galician	✅	—
German	✅	✅
Hebrew	✅	✅	Depends on the device; might require third-party text-to-speech
Hungarian	—	✅	Depends on the device; might require third-party text-to-speech
Indonesian	—	✅	Depends on the device; might require third-party text-to-speech
Italian	✅	✅
Japanese	—	✅
Korean	✅	✅
Norwegian	—	✅
Polish	—	✅
Portuguese	✅	✅
Romanian	—	✅
Russian	✅	✅
Slovenian	—	✅	Depends on the device; might require third-party text-to-speech
Spanish	✅	✅
Swedish	✅	✅
Turkish	—	✅
Ukrainian	✅	✅	Depends on the device; might require third-party text-to-speech
Vietnamese	✅	✅	Depends on the device; might require third-party text-to-speech
Yoruba	✅	✅	Depends on the device; might require third-party text-to-speech

Speech engine

For languages marked with Depends on the device; might require third-party text-to-speech, instructions are provided by the SDK, but it's not guaranteed that the given device will have the appropriate TextToSpeech speech engine installed to pronounce these instructions correctly.

Voice instruction sources

Turn-by-turn instructions are primarily designed to be announced by either the Mapbox Voice API or by the Android system's TextToSpeech. By default, the SDK uses the Mapbox Voice API, which requires an internet connection at various points along the route. If the Voice API lacks support for the turn-by-turn instruction language or there is no internet connection, the TextToSpeech system announces the instructions instead.

Customization

You can override the default language, units of distance, and time format used in instructions when building your route request.

Set text instructions language

To retrieve text instructions in a language other than the device's user interface language, pass the desired language through the RouteOptions.builder()'s language method as you request routes.

If you set a custom language, true must be passed though the steps() method. This true ensures that the Directions API response includes turn-by-turn instructions.

Set the text instructions language:

val routeOptions = RouteOptions.builder()
    .coordinatesList(coordinateList)
    .profile(directionsProfile)
    .steps(true)
    .language(languageCode)
    .build()

mapboxNavigation.requestRoutes(routeOptions, callback)

If you navigate using map matched routes with Mapbox Map Matching API you can pass the desired language through the MapMatchingOptions.builder()'s language method.

val options = MapMatchingOptions.Builder()
    .language(languageCode)
    .build()
mapboxNavigation.requestMapMatching(options, mapMatchingAPICallback)

Set voice instruction units of measurement

To override the measurement system used in spoken instructions, pass the desired unit through the RouteOptions.builder()'s voiceUnits() method when you request routes.

The units can either be DirectionsCriteria.IMPERIAL (the SDK's default) or DirectionsCriteria.METRIC.

If you set a desired unit, true must be passed through both the steps() and voiceInstructions() methods.

Set the units to metric:

val routeOptions = RouteOptions.builder()
    .steps(true)
    .voiceInstructions(true)
    .voiceUnits(DirectionsCriteria.METRIC)
    .build()

mapboxNavigation.requestRoutes(routeOptions, callback)

Language of spoken instructions

If you use the SDK framework to play prompt and detailed voice instructions you can pass the desired language when your create MapboxSpeechApi or MapboxVoiceInstructionsPlayer.

Format time

The NavigationOptions's builder has a .timeFormatType() method, which defines the format for the remaining trip time. The method takes either the TWELVE_HOURS (11.00PM), TWENTY_FOUR_HOURS (23.00), or NONE_SPECIFIED constant. NONE_SPECIFIED means the format will be defined by the device's current settings independent from your project. The Navigation SDK uses NONE_SPECIFIED if no format is passed through .timeFormatType().

Set the format:

val navigationOptions = NavigationOptions.Builder()
	.timeFormatType(TWENTY_FOUR_HOURS)
	.build()

Then use the NavigationOptions object when you initialize the MapboxNavigation object.

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?