애플리케이션에서 UI 라이브러리 지역화

지역화는 전 세계적으로 다른 언어를 사용하는 사람들이 사용할 수 있는 제품을 만드는 핵심입니다. Azure Communication Services UI 라이브러리는 RTL(오른쪽에서 왼쪽으로)과 같은 일부 언어 및 기능에 대한 기본 제공 지원을 제공합니다. 개발자는 UI 라이브러리에 대한 자체 지역화 파일을 제공할 수 있습니다.

이 문서에서는 애플리케이션에서 UI 라이브러리를 사용하여 지역화를 올바르게 설정하는 방법을 알아봅니다.

필수 조건

• 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
• 배포된 Communication Services 리소스. Communication Services 리소스 만들기
• 호출 클라이언트를 사용하도록 설정하는 사용자 액세스 토큰입니다. 사용자 액세스 토큰을 가져옵니다.
• 선택 사항: UI 라이브러리 복합 구성 요소 시작을 위한 빠른 시작을 완료합니다.

지역화 설정

웹 UI 라이브러리에 대한 자세한 설명서 및 빠른 시작은 웹 UI 라이브러리 스토리북을 참조하세요.

자세한 내용은 웹 UI 라이브러리의 지역화를 참조하세요.

자세한 내용은 오픈 소스 Android UI 라이브러리 및 샘플 애플리케이션 코드를 참조하세요.

사용 가능한 언어

다음 표에서는 기본 번역에 대한 CallCompositeSupportedLocale ID를 나열합니다. 복합 구성 요소를 지역화하려면 CallCompositeSupportedLocale에서 Locale 개체를 옵션 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
프랑스어/French	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();

레이아웃 방향

특정 문화권(예: 아랍어 및 히브리어)은 오른쪽에서 왼쪽 레이아웃이 있는 지역화가 필요할 수 있습니다. CallCompositeLocalizationOptions의 일부로 layoutDirection을 지정할 수 있습니다. 복합 구성 요소의 레이아웃은 미러링되지만 텍스트는 문자열 방향으로 유지됩니다.

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에 대한 기본 번역을 나열합니다. 복합 구성 요소를 지역화하려면 LocalizationOptions에서 locale을 옵션으로 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
터키어(튀르키예)	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)

레이아웃 방향

특정 문화권(예: 아랍어 및 히브리어)은 오른쪽에서 왼쪽 레이아웃이 있는 지역화가 필요할 수 있습니다. LocalizationOptions의 일부로 layoutDirection을 지정할 수 있습니다. 복합 구성 요소의 레이아웃은 미러링되지만 텍스트는 문자열 방향으로 유지됩니다.

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)

지역화를 위한 접근성 음성 변환

음성 변환이 지역화에 제대로 작동하려면 언어가 앱의 지역화에 추가되었는지 확인합니다. 그런 다음, 음성 변환은 앱이 locale의 LocalizationOptions에 지정된 언어를 지원하는지 감지합니다. 디바이스의 설정>접근성>음성에 있는 음성을 사용하여 언어에 대한 음성을 선택합니다. 다음 예제와 같이 언어가 프로젝트에 추가되었는지 확인할 수 있습니다.

다음 단계

• UI 라이브러리에 대해 자세히 알아보기