앱별 언어 설정

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
시스템 설정의 앱별 언어

다국어 사용자의 경우 시스템 언어는 한 가지 언어(예: 영어)로 설정하지만 특정 앱에는 다른 언어(예: 네덜란드어나 중국어, 힌디어)를 선택하고자 할 수 있습니다. 앱이 이러한 사용자에게 더 나은 환경을 제공할 수 있도록 Android 13에서는 다국어를 지원하는 앱을 위한 다음과 같은 기능을 도입했습니다.

  • 시스템 설정: 사용자가 각 앱의 기본 언어를 선택할 수 있는 중앙 위치입니다.

    앱은 앱의 매니페스트에서 android:localeConfig 속성을 선언하여 시스템에 여러 언어를 지원한다는 것을 알려야 합니다. 자세한 내용은 리소스 파일을 만들고 앱의 매니페스트 파일에서 선언하는 방법에 관한 안내를 참고하세요.

  • 추가 API: 공개 API(예: LocaleManagersetApplicationLocales()getApplicationLocales() 메서드)를 사용하면 앱이 런타임 중 시스템 언어와 다른 언어를 설정할 수 있습니다.

    이러한 API는 시스템 설정과 자동으로 동기화됩니다. 따라서 이러한 API를 사용하여 맞춤 인앱 언어 선택 도구를 만드는 앱은 언어 설정을 선택하는 위치와 관계없이 일관된 사용자 환경을 보장합니다. 또한 공개 API는 상용구 코드의 양을 줄이는 데 도움이 되고, 분할 APK를 지원하며, 앱 수준의 사용자 언어 설정을 저장하도록 앱 자동 백업을 지원합니다.

    이전 Android 버전과의 호환성을 위해 AndroidX에서도 이에 상응하는 API를 사용할 수 있습니다. Appcompat 1.6.0-beta01 이상을 사용하는 것이 좋습니다.

이 기능 구현 개요

다음 표에는 다양한 사용 사례에 기반한 권장되는 구현이 나와 있습니다.

사용 사례 권장되는 구현
앱에 인앱 언어 선택 도구가 없습니다.
  1. 앱 매니페스트에서 android:localeConfig 속성을 사용하여 시스템 설정에 앱의 언어를 추가합니다.
  2. 필요에 따라 인앱 언어 선택 도구를 추가하려면 AndroidX 라이브러리를 사용하고 API 구현을 선택하여 autoStoreLocales를 통한 이전 버전과의 호환성을 지원합니다.
앱에 이미 인앱 언어 선택 도구가 있습니다.
  1. 앱 매니페스트에서 android:localeConfig 속성을 사용하여 시스템 설정에 앱의 언어를 추가합니다.
  2. 공개 API를 사용하도록 앱의 맞춤 로직을 이전하여 사용자에게 일관된 환경을 제공합니다.
  3. 다음과 같은 특수한 사례를 처리합니다.
    1. Android 13을 실행하는 기기에서 앱을 처음 실행할 때 AppCompatDelegate.setApplicationLocales()를 호출합니다.
    2. 다음과 같은 경우 AppCompatDelegate.setApplicationLocales()를 호출하여 사용자가 요청한 기존 언어를 시스템에 제공합니다.

사용자를 위한 시스템 설정

Android 13부터 Android에 앱별 언어 설정을 지정하는 중앙 위치가 시스템 설정에 포함됩니다. Android 13 이상을 실행하는 기기의 시스템 설정에서 앱의 언어를 구성할 수 있도록 하려면 locales_config XML 파일을 만들고 android:localeConfig 속성을 사용하여 앱의 매니페스트에 이 파일을 추가합니다. android:localeConfig 매니페스트 항목 누락은 사용자가 시스템 설정에서 시스템 언어와 상관없이 앱의 언어를 설정할 수 없음을 나타냅니다.

android:localeConfig를 사용하여 지원되는 언어를 시스템 설정에 추가하세요.

