Localization and internationalization
The Navigation SDK allows you to customize the language and units of measurement used by both text and voice instructions.
There are several default behaviors built into the Navigation SDK:
- Language: The SDK will use the language defined in the device settings if it is available (see Supported languages below) for both user interface and spoken instructions. Instructions are announced in English if they're not available in the user interface language.
- Distance: The SDK gives distances in the predominant measurement system of the device system's region, which may 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 may 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.
The Navigation SDK allows you to override these defaults, including:
- Manually setting the language used in text and voice instructions.
- Changing the units of distance used.
- Changing how units of time are formatted.
Because language and units of measurement are specified when the route is generated, this guide does not describe any specific options in the Navigation UI SDK. The Navigation UI SDK will receive the defaults described above if no language is specified. If you would like to customize the language or units of measurement used in text and voice instructions, you must use the NavigationRoute.Builder class.
Supported languages
The table below lists the languages that are supported for user interface elements and for spoken instructions.
| Language | Code | User interface | Spoken instructions | Notes |
|---|---|---|---|---|
| Arabic | ar | ✅ | ✅ | Depends on the device; may require third-party text-to-speech |
| Bengali | bn | ✅ | — | |
| Burmese | my | ✅ | ✅ | Depends on the device; may require third-party text-to-speech |
| Chinese | zh-Hans | - | ✅ Mandarin | Depends on the device; may require third-party text-to-speech |
| Czech | cs | ✅ | - | |
| Danish | da | ✅ | ✅ | |
| English | en | ✅ | ✅ | |
| Esperanto | eo | — | ✅ | Depends on the device; may require third-party text-to-speech |
| Finnish | fi | — | ✅ | Depends on the device; may require third-party text-to-speech |
| French | fr | ✅ | ✅ | |
| Galician | gl | ✅ | — | |
| German | de | ✅ | ✅ | |
| Hebrew | he | ✅ | ✅ | Depends on the device; may require third-party text-to-speech |
| Hungarian | hu | — | ✅ | Depends on the device; may require third-party text-to-speech |
| Indonesian | id | — | ✅ | Depends on the device; may require third-party text-to-speech |
| Italian | it | ✅ | ✅ | |
| Japanese | ja | — | ✅ | |
| Korean | ko | ✅ | ✅ | |
| Norwegian | no | — | ✅ | |
| Polish | pl | — | ✅ | |
| Portuguese | pt-PT | ✅ | ✅ | |
| Romanian | ro | — | ✅ | |
| Russian | ru | ✅ | ✅ | |
| Slovenian | sl | — | ✅ | Depends on the device; may require third-party text-to-speech |
| Spanish | es | ✅ | ✅ | |
| Swedish | sv | ✅ | ✅ | |
| Turkish | tr | — | ✅ | |
| Ukrainian | uk | ✅ | ✅ | Depends on the device; may require third-party text-to-speech |
| Vietnamese | vi | ✅ | ✅ | Depends on the device; may require third-party text-to-speech |
| Yoruba | yo | ✅ | ✅ | Depends on the device; may require third-party text-to-speech |
Depends on the device; may require third-party text-to-speech, instructions are provided by the Navigation SDK, but it's not guaranteed that the given device will have the appropriate TextToSpeech speech engine installed to pronounce these instructions correctly.Add a localization
Read the Navigation SDK's contributing guide for detailed instructions on adding a new localization or improving an existing localization.
Voice instruction sources
Turn-by-turn instructions are primarily designed to be announced by either the Mapbox Voice API (powered by Amazon Polly) or by the Android system's TextToSpeech. By default, the Navigation 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 RouteOptions builder as you request routes.
true must be passed though the steps() method if you're going to set a custom language. This true ensures that the Directions API response includes turn-by-turn instructions.
Set the text instructions language:
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.accessToken(mapboxAccessToken)
.coordinates(coordinateList)
.profile(directionsProfile)
.steps(true)
.language(languageCode)
.build()
)
Set voice instruction units of measurement
To override the measurement system used in spoken instructions, pass the desired language through the RouteOptions.builder()'s voiceUnits() method when you request routes.
The units can either be DirectionsCriteria.IMPERIAL (the Navigation SDK's default) or DirectionsCriteria.METRIC.
true must be passed though both the steps() and voiceInstructions() methods if you're going to set a desired unit.
Set the units to imperial:
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.accessToken(mapboxAccessToken)
.coordinates(coordinateList)
.profile(directionsProfile)
.steps(true)
.voiceInstructions(true)
.voiceUnits(DirectionsCriteria.IMPERIAL)
.build()
)
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.