將應用程式中的 UI 程式庫當地語系化

當地語系化是製作產品的關鍵，可讓世界各地使用不同語言的人們使用。 Azure 通訊服務 UI 程式庫提供一些語言和功能的現成支援，例如從右至左 (RTL)。 開發人員可提供自己的當地語系化檔案，以便用於 UI 程式庫。

在本文中，您將了解如何在應用程式中使用 UI 程式庫正確設定當地語系化。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• 已部署通訊服務資源。 建立通訊服務資源。
• 用來啟用通話用戶端的使用者存取權杖。 取得使用者存取權杖。
• 選擇性：完成開始使用 UI 程式庫複合元件的快速入門。

設定當地語系化

如需 Web UI 程式庫的詳細文件和快速入門，請參閱 Web UI 程式庫Storybook。

若要深入了解，請參閱 Web UI 程式庫的當地語系化。

如需詳細資訊，請參閱開放原始碼 Android UI 程式庫和範例應用程式程式碼。

可用的語言

下表列出現成翻譯的 CallCompositeSupportedLocale 識別碼。 如果您想要將複合元件當地語系化，請將 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 元件之 Android UI 程式庫的所有字串。 根據預設，所有文字標籤都會使用英文字串。 您可以從 CallCompositeSupportedLocale 傳遞 Locale 物件，以使用 CallCompositeLocalizationOptions 來設定不同的語言。 現成可用的 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	識別碼
簡體中文	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 會偵測應用程式是否支援 LocalizationOptions 中針對 locale 所指定的語言。 它會使用在裝置的 [設定]>[協助工具]>[語音] 中找到的語音，選取語言的語音聲音。 您可確認語言已新增至您的專案，如下列範例所示。

下一步

• 深入了解 UI 程式庫