App-spezifische Spracheinstellungen

</ph>

In vielen Fällen stellen mehrsprachige Nutzer ihre Systemsprache auf eine Sprache ein, z. B. Englisch ist, möchte aber für bestimmte Apps andere Sprachen auswählen, Niederländisch, Chinesisch oder Hindi. Um die Nutzerfreundlichkeit in Apps zu verbessern werden mit Android 13 die folgenden Funktionen für Apps eingeführt, die mehrere Sprachen:

• Systemeinstellungen: An einem zentralen Ort können Nutzer eine bevorzugte Sprache für die jeweilige App.

  Sie können Ihre App so konfigurieren, dass die Dateien automatisch generiert werden, die für unterstützen App-spezifische Spracheinstellungen und werden in den Systemeinstellungen angezeigt. Bis finden Sie in der Anleitung zu Aktivieren der automatischen Sprachunterstützung pro App.

• Zusätzliche APIs: Diese öffentlichen APIs, z. B. die setApplicationLocales() und getApplicationLocales() können Apps in LocaleManager eine andere Sprache als die Systemsprache festlegen.

  Diese APIs werden automatisch mit den Systemeinstellungen synchronisiert. Daher werden Apps, die APIs zum Erstellen benutzerdefinierter In-App-Sprachauswahlen einsetzen, eine einheitliche User Experience zu bieten, unabhängig davon, wo sie ihre Spracheinstellungen. Mit den öffentlichen APIs lässt sich auch die Anzahl der Sie unterstützen unterteilte APKs und sie unterstützen die automatische Sicherung für Apps zum Speichern der Nutzersprache auf App-Ebene Einstellungen.

  Entsprechende APIs für die Abwärtskompatibilität mit früheren Android-Versionen sind auch in AndroidX verfügbar. Die abwärtskompatiblen APIs mit dem AppCompatActivity-Kontext und nicht mit dem Anwendungskontext für Android 12 (API-Level 32) und früher. Zugriff auf abwärtskompatible APIs mit Appcompat 1.6.0 oder höher.

Überblick über die Implementierung dieser Funktion

Die folgende Tabelle zeigt empfohlene Implementierungen für unterschiedliche Verwendungszwecke. Cases.

Systemeinstellungen für Nutzer

Ab Android 13 umfasst Android einen zentralen Ort im System. zum Festlegen der bevorzugten Sprache für einzelne Apps. Damit Ihre App Sprachen können in den Systemeinstellungen auf Geräten mit Android 13 oder Aktivieren Sie die automatische Sprachunterstützung pro App (empfohlen) oder konfigurieren Sie manuell zu unterstützen.

Automatische Unterstützung von Sprachen pro App aktivieren

Ab Android Studio Giraffe und AGP 8.1 kannst du deine App so konfigurieren, dass Unterstützung pro App-Sprache Einstellungen automatisch. Basierend auf Ihren Projektressourcen generiert AGP den LocaleConfig -Datei und fügt in der endgültigen Manifestdatei einen Verweis darauf hinzu, sodass Sie manuell erledigen müssen. AGP verwendet die Ressourcen in den res-Ordnern Ihrer Anwendung Module und alle Abhängigkeiten von Bibliotheksmodulen, um die einzuschließenden Sprachen zu bestimmen in der Datei LocaleConfig. Wenn Sie also Ressourcen für eine neue Sprache für deine App einstellen, musst du dich nicht darum kümmern, die LocaleConfig zu aktualisieren -Datei.

Hinweis: Die automatische Sprachfunktion pro App unterstützt Android-Apps. 13 (API-Level 33) oder höher. Um die Funktion zu verwenden, müssen Sie compileSdkVersion auf 33 oder höher. So konfigurieren Sie die Spracheinstellungen für einzelne Apps bei älteren Android-Versionen müssen Sie APIs und In-App-Sprachauswahl verwenden

So aktivieren Sie die automatische Sprachunterstützung für einzelne Apps:

1. Verwende zum Aktivieren der Funktion die generateLocaleConfig im androidResources {}-Block der Modulebene build.gradle.kts-Datei (build.gradle-Datei, falls Sie mit Groovy). Die Funktion ist standardmäßig deaktiviert.

   Kotlin

       android {
         androidResources {
           generateLocaleConfig = true
         }
       }
       

   Cool

       android {
         androidResources {
           generateLocaleConfig true
         }
       }
       

