你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将应用程序中的 UI 库本地化

本地化是制造可由世界各地说不同语言的人使用的产品的关键。 Azure 通信服务 UI 库为某些语言和功能（例如从右到左 (RTL)）提供现成的支持。 开发人员可以为 UI 库提供自己的本地化文件。

在本文中，了解如何在应用程序中使用 UI 库正确设置本地化。

先决条件

• 具有活动订阅的 Azure 帐户。 免费创建帐户。
• 已部署的通信服务资源。 创建通信服务资源。
• 用于启用通话客户端的用户访问令牌。 获取用户访问令牌。
• 可选：完成快速入门：开始使用 UI 库复合项。

设置本地化

有关 Web UI 库的详细文档和快速入门，请参阅 Web UI 库 Storybook。

若要了解详细信息，请参阅 Web UI 库中的本地化。

有关详细信息，请参阅开源 Android UI 库 和示例应用程序代码。

可用语言

下表列出了现用翻译的 CallCompositeSupportedLocale ID。 如果要本地化复合项，请将 Locale 对象从 CallCompositeSupportedLocale 传递到 CallCompositeLocalizationOptions 用作 CallComposite 的选项。

语言	CallCompositeSupportedLocale
阿拉伯语(沙特阿拉伯)	CallCompositeSupportedLocale.AR_SA
德语（德国）	CallCompositeSupportedLocale.DE_DE
英语(美国)	CallCompositeSupportedLocale.EN_US
英语(英国)	CallCompositeSupportedLocale.EN_UK
西班牙语(西班牙)	CallCompositeSupportedLocale.ES_ES
西班牙语	CallCompositeSupportedLocale.ES
芬兰语（芬兰）	CallCompositeSupportedLocale.FI_FI
法语（法国）	CallCompositeSupportedLocale.FR_FR
法语	CallCompositeSupportedLocale.FR
希伯来语（以色列）	CallCompositeSupportedLocale.IW_IL
意大利语（意大利）	CallCompositeSupportedLocale.IT_IT
意大利语	CallCompositeSupportedLocale.IT
日语（日本）	CallCompositeSupportedLocale.JA_JP
日语	CallCompositeSupportedLocale.JA
韩语(韩国)	CallCompositeSupportedLocale.KO_KR
韩语	CallCompositeSupportedLocale.KO
荷兰语（荷兰）	CallCompositeSupportedLocale.NL_NL
荷兰语	CallCompositeSupportedLocale.NL
挪威语（博克马尔语）	CallCompositeSupportedLocale.NB_NO
波兰语（波兰）	CallCompositeSupportedLocale.PL_PL
波兰语	CallCompositeSupportedLocale.PL
葡萄牙语（巴西）	CallCompositeSupportedLocale.PT_BR
葡萄牙语	CallCompositeSupportedLocale.PT
俄语（俄罗斯）	CallCompositeSupportedLocale.RU_RU
俄语	CallCompositeSupportedLocale.RU
瑞典语（瑞典）	CallCompositeSupportedLocale.SV_SE
土耳其语（土耳其）	CallCompositeSupportedLocale.TR_TR
土耳其语	CallCompositeSupportedLocale.TR
中文(简体)	CallCompositeSupportedLocale.ZH_CN
繁体中文	CallCompositeSupportedLocale.ZH_TW
中文	CallCompositeSupportedLocale.ZH

本地化提供程序

CallCompositeLocalizationOptions 是一个选项包装器，它使用 CallCompositeSupportedLocale 设置 Android UI 库组件的所有字符串。 默认情况下，所有文本标签都使用英文字符串。 可使用 CallCompositeLocalizationOptions 通过从 CallCompositeSupportedLocale 中传递 Locale 对象来设置其他语言。 现成的 UI 库包含一组可用于 UI 组件和复合项的 Locale 对象。

还可以使用静态函数 CallCompositeSupportedLocale.getSupportedLocales() 获取 Locale 对象的列表。

若要使用 CallCompositeLocalizationOptions，请指定 CallCompositeSupportedLocale 并将其传递给 CallCompositeBuilder。 以下示例将复合项本地化为法语。

Kotlin

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

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

Java

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

// CallCompositeSupportedLocale provides a list of supported locales
CallComposite callComposite = 
    new CallCompositeBuilder()
        .localization(new CallCompositeLocalizationOptions(CallCompositeSupportedLocale.FR))
        .build();

布局方向

某些区域性（例如阿拉伯语和希伯来语）可能需要本地化才能具有从右到左的布局。 可以将 layoutDirection 指定为 CallCompositeLocalizationOptions 的一部分。 复合项的布局将被镜像，但文本将保留在字符串的方向。

Kotlin

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

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

Java

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

// CallCompositeSupportedLocale provides a list of supported locales
CallComposite callComposite = 
    new CallCompositeBuilder()
        .localization(new CallCompositeLocalizationOptions(CallCompositeSupportedLocale.FR, LayoutDirection.LTR))
        .build();

LayoutDirection.RTL	LayoutDirection.LTR

自定义翻译