앱에서 지원하는 언어를 사용자의 시스템 설정에 추가하려면 다음 단계를 따르세요.

  1. res/xml/locales_config.xml이라는 파일을 만들고 앱의 최종 대체 언어(res/values/strings.xml에 지정된 언어)를 비롯한 앱 언어를 지정합니다.

    언어 이름을 만들려면 언어 코드에 스크립트(선택사항)와 지역 코드(선택사항)를 각각 대시를 사용하여 결합합니다.

    • 언어: 두 글자 또는 세 글자로 된 ISO 639-1 코드를 사용합니다.

    • 스크립트(선택사항): ISO 15924 코드를 사용합니다.

    • 지역(선택사항): 두 글자로 된 ISO 3166-1-alpha-2 코드 또는 3자리로 된 UN_M.49 코드를 사용합니다.

    가장 일반적으로 사용되는 언어 목록은 샘플 locale_config.xml 파일의 권장되는 형식을 참고하세요.

    예를 들어 다음 언어를 지원하는 앱에서 다음과 같이 locales_config.xml 파일의 형식을 지정할 수 있습니다.

    • 영어(미국), 최종 대체 언어
    • 영어(영국)
    • 프랑스어
    • 일본어
    • 중국어(간체, 마카오)
    • 중국어(번체, 마카오)
    <?xml version="1.0" encoding="utf-8"?>
    <locale-config xmlns:android="http://schemas.android.com/apk/res/android">
       <locale android:name="en"/>
       <locale android:name="en-GB"/>
       <locale android:name="fr"/>
       <locale android:name="ja"/>
       <locale android:name="zh-Hans-MO"/>
       <locale android:name="zh-Hant-MO"/>
    </locale-config>
    
  2. 매니페스트에서 이 새 파일을 가리키는 줄을 추가합니다.

    <manifest>
        ...
        <application
            ...
            android:localeConfig="@xml/locales_config">
        </application>
    </manifest>
    

Gradle에서 지원되는 언어 지정

아직 없다면 앱의 모듈 수준 build.gradle 파일에 resConfigs 속성을 사용하여 동일한 언어를 지정합니다.

Groovy

  android {
      defaultConfig {
          ...
          resConfigs "en", "en-GB", "fr", "ja", "zh-Hans-MO", "zh-Hant-MO"
      }
  }
  

Kotlin

  android {
      defaultConfig {
          ...
          resConfigs("en", "en-GB", "fr", "ja", "zh-Hans-MO", "zh-Hant-MO")
      }
  }
  

resConfigs 속성이 있으면 빌드 시스템은 지정된 언어의 APK에만 언어 리소스를 포함하므로 앱에서 지원하지 않는 언어를 지원할 수 있는 다른 라이브러리의 번역된 문자열이 포함되지 않습니다. 자세한 내용은 앱에서 지원하는 언어 지정을 참고하세요.

사용자가 시스템 설정에서 앱 언어를 선택하는 방법

사용자는 시스템 설정을 통해 앱별로 원하는 언어를 선택할 수 있습니다. 이 설정은 다음과 같은 두 가지 방법으로 액세스할 수 있습니다.

  • 시스템 설정을 통해 액세스

    설정 > 시스템 > 언어 및 입력 > 앱 언어 > (앱 선택)

  • 설정을 통해 액세스

    설정 > 앱 > (앱 선택) > 언어

알려진 문제

다음은 앱을 테스트할 때 유의해야 하는 알려진 문제입니다.

  • Android Gradle 플러그인(AGP) 버전 7.3.0-alpha07~7.3.0-beta02 또는 7.4.0-alpha01~7.4.0-alpha03을 사용하는 경우 앱의 매니페스트 파일에서 android:localeConfig를 선언할 때 리소스 연결 실패의 원인이 되는 문제가 발생할 수 있습니다. 이 문제는 AGP 및 Android SDK의 이후 버전에서 해결되었습니다. 이 문제가 발생하면 AGP 7.3.0-beta04 이상 또는 AGP 7.4.0-alpha05 이상과 SDK 버전 33(compileSdk = 33)을 사용하세요.

인앱 언어 선택 도구 처리

이미 인앱 언어 선택 도구가 있거나 이를 사용하려는 앱은 맞춤 앱 로직 대신 공개 API를 사용하여 사용자가 선호하는 앱 언어를 설정하고 가져옵니다. 인앱 언어 선택 도구에 공개 API를 사용하는 경우, 사용자가 인앱 환경을 통해 선택한 언어와 일치하도록 기기의 시스템 설정이 자동으로 업데이트됩니다.

