Localization

Localization is a key to making products that can be used across the world and by people who speak different languages. UI Library will provide out of the box support for some languages and capabilities such as RTL. Developers can provide their own localization files to be used for the UI Library.

Learn how to set up the localization correctly using the UI Library in your application.

Prerequisites

Note

For detailed documentation and quickstarts about the Web UI Library visit the Web UI Library Storybook.

Azure Communication UI open source library for Android and the sample application code can be found here

Available Languages

The following is table of CallCompositeSupportedLocale with out of the box translations. If you want to localize the composite, pass the Locale from CallCompositeSupportedLocale into CallCompositeLocalizationOptions as options into CallComposite.

Language CallCompositeSupportedLocale
German CallCompositeSupportedLocale.DE
Japanese CallCompositeSupportedLocale.JA
English CallCompositeSupportedLocale.EN_US
Chinese (Traditional) CallCompositeSupportedLocale.ZH_TW
Spanish CallCompositeSupportedLocale.ES
Chinese (Simplified) CallCompositeSupportedLocale.ZH_CN
Italian CallCompositeSupportedLocale.IT
English (United Kingdom) CallCompositeSupportedLocale.EN_UK
Korean CallCompositeSupportedLocale.KO
Turkish CallCompositeSupportedLocale.TR
Russian CallCompositeSupportedLocale.RU
French CallCompositeSupportedLocale.FR
Dutch CallCompositeSupportedLocale.NL
Portuguese CallCompositeSupportedLocale.PT_BR

Localization Provider

CallCompositeLocalizationOptions is an options wrapper that sets all the strings for UI Library for Android components using a CallCompositeSupportedLocale. By default, all text labels use English strings. If desired CallCompositeLocalizationOptions can be used to set a different language by passing a Locale object from CallCompositeSupportedLocale. Out of the box, the UI library includes a set of Locale usable with the UI components and composites.

You can also obtain list of Locale by the static function CallCompositeSupportedLocale.getSupportedLocales().

Android localization

Usage

To use the CallCompositeLocalizationOptions, specify a CallCompositeSupportedLocale and pass it to the CallCompositeBuilder. For the example below, we'll localize the composite to French.

import com.azure.android.communication.ui.calling.models.CallCompositeLocalizationOptions
import com.azure.android.communication.ui.calling.models.CallCompositeSupportedLocale

// CallCompositeSupportedLocale provides list of supported locale
val callComposite: CallComposite =
            CallCompositeBuilder().localization(
                CallCompositeLocalizationOptions(CallCompositeSupportedLocale.FR)
            ).build()

Layout Direction

Certain cultures (Arabic, Hebrew, etc.) may need for localization to have right-to-left layout. You can specify the layoutDirection as part of the CallCompositeLocalizationOptions. The layout of the composite will be mirrored but the text will remain in the direction of the string.

import com.azure.android.communication.ui.calling.models.CallCompositeLocalizationOptions
import com.azure.android.communication.ui.calling.models.CallCompositeSupportedLocale

// CallCompositeSupportedLocale provides list of supported locale
val callComposite: CallComposite =
            CallCompositeBuilder().localization(
                CallCompositeLocalizationOptions(CallCompositeSupportedLocale.FR, LayoutDirection.LTR)
            ).build()

Azure Communication UI open source library for iOS and the sample application code can be found here

Language Detection

If your application supports localization, the UI Library will be displayed based on user's system preferred language if it's part of the Available Languages listed below. Otherwise will default our predefined English (en) strings.

Available Languages

The following table of locale with out of the box translations. If you want to localize the composite, pass the locale into LocalizationOptions as options into CallComposite.

Language SupportedLocale identifier
Chinese, Simplified zh zh
Chinese, Simplified zhHans zh-Hans
Chinese, Simplified (China mainland) zhHansCN zh-Hans-CN
Chinese, Traditional zhHant zh-Hant
Chinese, Traditional (Taiwan) zhHantTW zh-Hant-TW
Dutch nl nl
Dutch (Netherlands) nlNL nl-NL
English en en
English (United Kingdom) enGB en-GB
English (United States) enUS en-US
French fr fr
French (France) frFR fr-FR
German de de
German (Germany) deDE de-DE
Italian it it
Italian (Italy) itIT it-IT
Japanese ja ja
Japanese (Japan) jaJP ja-JP
Korean ko ko
Korean (South Korea) koKR ko-KR
Portuguese pt pt
Portuguese (Brazil) ptBR pt-BR
Russian ru ru
Russian (Russia) ruRU ru-RU
Spanish es es
Spanish (Spain) esES es-ES
Turkish tr tr
Turkish (Turkey) trTR tr-TR

