![](https://developer.android.com/static/images/about/versions/13/app-languages.png?authuser=9&hl=pl)
W wielu przypadkach użytkownicy wielojęzyczni ustawiają język systemu na jeden język – jak angielski, ale chcą wybrać inne języki dla konkretnych aplikacji, niderlandzki, chiński lub hindi. Aby zwiększyć wygodę korzystania z aplikacji użytkowników, Android 13 wprowadza te funkcje w przypadku aplikacji obsługujących wiele języków:
Ustawienia systemu: scentralizowane miejsce, w którym użytkownicy mogą wybrać preferowanego języka dla każdej aplikacji.
Możesz skonfigurować aplikację tak, aby automatycznie generowała pliki potrzebne do obsługi preferencji językowych dla poszczególnych aplikacji i są widoczne w ustawieniach systemu. Do więcej informacji znajdziesz w instrukcjach dotyczących włączenie automatycznej obsługi języków dla poszczególnych aplikacji.
Dodatkowe interfejsy API: publiczne interfejsy API, takie jak
setApplicationLocales()
. orazgetApplicationLocales()
. wLocaleManager
, zezwól aplikacjom ustawić w czasie działania inny język niż język systemu.Te interfejsy API są automatycznie synchronizowane z ustawieniami systemowymi. dlatego aplikacje korzystające z technologii tych interfejsów API do tworzenia niestandardowych selektorów języka mają spójne wrażenia użytkownika niezależnie od tego, ustawienia języka. Publiczne interfejsy API pomagają również zmniejszyć ilość stały kod, obsługują dzielone pakiety APK oraz obsługują Automatyczną kopię zapasową Aplikacje do przechowywania języka użytkownika na poziomie aplikacji. ustawieniach.
Aby zapewnić zgodność wsteczną z poprzednimi wersjami Androida, odpowiednie interfejsy API są też dostępne na Androidzie X. Zgodne wstecznie interfejsy API działają jednak na podstawie kontekstu AppCompatActivity, a nie aplikacji, w przypadku Androida 12 (poziom interfejsu API 32) i starsze. Dostęp do zgodnych wstecznie interfejsów API za pomocą Appcompat 1.6.0 lub wyższą.
Omówienie implementacji tej funkcji
W tabeli poniżej znajdziesz zalecane implementacje w zależności od użycia przypadków.
Przypadek użycia | Zalecana implementacja |
---|---|
Twoja aplikacja nie ma selektora języka |
|
Twoja aplikacja ma już selektor języka |
|
Ustawienia systemu dla użytkowników
Począwszy od Androida 13, Android zapewnia scentralizowaną lokalizację w systemie ustawienia preferencji językowych dla poszczególnych aplikacji. Aby upewnić się, że języki można skonfigurować w ustawieniach systemowych na urządzeniach z Androidem 13 lub włącz automatyczną obsługę języków dla poszczególnych aplikacji (zalecane) lub skonfiguruj można włączyć ręcznie.
Włącz automatyczną obsługę języków w poszczególnych aplikacjach
Począwszy od Androida Studio Giraffe i AGP 8.1, możesz skonfigurować aplikację tak,
obsługa języka według aplikacji
ustawienia
automatycznie. Na podstawie zasobów projektu AGP generuje LocaleConfig
i dodaje odwołanie do jego ostatecznego pliku manifestu, dzięki czemu nie jest on już
musisz zrobić to ręcznie. AGP używa zasobów z folderów res
Twojej aplikacji
i wszelkie zależności modułów biblioteki pozwalające określić języki do uwzględnienia
w pliku LocaleConfig
. Oznacza to, że jeśli dodasz zasoby do nowej witryny,
Język aplikacji, nie musisz się więc przejmować aktualizacją aplikacji LocaleConfig
.
.
Pamiętaj, że funkcja automatycznego określania języka według aplikacji obsługuje aplikacje na Androida.
13 (poziom API 33) lub wyższy. Aby korzystać z tej funkcji, musisz skonfigurować
compileSdkVersion
do 33 lub więcej. Aby skonfigurować ustawienia języka według aplikacji
w poprzednich wersjach Androida, musisz też
korzystać z interfejsów API i selektorów języka w aplikacji.
Aby włączyć automatyczną obsługę języków w poszczególnych aplikacjach, wykonaj te czynności:
- Aby włączyć tę funkcję, użyj opcji
generateLocaleConfig
w blokuandroidResources {}
na poziomie modułubuild.gradle.kts
(build.gradle
plik w przypadku za pomocą Groovy'ego). Ta funkcja jest domyślnie wyłączona.Kotlin
android { androidResources { generateLocaleConfig = true } }
Odlotowe
android { androidResources { generateLocaleConfig true } }
- Określ język domyślny:
- W folderze
res
modułu aplikacji utwórz nowy plik o nazwieresources.properties
W pliku
resources.properties
ustaw wartość domyślną język z etykietąunqualifiedResLocale
. Aby sformatować Aby dowiedzieć się więcej, przeczytaj artykuł Tworzenie nazw regionalnych.
- W folderze
AGP dodaje ten domyślny język i wszystkie
alternatywnych języków
przy użyciu values-*
katalogów w folderze res
,
automatycznie wygenerowany plik LocaleConfig
.
Jak tworzyć nazwy języków
Aby utworzyć nazwy ustawień regionalnych, połącz kod języka z opcjonalnym skryptem i kodów regionów, oddzielając każdy z nich łącznikiem:
- Język: użyj dwu- lub trzyliterowego ISO 639-1 w kodzie.
- Skrypt (opcjonalnie): użyj kod ISO 15924.
- Region (opcjonalnie): użyj ISO 3166-1-alfa-2 kod lub 3-cyfrowy ciąg UN_M.49 w kodzie.
Jeśli na przykład domyślnym językiem jest amerykański angielski:
unqualifiedResLocale=en-US
Użyj android:localeConfig
, aby dodać obsługiwane języki do ustawień systemu
Możesz ręcznie skonfigurować aplikację, aby mieć pewność, że jej języki można skonfigurować w
ustawień systemu na urządzeniach z Androidem 13 lub nowszym. Aby to zrobić, utwórz
locales_config
i dodaj go jako plik manifestu aplikacji za pomocą polecenia
android:localeConfig
. Pomijam plik manifestu android:localeConfig
sygnały wejściowe, że użytkownicy nie powinni mieć możliwości ustawienia języka aplikacji
niezależnie od języka systemu w ustawieniach systemu.
Aby ręcznie dodać obsługiwane języki aplikacji do ustawień systemowych użytkownika:
Utwórz plik o nazwie
res/xml/locales_config.xml
i określ języków, w tym ostateczny język zastępczy, czyli języka ustawionego w:res/values/strings.xml
.Zobacz Jak tworzyć nazwy języków, aby zapoznać się z wymaganiami związanymi z formatem. Zobacz też przykładowy
locale_config.xml
plik, aby zobaczyć listę: z najczęściej używanych regionów.Na przykład sformatuj plik
locales_config.xml
w ten sposób dla aplikacji, która obsługuje następujące języki:- Najlepszym językiem zastępczym jest angielski (Stany Zjednoczone)
- angielski (Wielka Brytania)
- Francuski
- japoński
- chiński (uproszczony, Makau)
- chiński (tradycyjny, Makau)
<?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>
W pliku manifestu dodaj wiersz wskazujący nowy plik:
<manifest> ... <application ... android:localeConfig="@xml/locales_config"> </application> </manifest>
Możesz dynamicznie aktualizować w aplikacji localeConfig
za pomocą
LocaleManager.setOverrideLocaleConfig
, aby dostosować zestaw języków
wyświetlane na liście języków według aplikacji w Ustawieniach Androida. Dzięki temu możesz:
dostosować listę języków według regionu, przeprowadzać eksperymenty A/B oraz aktualizować
jeśli aplikacja wykorzystuje komunikaty push lokalizacji po stronie serwera, tak jak w przypadku
następujący przykład:
Kotlin
//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()
Java
//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();
Dodatkowo IME mogą teraz używać
LocaleManager.getApplicationLocales
Żeby poznać język interfejsu bieżącej aplikacji i zaktualizować język klawiatury,
wyświetlono:
Kotlin
val currentAppLocales: LocaleList = applicationContext.getSystemService(LocaleManager::class.java).getApplicationLocales(appPackageName)
Java
LocaleList currentAppLocales = mContext.getSystemService(LocaleManager.class).getApplicationLocales(appPackageName);
Określanie obsługiwanych języków w Gradle
Jeśli te warunki nie zostały jeszcze uwzględnione, określ je za pomocą atrybutu
resourceConfigurations
w pliku build.gradle
na poziomie modułu aplikacji:
android {
...
defaultConfig {
resourceConfigurations += ["en", "en-rGB", "fr", "ja", "b+zh+Hans+MO", "b+zh+Hant+MO"]
}
}
Jeśli jest dostępna właściwość resourceConfigurations
, system kompilacji zawiera tylko
zasób językowy w pakiecie APK dla tych języków, co uniemożliwia
przetłumaczonych ciągów tekstowych z innych bibliotek, które mogą obsługiwać
języków, których Twoja aplikacja nie obsługuje. Więcej informacji:
określić języki, które obsługuje Twoja aplikacja.
Jak użytkownicy wybierają język aplikacji w ustawieniach systemowych
Użytkownicy mogą wybrać preferowany język każdej aplikacji w systemie ustawieniach. Dostęp do tych ustawień mogą uzyskać na 2 sposoby:
Dostęp poprzez ustawienia systemu
Ustawienia > System > Języki Wejście > Języki aplikacji > (wybierz aplikację)
Dostęp przez ustawienia aplikacji
Ustawienia > Aplikacje > (wybierz aplikację) > Język
Obsługa selektorów języka w aplikacji
W przypadku aplikacji, które mają już selektor języka w aplikacji lub chcą go użyć, użyj publicznych interfejsów API zamiast niestandardowej logiki aplikacji do obsługi ustawień i pobierania preferowany język Twojej aplikacji. Jeśli w swojej aplikacji używasz publicznych interfejsów API selektor języka, ustawienia systemowe urządzenia zostaną automatycznie zmienione na pasują do języka wybranego przez użytkownika w aplikacji.
Dla zachowania zgodności wstecznej z poprzednimi wersjami Androida zdecydowanie zalecamy korzystając z biblioteki pomocy AndroidaX przy implementacji selektora języka w aplikacji. Możesz też bezpośrednio wdrożyć interfejsy API platformy. w razie potrzeby.
Implementacja z użyciem biblioteki pomocy AndroidaX
Użyj narzędzi setApplicationLocales()
i getApplicationLocales()
w Appcompat 1.6.0.
lub wyższą. Pamiętaj, że zgodne wstecznie interfejsy API współpracują z kontekstem AppCompatActivity.
a nie kontekstu aplikacji, na Androidzie 12 (poziom interfejsu API 32) i starszych.
Aby na przykład ustawić preferowany język użytkownika, należy go poprosić o wybierz ustawienia regionalne w selektorze języka, a potem ustaw tę wartość w systemie:
Kotlin
val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags("xx-YY") // Call this on the main thread as it may require Activity.restart() AppCompatDelegate.setApplicationLocales(appLocale)
Java
LocaleListCompat appLocale = LocaleListCompat.forLanguageTags("xx-YY"); // Call this on the main thread as it may require Activity.restart() AppCompatDelegate.setApplicationLocales(appLocale);
Pamiętaj, że wywołanie metody setApplicationLocales()
spowoduje odtworzenie elementu Activity
, chyba że
aplikacja obsługuje konfigurację języka
same się zmienia.
Użyj AppCompatDelegate.getApplicationLocales()
, aby pobrać język preferowany przez użytkownika. Użytkownik mógł wybrać język aplikacji w ustawieniach systemu lub w selektorze języka w aplikacji.
Obsługa Androida 12 i starszych wersji
Aby zapewnić obsługę urządzeń z Androidem 12 (poziom interfejsu API 32) lub starszym,
AndroidX obsługuje pamięć masową języka, ustawiając wartość autoStoreLocales
na
true
i android:enabled
do false
we wpisie manifestu aplikacji
Usługa AppLocalesMetadataHolderService
zgodnie z poniższym kodem
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>
Pamiętaj, że ustawienie wartości autoStoreLocales
na true
powoduje zablokowanie odczytu
w wątku głównym i może spowodować
StrictMode
diskRead
i
Naruszenie zasad: diskWrite
, jeśli rejestrujesz naruszenia wątków. Zobacz
AppCompatDelegate.setApplicationLocales()
.
Niestandardowa obsługa pamięci masowej
Pominięcie wpisu w pliku manifestu lub ustawienie autoStoreLocales
na false
sygnały
że obsługujesz własną pamięć masową. W takim przypadku musisz podać atrybut
zapisane języki przed onCreate
w cyklu życia aktywności i wywołania bramki w
AppCompatDelegate.setApplicationLocales()
na Androidzie 12 (poziom interfejsu API 32) lub
obniżysz się.
Jeśli Twoja aplikacja ma niestandardową lokalizację przechowywania, zalecamy użycie
między Twoim rozwiązaniem do przechowywania danych dla regionu a usługą autoStoreLocales
,
użytkownicy mogą nadal korzystać z aplikacji w preferowanym przez nich języku. Jest to szczególnie ważne,
ma zastosowanie w przypadku pierwszego uruchomienia aplikacji po przejściu na
Android 13. W takim przypadku możesz podać istniejące wcześniej języki wymagane przez użytkowników.
Pobierając języki z pamięci niestandardowej i przekazując je do
AppCompatDelegate.setApplicationLocales()
Implementacja z wykorzystaniem interfejsów API platformy Android
Zdecydowanie zalecamy korzystanie z biblioteki pomocy AndroidaX
implementacji selektorów języka w aplikacji, możesz też użyć
setApplicationLocales()
i getApplicationLocales()
w środowisku Androida na urządzeniach z Androidem 13.
Aby na przykład ustawić preferowany język użytkownika, należy go poprosić o wybierz ustawienia regionalne w selektorze języka, a potem ustaw tę wartość w systemie:
// 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
Aby wyświetlać w selektorze języka obecnie preferowany język użytkownika, aplikacja może odzyskać wartość z systemu:
// 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
Dodatkowe sprawdzone metody
Weź pod uwagę te sprawdzone metody.
Wywołując intencje w innej aplikacji, weź pod uwagę język
Intencje związane z językiem mogą umożliwiać określenie języka,
wywołano aplikację, która ma być w nim dostępna. Jednym z przykładów jest
EXTRA_LANGUAGE
z interfejsu Speech Adaptive API.
Rozważ użycie nagłówka Accept-Language na karcie niestandardowej w Chrome
Rozważ dodanie nagłówka Accept-Language
przez Browser.EXTRA_HEADERS
, aby otworzyć stronę internetową w języku aplikacji podczas wywoływania niestandardowej karty Chrome.
Jeśli usuniesz ustawienia języka według aplikacji w ustawieniach systemowych, zresetuj język aplikacji do systemowego
Jeśli usuniesz ustawienia języka aplikacji z ustawień systemu (przez usunięcie
android:localeConfig
z konta AndroidManifest.xml
w Twojej aplikacji), użytkownicy nie mogą
łatwo przywrócić domyślny język aplikacji.
Dlatego, jeśli usuniesz android:localeConfig
, rozważ zresetowanie
ustawienia regionalne aplikacji na język systemu za pomocą
LocaleListCompat.getEmptyLocaleList()
.
lub
LocaleList.getEmptyLocaleList()
jak widać w tym fragmencie kodu:
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()
Java
// 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());
Dodatkowe materiały
Aby uzyskać dodatkowe informacje, zapoznaj się z naszymi przykładami kodu, artykułami na blogu i filmami.
- Ustawienia języka według aplikacji (część 1) – post na blogu
- Ustawienia języka według aplikacji (część 2) – post na blogu
- Przykładowe aplikacje
- Tworzenie treści pod kątem wielojęzycznego świata – film
Przykładowy plik locale_config.xml
W Android Open domyślnie umieszcza się tłumaczenia na poziomie systemu
Projekt źródłowy (AOSP) dla standardowego zestawu najczęściej używanych języków.
Przykładowy plik locale_config.xml
zawarty w tej sekcji zawiera
dla każdego z tych języków. Użyj tego przykładowego pliku, aby uzyskać pomoc
samodzielnie utworzysz plik locale_config.xml
dla zestawu języków,
obsługiwane przez Twoją aplikację.
<?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>