이전 Android 버전과의 호환성을 위해, 인앱 언어 선택 도구를 구현할 때는 AndroidX 지원 라이브러리를 사용하는 것이 좋습니다. 하지만 필요하다면 프레임워크 API를 직접 구현해도 됩니다.

AndroidX 지원 라이브러리를 사용하여 구현

Appcompat 1.6.0-beta01 및 이후 버전의 setApplicationLocales()getApplicationLocales() 메서드를 사용합니다.

예를 들어 사용자가 선호하는 언어를 설정하려면 사용자에게 언어 선택 도구에서 언어를 선택하도록 요청한 후 시스템에서 값을 설정합니다.

Kotlin

val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags("xx-YY")
// Call this on the main thread as it may require Activity.restart()
AppCompatDelegate.setApplicationLocales(appLocale)

자바

LocaleListCompat appLocale = LocaleListCompat.forLanguageTags("xx-YY");
// Call this on the main thread as it may require Activity.restart()
AppCompatDelegate.setApplicationLocales(appLocale);

앱 자체에서 언어 구성 변경을 처리하지 않는 한 setApplicationLocales()를 호출하면 Activity가 다시 생성됩니다.

AppCompatDelegate.getApplicationLocales()를 사용하여 사용자의 기본 언어를 가져옵니다. 사용자가 시스템 설정 또는 인앱 언어 선택 도구에서 앱 언어를 선택했을 수 있습니다.

Android 12 및 이전 버전 지원

Android 12(API 수준 32) 및 이전 버전을 실행하는 기기를 지원하려면 다음 코드 스니펫과 같이 앱의 AppLocalesMetadataHolderService 서비스의 매니페스트 항목에서 autoStoreLocales 값을 true로 설정하고 android:enabledfalse로 설정하여 AndroidX에 언어 저장소를 처리하도록 지시합니다.

<application
  ...
  <service
    android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
    android:enabled="false"
    android:exported="false">
    <meta-data
      android:name="autoStoreLocales"
      android:value="true" />
  </service>
  ...
</application>

autoStoreLocales 값을 true로 설정하면 기본 스레드에서 블로킹 읽기가 발생하고, 스레드 위반을 기록하는 경우 StrictMode diskReaddiskWrite 위반이 발생할 수도 있습니다. 자세한 내용은 AppCompatDelegate.setApplicationLocales()를 참고하세요.

맞춤 저장소 처리

매니페스트 항목을 생략하거나 autoStoreLocalesfalse로 설정하면 자체 저장소를 처리하고 있다고 알리는 것입니다. 이 경우 활동 수명 주기에서 onCreate 전에 저장된 언어를 제공해야 하고 Android 12(API 수준 32) 이하에서 AppCompatDelegate.setApplicationLocales() 호출을 제어해야 합니다.

앱에 맞춤 언어 저장소 위치가 있으면 사용자가 원하는 언어로 앱을 계속 즐길 수 있도록 맞춤 언어 저장소 솔루션과 autoStoreLocales 간에 일회성 핸드오프를 사용하는 것이 좋습니다. 기기가 Android 13으로 업그레이드된 후 앱을 처음 실행하는 경우에 특히 유용합니다. 이 경우 맞춤 저장소에서 언어를 가져와 AppCompatDelegate.setApplicationLocales()에 전달하여 사용자가 요청한 기존 언어를 제공할 수 있습니다.

Android 프레임워크 API를 사용하여 구현

AndroidX 지원 라이브러리를 사용하여 인앱 언어 선택 도구를 구현하는 것이 좋지만 Android 13을 실행하는 기기의 경우 Android 프레임워크에서 setApplicationLocales()getApplicationLocales() 메서드를 사용해도 됩니다.

예를 들어 사용자가 선호하는 언어를 설정하려면 사용자에게 언어 선택 도구에서 언어를 선택하도록 요청한 후 시스템에서 값을 설정합니다.

// 1. Inside an activity, in-app language picker gets an input locale "xx-YY"
// 2. App calls the API to set its locale
mContext.getSystemService(LocaleManager.class
    ).setApplicationLocales(new LocaleList(Locale.forLanguageTag("xx-YY")));
// 3. The system updates the locale and restarts the app, including any configuration updates
// 4. The app is now displayed in "xx-YY" language

언어 선택 도구에 표시할 사용자의 현재 선호 언어를 가져오려면 앱이 시스템에서 값을 다시 가져오면 됩니다.