You can also obtain list of locale by the static function SupportedLocale.values will return list of Locale structs.

let locales: [Locale] = SupportedLocale.values.map{ $0.identifier }
print(locales)

// ["de", "de-DE", "en", "en-GB", "en-US", "es", "es-ES", "fr", "fr-FR", "it", "it-IT", "ja", "ja-JP", "ko", "ko-KR", "nl", "nl-NL", "pt", "pt-BR", "ru", "ru-RU", "tr", "tr-TR", "zh", "zh-Hans", "zh-Hans-CN", "zh-Hant", "zh-Hant-TW"]

LocalizationOptions

LocalizationOptions is an options wrapper that sets all the strings for UI Library components using a locale. By default, all text labels use our English (en) strings. If desired, LocalizationOptions can be used to set a different locale. Out of the box, the UI library includes a set of locale usable with the UI components and composites.

To use the LocalizationOptions, specify a locale Swift Locale struct (with or without a region code), and pass it to the CallCompositeOptions. For the example below, we'll localize the composite to French for France (fr-FR).

// Creating swift Locale struct
var localizationOptions = LocalizationOptions(locale: Locale(identifier: "fr-FR"))

// Use intellisense SupportedLocale to get supported Locale struct
localizationOptions = LocalizationOptions(locale: SupportedLocale.frFR)

let callCompositeOptions = CallCompositeOptions(localization: localizationOptions)
let callComposite = CallComposite(withOptions: callCompositeOptions)

iOS localization

Layout Direction

Certain cultures (Arabic, Hebrew, etc.) may need for localization to have right-to-left layout. You can specify the layoutDirection as part of the LocalizationOptions. The layout of the composite will be mirrored but the text will remain in the direction of the string.

var localizationOptions: LocalizationOptions

// Initializer with locale and layoutDirection
localizationOptions = LocalizationOptions(locale: Locale(identifier: "en"),
                                          layoutDirection: .rightToLeft)

// Initializer with locale, localizableFilename, and layoutDirection
localizationOptions = LocalizationOptions(locale: Locale(identifier: "en"),
                                          localizableFilename: "Localizable",
                                          layoutDirection: .rightToLeft)

// Add localizationOptions as option
let callCompositeOptions = CallCompositeOptions(localization: localizationOptions)
let callComposite = CallComposite(withOptions: callCompositeOptions)

You can see below the right-to-left layout mirroring, by default without specifying layoutDirection will default to false (left-to-right layout).

layoutDirection = .leftToRight (default) layoutDirection = .rightToLeft
iOS layout direction left-to-right iOS layout direction right-to-left

Customizing Translations

There are two options to customize the language translations that we provide. To override a particular string, you can find the list of localization keys here for the key-value pair. You can specify the locale to be one of the supported languages, and when a key isn't provided, will fall back to our supported translation string. If you specified an unsupported language, you should provide translations for all the keys for that language (using Localizable.strings file), and will fall back to English strings when a key isn't provided.

Let's say you wish to have the ControlBar with strings from our English (US) locale but you want to change the label of JoinCall button to "Start Meeting" (instead of "Join call") in Setup View.

Override using Localization.strings file

Enable Localization in the Project, below for the locale you want to override. Create a Localizable.strings file (or other filename with extension .strings) with the key-value pair for selected keys you want to override. In the example below, we're overriding the key AzureCommunicationUI.SetupView.Button.JoinCall.

iOS setup project

iOS custom string

To specify you're overriding with Localization.strings, create a LocalizationOptions object to specify the locale and localizationFilename. Or when using the locale initializer, will look keys in Localizable.strings for locale.collatorIdentifier as the language in your project.

let localizationOptions = LocalizationOptions(locale: Locale(identifier: "fr"),
                                              localizableFilename: "Localizable")
let callCompositeOptions = CallCompositeOptions(localization: localizationOptions)
let callComposite = CallComposite(withOptions: callCompositeOptions)

Accessibility VoiceOver for Localization

For VoiceOver to work properly for a localization, make sure the language is added into your app's Localizations. So the VoiceOver will detect the app supports the language specified in LocalizationOptions locale, and select the Speech voice for the language using the voice found in device's Settings -> Accessibility -> Speech. You can verify if the language is added to your project as shown below.

iOS XCode Project Localizations

Next steps