> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/ja/navigation/v2/llms.txt)

# Localization and internationalization

The Mapbox Navigation SDK supports over a dozen major languages as well as some other locale settings. For a seamless user experience, the SDK's default behavior matches the standard iOS behavior as much as possible, but several customization options are also available for specialized use cases.

## User interface

The Mapbox Navigation SDK's user interface automatically matches your application's language whenever possible. To improve user experience, you should localize your application fully rather than piecemeal. If you want to display a turn-by-turn navigation experience in a language without first localizing your application, you can add the language to your Xcode project's languages and add a stub `Localizable.strings` file to your application target. For more information about preparing your application for additional languages, consult "[Localizing Your App](https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html)" in Apple developer documentation.

Distances, travel times, and arrival times are displayed according to the system language and region settings by default, regardless of the application's language. By default, the measurement system is that of the [spoken instructions](#spoken-instructions). To override the measurement system you have two options:

-   Set the [`NavigationSettings.distanceUnit`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/NavigationSettings.html#/s:16MapboxNavigation0B8SettingsC12distanceUnitSo017NSLengthFormatterE0Vvp) property.
-   Set the [`RouteOptions.distanceMeasurementSystem`](https://docs.mapbox.com/ios/directions/api/2.14.4/Classes/DirectionsOptions.html#/s:16MapboxDirections0B7OptionsC25distanceMeasurementSystemAA0eF0Ovp) property when calculating the route with which to start navigation.

The turn banner names the upcoming road or ramp destination in the local or national language. In some regions, the name may appear in multiple languages or scripts. A label near the bottom bar displays the current road name in the local language as well.

By default, the map inside [`NavigationViewController`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/NavigationViewController.html) displays road labels in the local language, while points of interest and places are displayed in the system's preferred language, if that language is one of the eight supported by the [Mapbox Streets source](https://docs.mapbox.com/vector-tiles/mapbox-streets-v8/#overview). The user can set the system's preferred language in Settings, General Settings, Language & Region.

A standalone [`NavigationMapView`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/NavigationMapView.html) labels roads, points of interest, and places in the language specified by the current style. (The default Mapbox Navigation Day v1 style specifies English.) To match the behavior of the map inside [`NavigationViewController`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/NavigationViewController.html), call the [`NavigationMapView.localizeLabels()`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/NavigationMapView.html#/s:16MapboxNavigation0B7MapViewC14localizeLabelsyyF) method from within [`MapboxMap.onStyleLoaded`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapboxmap/onstyleloaded/):

```swift
var cancellables: Set<AnyCancelable> = []

navigationMapView.mapView.mapboxMap.onStyleLoaded.observeNext { [weak self] _ in
    self?.navigationMapView?.localizeLabels()
}).store(in: &cancellables)
```

## Spoken instructions

Turn instructions are announced in the user interface language when turn instructions are available in that language. Otherwise, if turn instructions are unavailable in that language, they are announced in English instead. To have instructions announced in a language other than the user interface language, set the [`DirectionsOptions.locale`](https://docs.mapbox.com/ios/directions/api/2.14.4/Classes/DirectionsOptions.html#/s:16MapboxDirections0B7OptionsC6locale10Foundation6LocaleVvp) property when calculating the route with which to start navigation. Turn instructions are primarily designed to be announced by either the Mapbox Voice API or the [Speech Synthesis framework](https://developer.apple.com/documentation/avfoundation/speech-synthesis) built into iOS (also known as `AVSpeechSynthesizer` or [VoiceOver](https://support.apple.com/en-us/HT206175)). This SDK uses the Mapbox Voice API by default. If the Voice API lacks support for the turn instruction language, `AVSpeechSynthesizer` announces the instructions instead. The Voice API requires an Internet connection at various points along the route. To have `AVSpeechSynthesizer` announce the instructions regardless of the language, initialize a [`SystemSpeechSynthesizer`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/SystemSpeechSynthesizer.html), then set it to `RouteVoiceController.voiceController`. After that, to apply this customization, set `NavigationOptions.voiceController` which will be used for presented `NavigationViewController`. Neither the Voice API nor `AVSpeechSynthesizer` supports Burmese, Esperanto, Ukrainian, or Vietnamese; for these languages, you must [create an implementation of `SpeechSynthesizing`](https://docs.mapbox.com/ios/ja/navigation/v2/examples/custom-voice-controller/) that uses a third-party speech synthesizer. You may also use `MultiplexedSpeechSynthesizer` to create a "fallback" speech synthesizer functionality with your speech engines of choice.

By default, the SDK provides distances in the predominant measurement system of the system region, which may not necessarily be the same region in which the user is traveling. To override the measurement system used in spoken instructions, set the [`RouteOptions.distanceMeasurementSystem`](https://docs.mapbox.com/ios/directions/api/2.14.4/Classes/DirectionsOptions.html#/s:16MapboxDirections0B7OptionsC25distanceMeasurementSystemAA0eF0Ovp) property when calculating the route with which to start navigation or set it once with the [`NavigationSettings.distanceUnit`](https://docs.mapbox.com/ios/navigation/api/2.21.0/Classes/NavigationSettings.html#/s:16MapboxNavigation0B8SettingsC12distanceUnitSo017NSLengthFormatterE0Vvp) property.

The upcoming road or ramp destination is named according to the local or national language. In some regions, the name may appear in multiple languages or scripts.

## Supported languages

| Language | User interface | [Spoken instructions](https://github.com/Project-OSRM/osrm-text-instructions/) | Remarks |
| --- | --- | --- | --- |
| Arabic | ✅ | ✅ | Uses VoiceOver |
| Burmese | — | ✅ | Requires third-party text-to-speech |
| Catalan | ✅ | — |  |
| Chinese | ✅ Simplified | ✅ Mandarin | Uses VoiceOver |
| Danish | ✅ | ✅ |  |
| Dutch | ✅ | ✅ |  |
| English | ✅ | ✅ |  |
| Esperanto | — | ✅ | Requires third-party text-to-speech |
| Finnish | — | ✅ | Uses VoiceOver |
| French | ✅ | ✅ |  |
| German | ✅ | ✅ |  |
| Greek | ✅ | — |  |
| Hebrew | ✅ | ✅ | Uses VoiceOver |
| Hungarian | ✅ | ✅ | Uses VoiceOver |
| Indonesian | — | ✅ | Uses VoiceOver |
| Italian | ✅ | ✅ |  |
| Japanese | ✅ | ✅ |  |
| Korean | ✅ | ✅ |  |
| Norwegian | — | ✅ |  |
| Portuguese | ✅ | ✅ |  |
| Polish | ✅ | ✅ |  |
| Romanian | — | ✅ |  |
| Russian | ✅ | ✅ |  |
| Slovenian | — | ✅ | Requires third-party text-to-speech |
| Spanish | ✅ | ✅ |  |
| Swedish | ✅ | ✅ |  |
| Turkish | ✅ | ✅ |  |
| Ukrainian | ✅ | ✅ | Requires third-party text-to-speech |
| Vietnamese | ✅ | ✅ | Requires third-party text-to-speech |
| Yoruba | ✅ | ✅ | Requires third-party text-to-speech |

## Contributing

See the [contributing guide](https://github.com/mapbox/mapbox-navigation-ios/blob/v2.21.0/README.md#adding-or-updating-a-localization) for instructions on adding a new localization or improving an existing localization.