2. Standardgebietsschema angeben: <ph type="x-smartling-placeholder">
   </ph>
   1. Erstellen Sie im Ordner res des Anwendungsmoduls eine neue Datei mit dem Namen resources.properties.

   2. Legen Sie in der Datei resources.properties den Standardwert fest. mit dem Label unqualifiedResLocale. So formatieren Sie den Hier erfahren Sie, wie Sie Gebietsschemanamen bilden.

AGP fügt diese Standardsprache und alle alternative Sprachen mithilfe von values-*-Verzeichnissen im Ordner res im automatisch generierte LocaleConfig-Datei.

So bilden Sie Gebietsschemanamen

Um Gebietsschemanamen zu bilden, kombinieren Sie den Sprachcode mit dem optionalen Skript und Regionscodes, getrennt durch einen Bindestrich:

• Sprache: Verwenden Sie die aus zwei oder drei Buchstaben bestehenden ISO 639-1 Code.
• Skript (optional): Verwenden Sie das ISO 15924-Code.
• Region (optional): Sie können die aus zwei Buchstaben bestehenden ISO 3166-1-alpha-2 Code oder dreistelliges UN_M.49 Code.

Wenn Ihre Standardsprache beispielsweise „Englisch (USA)“ ist, gehen Sie so vor:

unqualifiedResLocale=en-US

Verwende android:localeConfig, um den Systemeinstellungen unterstützte Sprachen hinzuzufügen

Du kannst deine App manuell so einrichten, dass die Sprachen hier konfiguriert werden können: Systemeinstellungen auf Geräten mit Android 13 oder höher. Erstellen Sie dazu locales_config und füge sie mithilfe des android:localeConfig-Attribut. Manifest android:localeConfig weglassen signalisiert, dass Nutzer nicht in der Lage sein sollten, die Sprache Ihrer App festzulegen unabhängig von der Systemsprache in den Systemeinstellungen verwendet.

So fügen Sie die unterstützten Sprachen Ihrer App den Systemeinstellungen eines Nutzers manuell hinzu:

1. Erstellen Sie eine Datei mit dem Namen res/xml/locales_config.xml und geben Sie die Sprachen, einschließlich der Sprache Ihrer App ultimiertes Fallback-Gebietsschema, Dies ist die in res/values/strings.xml angegebene Sprache.

   Informationen zu den Formatanforderungen finden Sie unter So bilden Sie Gebietsschemanamen. Die Beispieldatei locale_config.xml enthält eine Liste der in den am häufigsten verwendeten Sprachen.

   Formatieren Sie beispielsweise die Datei locales_config.xml für eine App, die unterstützt die folgenden Sprachen:

   • Englisch (USA) als ultimatives Fallback-Gebietsschema
   • Englisch (Vereinigtes Königreich)
   • Französisch
   • Japanisch
   • Chinesisch (vereinfacht, Macau)
   • Chinesisch (traditionell, Macau)

   <?xml version="1.0" encoding="utf-8"?>
   <locale-config xmlns:android="http://schemas.android.com/apk/res/android">
      <locale android:name="en-US"/>
      <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. Fügen Sie im Manifest eine Zeile hinzu, die auf diese neue Datei verweist:

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