有两个选项可用于自定义我们提供的语言翻译。 若要替代键/值对的特定字符串，可使用本地化键的列表。 可以将区域设置指定为受支持的语言之一。 如果未提供键，它将回退到受支持的翻译字符串。 如果指定了不受支持的语言，则应为该语言的所有键提供翻译（使用 string.xml 文件），然后在未提供键时回退到英语字符串。

例如，你希望控件条使用英语（美国）区域设置中的字符串，但希望在设置视图中将“加入通话”按钮的标签更改为“开始会议”。 使用要替代的选定键的键/值对创建一个 string.xml 文件（或其他文件名）。 以下示例替代了键 azure_communication_ui_calling_setup_view_button_join_call。

有关详细信息，请参阅开源 iOS UI 库 和示例应用程序代码。

语言检测

如果应用程序支持本地化，则 UI 库将基于用户系统的首选语言显示（前提是该语言是下述部分中所列的可用语言之一）。 否则，语言默认为预定义的英语 (en) 字符串。

可用语言

下表列出了 locale 的现用翻译。 如果要本地化复合项，请将 locale 传递到 LocalizationOptions 用作 CallComposite 的选项。

语言	SupportedLocale	Identifier
简体中文	zh	zh
简体中文	zhHans	zh-Hans
简体中文（中国大陆）	zhHansCN	zh-Hans-CN
中文，繁体	zhHant	zh-Hant
繁体中文（中国台湾）	zhHantTW	zh-Hant-TW
荷兰语	nl	nl
荷兰语（荷兰）	nlNL	nl-NL
英语	en	en
英语（英国）	enGB	en-GB
英语（美国）	enUS	en-US
法语	fr	fr
法语（法国）	frFR	fr-FR
德语	de	de
德语（德国）	deDE	de-DE
意大利语	it	it
意大利语（意大利）	itIT	it-IT
日语	ja	ja
日语（日本）	jaJP	ja-JP
韩语	ko	ko
韩语（韩国）	koKR	ko-KR
葡萄牙语	pt	pt
葡萄牙语（巴西）	ptBR	pt-BR
俄语	ru	ru
俄语（俄罗斯）	ruRU	ru-RU
西班牙语	es	es
西班牙语(西班牙)	esES	es-ES
土耳其语	tr	tr
土耳其语 (Türkiye)	trTR	tr-TR

还可以使用静态函数 SupportedLocale.values 获取 locale 结构的列表。

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 是一个选项包装器，它使用 locale 设置 UI 库组件的所有字符串。 默认情况下，所有文本标签都使用英文 (en) 字符串。 可以使用 LocalizationOptions 来设置不同的 locale 结构。 现成的 UI 库包含一组可用于 UI 组件和复合项的 locale 结构。

若要使用 LocalizationOptions，请指定 Swift locale 结构（具有或不具有区域代码），并将其传递给 CallCompositeOptions。 以下示例将复合项本地化为法语（法国）(fr-FR)。

// Creating a Swift locale structure
var localizationOptions = LocalizationOptions(locale: Locale(identifier: "fr-FR"))

// Use IntelliSense SupportedLocale to get supported locale structures
localizationOptions = LocalizationOptions(locale: SupportedLocale.frFR)

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

布局方向

某些区域性（例如阿拉伯语和希伯来语）可能需要本地化才能具有从右到左的布局。 可以将 layoutDirection 指定为 LocalizationOptions 的一部分。 复合项的布局将被镜像，但文本将保留在字符串的方向。

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 an option
let callCompositeOptions = CallCompositeOptions(localization: localizationOptions)
let callComposite = CallComposite(withOptions: callCompositeOptions)

以下示例显示了从右到左的布局镜像。 如果未指定 layoutDirection，则默认为 false（从左到右布局）。

layoutDirection = .leftToRight（默认值）	layoutDirection = .rightToLeft

自定义翻译

有两个选项可用于自定义我们提供的语言翻译。 若要替代特定字符串，可以为键/值对使用本地化键的列表。 可以将 locale 指定为受支持的语言之一。 如果未提供键，它会回退到受支持的翻译字符串。 如果指定了不受支持的语言，则应为该语言的所有键提供翻译（使用 Localizable.strings 文件），然后在未提供键时回退到英语字符串。

例如，你希望控件条使用英语（美国）区域设置中的字符串，但希望在设置视图中将“加入通话”按钮的标签更改为“开始会议”。 对于要替代的 locale 实例，请在项目中启用本地化。 使用要替代的选定键的键/值对创建一个 Localizable.strings 文件（或者其他扩展名为 .strings 的文件名）。 以下示例替代了键 AzureCommunicationUI.SetupView.Button.JoinCall。

若要指定使用 Localizable.strings 进行替代，请创建一个 LocalizationOptions 对象来指定 locale 和 localizationFilename。 或者，使用 locale 初始值设定项时，它会在 locale.collatorIdentifier 的 Localizable.strings 中查找键作为项目中的语言。

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

用于本地化的辅助功能 VoiceOver

若要使 VoiceOver 能够正常进行本地化，请确保将语言添加到应用的本地化中。 然后，VoiceOver 检测到应用支持 locale 的 LocalizationOptions 中指定的语言。 它通过在设备上的“设置”>“辅助功能”>“语音”中找到的语音来选择语言的语音。 可以验证语言是否已添加到项目中，如下例所示。

后续步骤

• 详细了解 UI 库