// 1. App calls the API to get the preferred locale
LocaleList currentAppLocales =
    mContext.getSystemService(LocaleManager.class).getApplicationLocales();
// 2. App uses the returned LocaleList to display languages to the user

추가 권장사항

다음 권장사항에 유의하세요.

다른 앱에서 인텐트를 호출할 때 언어를 고려합니다.

언어 중심 인텐트를 사용하면 호출된 앱의 언어를 지정할 수 있습니다. 한 가지 예로 Speech Recognizer API의 EXTRA_LANGUAGE 기능을 들 수 있습니다.

Chrome 맞춤 탭의 Accept-Language 헤더를 고려합니다.

Chrome 맞춤 탭을 호출할 때 앱의 언어로 웹페이지를 열도록 Browser.EXTRA_HEADERS를 통해 Accept-Language 헤더를 추가하는 것이 좋습니다.

시스템 설정에서 앱별 언어 환경설정을 삭제하는 경우 앱 언어를 시스템 언어로 재설정하세요.

시스템 설정에서 앱의 언어 환경설정을 삭제하면 (앱의 AndroidManifest.xml에서 android:localeConfig를 삭제하는 방식) 사용자가 앱의 언어를 시스템 기본값으로 다시 쉽게 재설정할 수 없습니다.

이러한 이유로 android:localeConfig를 삭제하는 경우 다음 코드 스니펫에 나와 있는 것처럼 LocaleListCompat.getEmptyLocaleList() 또는 LocaleList.getEmptyLocaleList()를 사용하여 앱 언어를 시스템 언어로 재설정하는 것이 좋습니다.

Kotlin

// Use the AndroidX APIs to reset to the system locale for backward and forward compatibility
AppCompatDelegate.setApplicationLocales(
  LocaleListCompat.getEmptyLocaleList()
)

// Or use the Framework APIs for Android 13 and above to reset to the system locale
val context = LocalContext.current
context.getSystemService(LocaleManager::class.java)
  .applicationLocales = LocaleList.getEmptyLocaleList()

자바

// Use the AndroidX APIs to reset to the system locale for backward and forward compatibility
AppCompatDelegate.setApplicationLocales(
  LocaleListCompat.getEmptyLocaleList()
);

// Or use the Framework APIs for Android 13 and above to reset to the system locale
mContext.getSystemService(LocaleManager.class)
  .setApplicationLocales(LocaleList.getEmptyLocaleList());

추가 리소스

자세한 내용은 코드 샘플, 블로그 기사, 동영상을 참고하세요.

locale_config.xml 파일 샘플

기본적으로 Android는 가장 일반적으로 사용되는 표준 언어 세트의 Android 오픈소스 프로젝트 (AOSP)에 시스템 수준 번역을 포함합니다. 이 섹션에 포함된 샘플 locale_config.xml 파일은 이러한 각 언어에 권장되는 형식을 보여줍니다. 앱에서 지원하는 언어 집합에 관한 자체 locale_config.xml 파일을 구성하는 데 도움이 되도록 이 샘플 파일을 참고하세요.