Sie können die localeConfig Ihrer App dynamisch mit LocaleManager.setOverrideLocaleConfig zum Anpassen der Sprachen App-Sprache in den Android-Einstellungen angezeigt wird. So können Sie Sprachliste für einzelne Regionen anpassen, A/B-Tests durchführen und aktualisierte Sprachen festlegen, wenn Ihre App serverseitige Lokalisierungs-Pushes verwendet (siehe folgendes Beispiel:

//For setOverrideLocaleConfig
val localeManager = applicationContext
    .getSystemService(LocaleManager::class.java)
localeManager.overrideLocaleConfig = LocaleConfig(
LocaleList.forLanguageTags("en-US,ja-JP,zh-Hans-SG")
)

//For getOverrideLocaleConfig
// The app calls the API to get the override LocaleConfig
val overrideLocaleConfig = localeManager.overrideLocaleConfig
// If the returned overrideLocaleConfig isn't equal to NULL, then the app calls the API to get the supported Locales
val supportedLocales = overrideLocaleConfig.supportedLocales()

//For setOverrideLocaleConfig
mContext.getSystemService(LocaleManager.class).setOverrideLocaleConfig(new LocaleConfig(LocaleList.forLanguageTags("en-US,ja-JP,zh-Hans-SG")));

//For getOverrideLocaleConfig
// The app calls the API to get the override LocaleConfig
LocaleConfig overrideLocaleConfig = mContext.getSystemService(LocaleManager.class).getOverrideLocaleConfig();
// If the returned overrideLocaleConfig isn't equal to NULL, then the app calls the API to get the supported Locales
LocaleList supportedLocales = overrideLocaleConfig.getSupportedLocales();

Außerdem können IMEs jetzt LocaleManager.getApplicationLocales um die Sprache der Benutzeroberfläche der aktuellen App zu erfahren, um die Tastatursprache angezeigt:

val currentAppLocales: LocaleList = applicationContext.getSystemService(LocaleManager::class.java).getApplicationLocales(appPackageName)

LocaleList currentAppLocales =
    mContext.getSystemService(LocaleManager.class).getApplicationLocales(appPackageName);

Unterstützte Sprachen in Gradle angeben

Falls nicht bereits vorhanden, geben Sie dieselben Sprachen mithilfe des resourceConfigurations in der build.gradle-Datei Ihrer App auf Modulebene fest:

android {
  ...
  defaultConfig {
    resourceConfigurations += ["en", "en-rGB", "fr", "ja", "b+zh+Hans+MO", "b+zh+Hant+MO"]
  }
}

Wenn das Attribut resourceConfigurations vorhanden ist, schließt das Build-System nur im APK für diese angegebenen Sprachen enthalten. Dadurch wird verhindert, aus anderen Bibliotheken, die die Übersetzung von übersetzten Strings unterstützen, Sprachen, die deine App nicht unterstützt. Weitere Informationen finden Sie unter Gib die Sprachen an, die deine App unterstützt.

So wählen Nutzer die App-Sprache in den Systemeinstellungen aus

Nutzer können über das System ihre bevorzugte Sprache für jede App auswählen Einstellungen. Sie haben zwei Möglichkeiten, auf diese Einstellungen zuzugreifen:

• Zugriff über die Systemeinstellungen

  Einstellungen > System > Sprachen und Eingabe > App-Sprachen > (App auswählen)

• Zugriff über Apps-Einstellungen

  Einstellungen > Apps > (App auswählen) > Sprache

Umgang mit der In-App-Sprachauswahl

Für Apps, die bereits über eine In-App-Sprachauswahl verfügen oder wenn Sie eine verwenden möchten, verwenden Sie die öffentlichen APIs statt benutzerdefinierter Anwendungslogik, um die Einstellung und den Abruf der bevorzugte Sprache für Ihre App. Wenn Sie die öffentlichen APIs für Ihre In-App verwenden Sprachauswahl werden die Systemeinstellungen des Geräts automatisch auf Die Anzeigen müssen der Sprache entsprechen, die der Nutzer in der App auswählt.

Für die Abwärtskompatibilität mit früheren Android-Versionen empfehlen wir dringend, bei der Implementierung einer In-App-Sprachauswahl mithilfe der AndroidX-Supportbibliothek Sie können die Framework-APIs auch direkt implementieren. wenn nötig.

Implementierung mithilfe der AndroidX-Supportbibliothek

setApplicationLocales() und getApplicationLocales() verwenden Methoden in Appcompat 1.6.0 oder höher. Beachten Sie, dass die abwärtskompatiblen APIs mit dem AppCompatActivity-Kontext funktionieren, und nicht den Anwendungskontext, bei Android 12 (API-Level 32) und früheren Versionen.

Um die bevorzugte Sprache eines Nutzers festzulegen, müssen Sie ihn beispielsweise bitten, wählen Sie in der Sprachauswahl ein Gebietsschema aus und legen dann diesen Wert im System fest:

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);

Hinweis: Durch das Aufrufen von setApplicationLocales() wird Ihr Activity neu erstellt, es sei denn, Ihre App wickelt die Konfiguration des Gebietsschemas ab an sich.

Verwenden Sie AppCompatDelegate.getApplicationLocales(), um das bevorzugte Gebietsschema des Nutzers abzurufen. Der Nutzer hat die Sprache der App möglicherweise in den Systemeinstellungen oder in der Sprachauswahl in der App ausgewählt.

Android 12 und niedriger unterstützen

Wenn Sie Geräte mit Android 12 (API-Level 32) und niedriger unterstützen möchten, teilen Sie AndroidX verarbeitet den Gebietsschemaspeicher durch Festlegen eines autoStoreLocales-Werts auf true und android:enabled bis false im Manifesteintrag für die AppLocalesMetadataHolderService, wie im folgenden Code dargestellt: snippet:

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

Das Festlegen eines autoStoreLocales-Werts auf true führt zu einem blockierenden Lesevorgang im Hauptthread StrictMode diskRead und diskWrite-Verstoß, wenn Sie Thread-Verstöße protokollieren. Weitere Informationen finden Sie unter AppCompatDelegate.setApplicationLocales() .