<?xml version="1.0" encoding="utf-8"?>
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
   <locale android:name="af"/> <!-- Afrikaans -->
   <locale android:name="am"/> <!-- Amharic -->
   <locale android:name="ar"/> <!-- Arabic -->
   <locale android:name="as"/> <!-- Assamese -->
   <locale android:name="az"/> <!-- Azerbaijani -->
   <locale android:name="be"/> <!-- Belarusian -->
   <locale android:name="bg"/> <!-- Bulgarian -->
   <locale android:name="bn"/> <!-- Bengali -->
   <locale android:name="bs"/> <!-- Bosnian -->
   <locale android:name="ca"/> <!-- Catalan -->
   <locale android:name="cs"/> <!-- Czech -->
   <locale android:name="da"/> <!-- Danish -->
   <locale android:name="de"/> <!-- German -->
   <locale android:name="el"/> <!-- Greek -->
   <locale android:name="en-AU"/> <!-- English (Australia) -->
   <locale android:name="en-CA"/> <!-- English (Canada) -->
   <locale android:name="en-GB"/> <!-- English (United Kingdom) -->
   <locale android:name="en-IN"/> <!-- English (India) -->
   <locale android:name="en-US"/> <!-- English (United States) -->
   <locale android:name="en-XA"/> <!-- English (Pseudo-Accents) -->
   <locale android:name="es"/> <!-- Spanish (Spain) -->
   <locale android:name="es-US"/> <!-- Spanish (United States) -->
   <locale android:name="et"/> <!-- Estonian -->
   <locale android:name="eu"/> <!-- Basque -->
   <locale android:name="fa"/> <!-- Farsi -->
   <locale android:name="fi"/> <!-- Finnish -->
   <locale android:name="fr"/> <!-- French (France) -->
   <locale android:name="fr-CA"/> <!-- French (Canada) -->
   <locale android:name="gl"/> <!-- Galician -->
   <locale android:name="gu"/> <!-- Gujarati -->
   <locale android:name="hi"/> <!-- Hindi -->
   <locale android:name="hr"/> <!-- Croatian -->
   <locale android:name="hu"/> <!-- Hungarian -->
   <locale android:name="hy"/> <!-- Armenian -->
   <locale android:name="in"/> <!-- Indonesian -->
   <locale android:name="is"/> <!-- Icelandic -->
   <locale android:name="it"/> <!-- Italian -->
   <locale android:name="iw"/> <!-- Hebrew -->
   <locale android:name="ja"/> <!-- Japanese -->
   <locale android:name="ka"/> <!-- Georgian -->
   <locale android:name="kk"/> <!-- Kazakh -->
   <locale android:name="km"/> <!-- Khmer -->
   <locale android:name="kn"/> <!-- Kannada -->
   <locale android:name="ko"/> <!-- Korean -->
   <locale android:name="ky"/> <!-- Kyrgyz -->
   <locale android:name="lo"/> <!-- Lao -->
   <locale android:name="lt"/> <!-- Lithuanian -->
   <locale android:name="lv"/> <!-- Latvian -->
   <locale android:name="mk"/> <!-- Macedonian -->
   <locale android:name="ml"/> <!-- Malayalam -->
   <locale android:name="mn"/> <!-- Mongolian -->
   <locale android:name="mr"/> <!-- Marathi -->
   <locale android:name="ms"/> <!-- Malay -->
   <locale android:name="my"/> <!-- Burmese -->
   <locale android:name="my-MM"/> <!-- Burmese (Myanmar) -->
   <locale android:name="nb"/> <!-- Norwegian -->
   <locale android:name="ne"/> <!-- Nepali -->
   <locale android:name="nl"/> <!-- Dutch -->
   <locale android:name="or"/> <!-- Odia -->
   <locale android:name="pa"/> <!-- Punjabi -->
   <locale android:name="pl"/> <!-- Polish -->
   <locale android:name="pt-BR"/> <!-- Portuguese (Brazil) -->
   <locale android:name="pt-PT"/> <!-- Portuguese (Portugal) -->
   <locale android:name="ro"/> <!-- Romanian -->
   <locale android:name="ru"/> <!-- Russian -->
   <locale android:name="si"/> <!-- Sinhala -->
   <locale android:name="sk"/> <!-- Slovak -->
   <locale android:name="sl"/> <!-- Slovenian -->
   <locale android:name="sq"/> <!-- Albanian -->
   <locale android:name="sr"/> <!-- Serbian (Cyrillic) -->
   <locale android:name="sr-Latn"/> <!-- Serbian (Latin) -->
   <locale android:name="sv"/> <!-- Swedish -->
   <locale android:name="sw"/> <!-- Swahili -->
   <locale android:name="ta"/> <!-- Tamil -->
   <locale android:name="te"/> <!-- Telugu -->
   <locale android:name="th"/> <!-- Thai -->
   <locale android:name="tl"/> <!-- Filipino -->
   <locale android:name="tr"/> <!-- Turkish -->
   <locale android:name="uk"/> <!-- Ukrainian -->
   <locale android:name="ur"/> <!-- Urdu -->
   <locale android:name="uz"/> <!-- Uzbek -->
   <locale android:name="vi"/> <!-- Vietnamese -->
   <locale android:name="zh-CN"/> <!-- Chinese (Simplified) -->
   <locale android:name="zh-HK"/> <!-- Chinese (Hong Kong) -->
   <locale android:name="zh-TW"/> <!-- Chinese (Traditional) -->
   <locale android:name="zu"/> <!-- Zulu -->
</locale-config>