Benutzerdefinierte Speicherverwaltung

Manifesteintrag fehlt oder autoStoreLocales auf false-Signale gesetzt dass Sie Ihren Speicherplatz selbst verwalten. In diesem Fall müssen Sie die in den gespeicherten Sprachen vor onCreate im Aktivitätslebenszyklus und gattern Sie Aufrufe an AppCompatDelegate.setApplicationLocales() unter Android 12 (API-Level 32) oder darunter.

Wenn Ihre App einen Speicherort mit benutzerdefiniertem Gebietsschema hat, empfehlen wir die Verwendung eines einmaligen eine Übergabe zwischen Ihrer benutzerdefinierten Speicherlösung und autoStoreLocales, Nutzer verwenden Ihre App weiterhin in der Sprache, die sie bevorzugen. Das ist besonders wenn deine App zum ersten Mal ausgeführt wird, nachdem ein Gerät auf Android 13 In diesem Fall können Sie bereits vorhandene, vom Nutzer angeforderte Sprachen indem Sie die Sprachen aus Ihrem benutzerdefinierten Speicher abrufen und die Sprachen an AppCompatDelegate.setApplicationLocales()

Mit den Android Framework APIs implementieren

Auch wenn wir dringend empfehlen, die AndroidX-Supportbibliothek zu verwenden, In-App-Sprachauswahl implementieren, können Sie auch die setApplicationLocales() und getApplicationLocales() im Android-Framework für Geräte mit Android 13 an.

Um die bevorzugte Sprache eines Nutzers festzulegen, müssen Sie ihn beispielsweise bitten, wählen Sie in der Sprachauswahl ein Gebietsschema aus und legen dann diesen Wert im System fest:

// 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

Um die aktuelle bevorzugte Sprache eines Nutzers in der Sprachauswahl anzuzeigen, kann Ihre App den Wert vom System zurückgeben:

// 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

Zusätzliche Best Practices

Beachten Sie die folgenden Best Practices.

Beim Aufruf eines Intents in einer anderen App Sprache berücksichtigen

Mit sprachorientierten Intents können Sie die Sprache angeben, aufgerufene App. Ein Beispiel ist die EXTRA_LANGUAGE der Speech Recognition API.

Beachten Sie den Header „Accept-Language“ für den benutzerdefinierten Chrome-Tab

Erwägen Sie das Hinzufügen des Accept-Language Header über die Browser.EXTRA_HEADERS um beim Aufrufen eines benutzerdefinierten Chrome-Tabs eine Webseite in der Sprache Ihrer App zu öffnen.

Wenn Sie die Spracheinstellungen für einzelne Apps in den Systemeinstellungen entfernen, setzen Sie die Sprache der App auf die Systemsprache zurück

Wenn Sie die Spracheinstellungen Ihrer App aus den Systemeinstellungen entfernen, indem Sie android:localeConfig aus dem AndroidManifest.xml deiner App), können Nutzer nicht die App-Sprache ganz einfach auf die Standardeinstellungen des Systems zurücksetzen.

Wenn Sie android:localeConfig entfernen, sollten Sie daher das in die Systemsprache mit LocaleListCompat.getEmptyLocaleList() oder LocaleList.getEmptyLocaleList() wie im folgenden Code-Snippet dargestellt:

// 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());

Weitere Informationen

Weitere Informationen finden Sie in unseren Codebeispielen, Blogartikeln und Videos.

• Blog: App-spezifische Spracheinstellungen – Teil 1
• Blog: App-spezifische Spracheinstellungen – Teil 2
• Beispiel-Apps
• Video Building for a multilingual world

Beispiel für eine Datei „language_config.xml“

Standardmäßig zeigt Android Übersetzungen auf Systemebene in den Android Open Quellprojekt (AOSP) für einen Standardsatz der am häufigsten verwendeten Sprachen. Die in diesem Abschnitt enthaltene Beispieldatei locale_config.xml zeigt den empfohlenes Format für jede dieser Sprachen. Diese Beispieldatei soll Ihnen dabei helfen. erstellen Sie Ihre eigene locale_config.xml-Datei für die Sprachen, die Ihre App unterstützt.

<?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="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="fil"/> <!-- Filipino -->
   <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="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="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-Hans"/> <!-- Chinese (Simplified) -->
   <locale android:name="zh-Hant"/> <!-- Chinese (Traditional) -->
   <locale android:name="zu"/> <!-- Zulu -->
</locale-config>