Android to system operacyjny używany na wielu urządzeniach w wielu regionach. Aby Twoja aplikacja mogła docierać do jak największej liczby użytkowników, zawarte w niej treści, czyli tekst, pliki audio, liczby, waluty i obrazy powinny zostać dostosowane do regionów, w których jest używana.
Na tej stronie znajdziesz sprawdzone metody lokalizowania aplikacji na Androida.
Musisz mieć praktyczną wiedzę o Kotlinie i znać ładowanie zasobów Androida, kwestie związane z programowaniem, takie jak cykl życia aktywności, oraz ogólne zasady internacjonalizacji i lokalizacji.
Warto korzystać z platformy zasobów Androida, aby w jak największym stopniu oddzielić zlokalizowane aspekty aplikacji od jej podstawowych funkcji aplikacji.
- Umieść większość lub wszystkie treści interfejsu aplikacji w plikach zasobów, jak opisano na tej stronie i w omówieniu zasobów aplikacji.
- Z kolei zachowanie interfejsu użytkownika jest oparte na kodzie w języku Kotlin. Jeśli na przykład użytkownicy wprowadzają dane, które w zależności od ustawień regionalnych wymagają innego formatowania lub sortowania, możesz użyć języka Kotlin do programowego przetwarzania tych danych. Ta strona nie zawiera informacji o tym, jak dostosować kod oparty na języku Kotlin do różnych regionów.
Ten przewodnik omawia podstawowy system lokalizacji Androida używany we wszystkich aplikacjach na Androida. Aby dowiedzieć się, jak wczytywać te zlokalizowane zasoby w interfejsie Jetpack Compose, zapoznaj się z sekcją Zasoby w Compose.
Krótki przewodnik po lokalizowaniu ciągów tekstowych w aplikacji znajdziesz w artykule Obsługa różnych języków i kultur.
Omówienie: przełączanie zasobów na Androidzie
Zasoby to ciągi tekstowe, dźwięki, grafiki i inne dane statyczne, których potrzebuje Twoja aplikacja na Androida. Aplikacja może zawierać wiele zestawów zasobów, z których każdy jest dostosowany do innej konfiguracji urządzenia. Gdy użytkownik uruchamia aplikację, Android automatycznie wybiera i wczytuje zasoby, które najlepiej pasują do urządzenia.
Ta strona dotyczy lokalizacji i ustawień regionalnych. Pełny opis przełączania zasobów i wszystkich typów konfiguracji, które możesz określić, np. orientacji ekranu lub typu ekranu dotykowego, znajdziesz w artykule Podawanie zasobów alternatywnych.
Podczas pisania aplikacji tworzysz domyślne i alternatywne zasoby, z których będzie ona korzystać. Gdy użytkownicy uruchamiają aplikację, system Android wybiera zasoby do wczytania na podstawie ustawień regionalnych urządzenia.
Aby utworzyć zasoby, umieść pliki w specjalnie nazwanych podkatalogach katalogu res/ projektu.
Dlaczego zasoby domyślne są ważne
Gdy aplikacja jest uruchamiana w dowolnym regionie, dla którego nie podano tekstu w danym języku, Android wczytuje domyślne ciągi znaków z pliku res/values/strings.xml. Jeśli tego domyślnego pliku brakuje lub nie zawiera on ciągu znaków, którego potrzebuje aplikacja, aplikacja nie uruchomi się i wyświetli błąd. Przykład poniżej pokazuje, co może się stać, gdy domyślny plik tekstowy jest niekompletny.
Przykład:
Kod aplikacji oparty na języku Kotlin odwołuje się tylko do 2 ciągów znaków: text_a i text_b. Aplikacja zawiera zlokalizowany plik zasobów (res/values-en/strings.xml), który definiuje text_a i text_b w języku angielskim.
Aplikacja zawiera też domyślny plik zasobów (res/values/strings.xml), który zawiera definicję text_a, ale nie zawiera definicji text_b.
- Gdy ta aplikacja zostanie uruchomiona na urządzeniu, na którym ustawiony jest język angielski, może działać bez problemu, ponieważ
res/values-en/strings.xmlzawiera oba potrzebne ciągi tekstowe. - Jeśli jednak ta aplikacja zostanie uruchomiona na urządzeniu, na którym ustawiono język inny niż angielski, użytkownik zobaczy komunikat o błędzie i przycisk Wymuś zamknięcie. Aplikacja się nie wczytuje.
Aby temu zapobiec, upewnij się, że plik res/values/strings.xml istnieje i zawiera wszystkie potrzebne ciągi znaków. Dotyczy to wszystkich typów zasobów, nie tylko ciągów znaków. Musisz utworzyć zestaw domyślnych plików zasobów zawierających wszystkie zasoby, z których korzysta Twoja aplikacja, takie jak elementy rysunkowe, czcionki czy kolory. Informacje o testowaniu znajdziesz w sekcji Testowanie zasobów domyślnych.
Korzystanie z zasobów do lokalizacji
W tej sekcji omawiamy tworzenie zasobów domyślnych i alternatywnych. Wyjaśniono w nim też, jak zasoby są przypisywane do priorytetów i jak odwoływać się do nich w kodzie.
Tworzenie zasobów domyślnych
Domyślny tekst aplikacji umieść w res/values/strings.xml. W przypadku tych ciągów znaków użyj języka domyślnego, czyli języka, którym posługuje się większość użytkowników aplikacji.
Domyślny zestaw zasobów zawiera też wszystkie domyślne elementy rysowalne i może obejmować inne typy zasobów, takie jak ikony czy ciągi tekstowe. Te zasoby znajdują się w tych katalogach:
res/drawable/: wymagany katalog zawierający co najmniej 1 plik graficzny, który będzie ikoną aplikacji w Google Play.res/xml/: wymagane, jeśli masz jakiekolwiekres/xml-<qualifiers>folderyres/raw/: wymagane, jeśli masz jakiekolwiekres/raw-<qualifiers>foldery
Tworzenie zasobów alternatywnych
W procesie lokalizacji aplikacji ważne jest udostępnianie alternatywnego tekstu w różnych językach. W niektórych przypadkach możesz też udostępniać alternatywne grafiki, dźwięki i inne zasoby specyficzne dla danego regionu.
Aplikacja może określać wiele katalogów res/<qualifiers>/, z których każdy ma inne kwalifikatory. Aby utworzyć zasób alternatywny dla innego ustawienia regionalnego, użyj kwalifikatora, który określa język lub kombinację języka i regionu. Nazwa katalogu zasobów musi być zgodna ze schematem nazewnictwa opisanym w sekcji Dostarczanie zasobów alternatywnych. W przeciwnym razie nie będzie można skompilować aplikacji.
Przykład:
Załóżmy, że domyślnym językiem Twojej aplikacji jest angielski i chcesz przetłumaczyć wszystkie teksty w niej na język francuski, a wszystkie teksty z wyjątkiem tytułu aplikacji na język japoński. W takim przypadku tworzysz 3 pliki strings.xml, z których każdy jest przechowywany w katalogu zasobów specyficznym dla danego języka:
res/values/strings.xml
Zawiera tekst w języku angielskim dla wszystkich ciągów znaków używanych przez aplikację, w tym tekst dla ciągu znaków o nazwietitle.res/values-fr/strings.xml
Zawierają tekst w języku francuskim dla wszystkich ciągów znaków, w tymtitle.res/values-ja/strings.xml
Zawierają tekst w języku japońskim we wszystkich ciągach znaków z wyjątkiemtitle.
Jeśli kod w języku Kotlin odwołuje się do R.string.title, w czasie działania programu nastąpią te zdarzenia:
- Jeśli język urządzenia jest inny niż francuski, Android wczytuje
titlez plikures/values/strings.xml. - Jeśli urządzenie jest ustawione na język francuski, Android wczytuje
titlez plikures/values-fr/strings.xml.
Jeśli urządzenie jest ustawione na język japoński, Android szuka w pliku title
res/values-ja/strings.xml. Ponieważ w tym pliku nie ma takiego ciągu znaków, Android wraca do wartości domyślnej i wczytuje title w języku angielskim z pliku res/values/strings.xml.
Które zasoby mają pierwszeństwo?
Jeśli wiele plików zasobów pasuje do konfiguracji urządzenia, Android stosuje zestaw reguł, aby zdecydować, którego pliku użyć. Wśród kwalifikatorów, które można określić w nazwie katalogu zasobów, język prawie zawsze ma pierwszeństwo.
Przykład:
Załóżmy, że aplikacja zawiera domyślny zestaw grafik i 2 inne zestawy grafik, z których każdy jest zoptymalizowany pod kątem innego ustawienia urządzenia:
res/drawable/
Zawiera domyślną grafikę.res/drawable-small-land-stylus/
Zawiera grafikę zoptymalizowaną pod kątem urządzenia, które oczekuje danych wejściowych z rysika i ma ekran QVGA o niskiej gęstości pikseli w orientacji poziomej.res/drawable-ja/
Zawiera grafikę zoptymalizowaną pod kątem języka japońskiego.
Jeśli aplikacja działa na urządzeniu skonfigurowanym do używania języka japońskiego, Android wczytuje grafikę z res/drawable-ja/, nawet jeśli urządzenie obsługuje rysik i ma ekran QVGA o niskiej gęstości w orientacji poziomej.
Wyjątek: jedynymi kwalifikatorami, które mają pierwszeństwo przed ustawieniami regionalnymi w procesie wyboru, są kod kraju sieci komórkowej (MCC) i kod sieci komórkowej (MNC).
Przykład:
Załóżmy, że masz taką sytuację:
- Kod aplikacji wywołuje
R.string.text_a. - Dostępne są 2 odpowiednie pliki zasobów:
res/values-mcc404/strings.xml, która zawieratext_aw domyślnym języku aplikacji, w tym przypadku w języku angielskim.res/values-hi/strings.xml, który zawieratext_aw języku hindi.
- Aplikacja działa na urządzeniu o tej konfiguracji:
- Karta SIM jest połączona z siecią komórkową w Indiach (MCC 404).
- Język jest ustawiony na hindi (
hi).
Android wczytuje text_a z res/values-mcc404/strings.xml (w języku angielskim), nawet jeśli urządzenie jest skonfigurowane do obsługi języka hindi. Dzieje się tak, ponieważ podczas wyboru zasobów Android preferuje dopasowanie kodu kraju do dopasowania języka.
Proces wyboru nie zawsze jest tak prosty, jak sugerują te przykłady. Bardziej szczegółowy opis tego procesu znajdziesz w artykule Jak Android znajduje najlepiej pasujący zasób. Wszystkie kwalifikatory są opisane i wymienione w kolejności ważności w omówieniu zasobów aplikacji.
Odsyłanie do zasobów w kodzie
W kodzie aplikacji opartym na języku Kotlin odwołujesz się do zasobów za pomocą składni R.resource_type.resource_name lub android.R.resource_type.resource_name.
Więcej informacji znajdziesz w artykule Uzyskiwanie dostępu do zasobów aplikacji.
Zarządzanie ciągami tekstowymi na potrzeby lokalizacji
W tej sekcji znajdziesz sprawdzone metody zarządzania ciągami znaków związanymi z lokalizacją.
Przenieś wszystkie ciągi znaków do pliku strings.xml
Podczas tworzenia aplikacji nie koduj na stałe żadnych ciągów znaków. Zamiast tego zadeklaruj wszystkie ciągi znaków jako zasoby w domyślnym pliku strings.xml, co ułatwi ich aktualizowanie i lokalizowanie. Ciągi znaków w pliku strings.xml można łatwo wyodrębnić, przetłumaczyć i zintegrować z aplikacją, z odpowiednimi kwalifikatorami, bez wprowadzania zmian w skompilowanym kodzie.
Na przykład w Compose możesz wczytać ciąg znaków w ten sposób:
// In the res/values/strings.xml file // <string name="compose">Jetpack Compose</string> // In your Compose code Text( text = stringResource(R.string.compose) )
Jeśli generujesz obrazy z tekstem, umieść te ciągi znaków również w strings.xml i wygeneruj obrazy ponownie po przetłumaczeniu.
Przestrzegaj wytycznych dotyczących ciągów interfejsu użytkownika na Androidzie
Podczas projektowania i tworzenia interfejsów użytkownika zwracaj szczególną uwagę na to, jak komunikujesz się z użytkownikiem. Ogólnie rzecz biorąc, stosuj zwięzły styl, który jest przyjazny, ale krótki, i używaj spójnego stylu w całym interfejsie.
Zapoznaj się z zaleceniami Material Design dotyczącymi stylu pisania i doboru słów i postępuj zgodnie z nimi. Dzięki temu aplikacje będą wyglądać bardziej profesjonalnie, a użytkownicy szybciej zrozumieją interfejs.
W miarę możliwości używaj standardowej terminologii Androida, np. w przypadku elementów interfejsu, takich jak pasek aplikacji, menu opcji, pasek systemowy i powiadomienia. Prawidłowe i spójne używanie terminów związanych z Androidem ułatwia tłumaczenie i zapewnia użytkownikom lepszy produkt końcowy.
Zapewnij wystarczający kontekst dla zadeklarowanych ciągów znaków.
Podczas deklarowania ciągów znaków w pliku strings.xml pamiętaj, aby opisać kontekst, w którym są one używane. Te informacje są dla tłumacza bezcenne i przekład jest dzięki nim lepszej jakości. Ułatwia też efektywne zarządzanie ciągami znaków.
Oto przykład:
<!-- The action for submitting a form. This text is on a button that can fit 30 chars --> <string name="login_submit_button">Sign in</string>
Możesz podać dodatkowe informacje, np.:
- Do czego służy ten ciąg znaków? Kiedy i gdzie jest wyświetlana użytkownikowi?
- Gdzie w interfejsie znajduje się ta opcja? Na przykład tłumaczenia w przypadku przycisków są mniej elastyczne niż w przypadku pól tekstowych.
Oznaczanie części wiadomości, które nie mają być tłumaczone
Często ciągi znaków zawierają tekst, który nie powinien być tłumaczony na inne języki. Typowe przykłady to fragment kodu, symbol zastępczy wartości, symbol specjalny lub nazwa. Podczas przygotowywania ciągów znaków do tłumaczenia wyszukaj i oznacz tekst, który musi pozostać bez zmian, aby tłumacz go nie zmienił.
Aby oznaczyć tekst, który nie ma być tłumaczony, użyj tagu zastępczego <xliff:g>.
Oto przykładowy tag, który wskazuje, że tekstu "%1$s" nie należy zmieniać podczas tłumaczenia, aby nie uszkodzić wiadomości:
<string name="countdown"> <xliff:g id="time" example="5 days">%1$s</xliff:g> until holiday </string>
Podczas deklarowania tagu zmiennej dodaj atrybut ID, który wyjaśnia, do czego służy zmienna. Jeśli aplikacja później zastąpi wartość zmiennej, podaj przykładowy atrybut, aby wyjaśnić oczekiwane użycie.
Oto kilka innych przykładów tagów obiektu zastępczego:
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> <!-- Example placeholder for a special Unicode symbol --> <string name="star_rating">Check out our 5 <xliff:g id="star">\u2605</xliff:g> </string> <!-- Example placeholder for a URL --> <string name="app_homeurl"> Visit us at <xliff:g id="application_homepage">http://my/app/home.html</xliff:g> </string> <!-- Example placeholder for a name --> <string name="prod_name"> Learn more at <xliff:g id="prod_gamegroup">Game Group</xliff:g> </string> <!-- Example placeholder for a literal --> <string name="promo_message"> Please use the "<xliff:g id="promotion_code">ABCDEFG</xliff:g>" to get a discount. </string> ... </resources>
Lista kontrolna lokalizacji
Pełne omówienie procesu lokalizowania i dystrybuowania aplikacji na Androida znajdziesz w artykule Tłumaczenie i lokalizowanie aplikacji.
Wskazówki dotyczące lokalizacji
Podczas lokalizowania aplikacji stosuj się do tych wskazówek.
Zaprojektuj aplikację tak, aby działała w każdym regionie
Nie zakładaj niczego na temat urządzenia, na którym użytkownik uruchamia Twoją aplikację. Może ono mieć sprzęt, którego się nie spodziewasz, lub być ustawione na język, którego nie planujesz lub którego nie możesz przetestować. Zaprojektuj aplikację tak, aby działała normalnie lub w sposób niezakłócony, niezależnie od urządzenia, na którym jest uruchomiona.
Ważne: upewnij się, że aplikacja zawiera pełny zestaw zasobów domyślnych: uwzględnij foldery res/drawable/ i res/values/ bez dodatkowych modyfikatorów w nazwach folderów, które zawierają wszystkie obrazy i teksty potrzebne aplikacji.
Jeśli w aplikacji brakuje choćby jednego zasobu domyślnego, nie będzie ona działać na urządzeniu, na którym ustawiono nieobsługiwany język. Jeśli na przykład w res/values/strings.xml domyślnym pliku brakuje jednego ciągu znaków, którego potrzebuje aplikacja, a użytkownik uruchomi aplikację w nieobsługiwanym języku i spróbuje wczytać res/values/strings.xml, zobaczy komunikat o błędzie i przycisk Wymuś zamknięcie.
Więcej informacji znajdziesz w sekcji Testowanie zasobów domyślnych.
Unikaj tworzenia większej liczby plików zasobów i ciągów tekstowych niż jest to konieczne.
Prawdopodobnie nie musisz tworzyć wersji alternatywnych dla każdego zasobu w aplikacji. Na przykład logo aplikacji zdefiniowane w katalogu res/drawable/ może działać w każdym języku, więc nie musisz tworzyć żadnych alternatywnych plików graficznych.
Nie musisz też tworzyć tekstu alternatywnego dla każdego ciągu znaków. Załóżmy na przykład, że:
- Domyślnym językiem Twojej aplikacji jest angielski amerykański. Każdy ciąg tekstowy używany przez aplikację jest zdefiniowany w języku angielskim (amerykańskim) w pliku
res/values/strings.xml. - W przypadku kilku ważnych wyrażeń chcesz podać pisownię w brytyjskiej odmianie języka angielskiego. Chcesz, aby te alternatywne ciągi znaków były używane, gdy aplikacja działa na urządzeniu w Wielkiej Brytanii.
W tym celu utwórz mały plik o nazwie res/values-en-rGB/strings.xml, który zawiera tylko ciągi znaków różniące się od tych, które są używane, gdy aplikacja działa w Wielkiej Brytanii. W przypadku wszystkich pozostałych ciągów znaków aplikacja wraca do ustawień domyślnych i używa tych zdefiniowanych w pliku res/values/strings.xml.
Użyj LocalConfiguration do ręcznego wyszukiwania regionu.
Możesz wyszukać ustawienia regionalne za pomocą funkcji LocalConfiguration udostępnianej przez Androida, jak pokazano w tym przykładzie:
val locale = LocalConfiguration.current.locales[0]
Korzystanie z usługi tłumaczenia aplikacji
Usługa tłumaczenia aplikacji jest zintegrowana z Konsolą Play. Umożliwia to uzyskanie natychmiastowej wyceny i złożenie zamówienia w firmie tłumaczeniowej. Możesz zamówić tłumaczenia na co najmniej 1 język ciągów tekstowych interfejsu aplikacji, tekstu informacji o aplikacji w Sklepie Play, nazw zakupów w aplikacji i tekstu kampanii reklamowej.
Tłumaczenie ciągów tekstowych z aplikacji za pomocą Gemini
W Androidzie Studio możesz używać Gemini do tłumaczenia zasobów ciągów tekstowych aplikacji bezpośrednio w projekcie. Więcej informacji znajdziesz w artykule Tłumaczenie i lokalizowanie aplikacji.
Testowanie zlokalizowanych aplikacji
Przetestuj zlokalizowaną aplikację na urządzeniu lub za pomocą Android Emulator. W szczególności przetestuj aplikację, aby upewnić się, że zawiera ona wszystkie niezbędne zasoby domyślne.
Testowanie na urządzeniu
Pamiętaj, że urządzenie, na którym testujesz, może znacznie różnić się od urządzeń dostępnych dla konsumentów w innych miejscach. Dostępne na urządzeniu ustawienia regionalne mogą się różnić od tych dostępnych na innych urządzeniach. Rozdzielczość i gęstość ekranu urządzenia mogą się różnić, co może mieć wpływ na wyświetlanie ciągów znaków i elementów rysunkowych w interfejsie.
Aby zmienić region lub język na urządzeniu, użyj aplikacji Ustawienia.
Testowanie za pomocą podglądów z możliwością komponowania
Przed przetestowaniem aplikacji na urządzeniu możesz użyć podglądów funkcji kompozycyjnych w Android Studio, aby przetestować zlokalizowane interfejsy bez wdrażania ich w emulatorze. Aby wyświetlić podgląd interfejsu w różnych językach, użyj adnotacji @Preview (np. @Preview(locale = "fr")). Możesz też przetestować układy od prawej do lewej, określając ustawienia regionalne RTL, np. @Preview(locale = "ar").
Testowanie w emulatorze
Więcej informacji o korzystaniu z emulatora znajdziesz w artykule Uruchamianie aplikacji w emulatorze Androida.
Tworzenie i używanie niestandardowych ustawień regionalnych
„Niestandardowa” lokalizacja to kombinacja języka i regionu, która nie jest wyraźnie obsługiwana przez obraz systemu Android. Możesz sprawdzić, jak aplikacja działa w niestandardowych ustawieniach regionalnych, tworząc je w emulatorze. Możesz to zrobić na 2 sposoby:
- Użyj aplikacji Custom Locale, która jest dostępna na karcie aplikacji. Po utworzeniu niestandardowych ustawień regionalnych przełącz się na nie, dotykając i przytrzymując nazwę ustawień regionalnych.
- Zmień język na niestandardowy w powłoce
adbzgodnie z opisem w sekcji poniżej.
Jeśli ustawisz w emulatorze język, który nie jest dostępny w obrazie systemu Android, system będzie wyświetlany w języku domyślnym. Twoja aplikacja jednak prawidłowo dostosowuje się do ustawień regionalnych.
Zmiana ustawień regionalnych emulatora w powłoce adb
Aby zmienić ustawienia regionalne w emulatorze za pomocą powłoki adb, wykonaj te czynności:
- Wybierz lokalizację, którą chcesz przetestować, i określ jej tag języka BCP-47, np.
fr-CAdla francuskiego kanadyjskiego. - Uruchom emulator.
- W powłoce wiersza poleceń na komputerze hosta uruchom to polecenie:
adb shell
Jeśli masz podłączone urządzenie, możesz określić, że chcesz użyć emulatora, dodając opcję-e:
adb -e shell - W wierszu poleceń
adb(#) uruchom to polecenie:
setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
Zastąp sekcje w nawiasach odpowiednimi kodami z kroku 1.
Aby na przykład przeprowadzić test w języku francuskim (kanadyjskim):
setprop persist.sys.locale fr-CA;stop;sleep 5;start
Spowoduje to ponowne uruchomienie emulatora. Gdy ekran główny pojawi się ponownie, uruchom aplikację. Zostanie ona uruchomiona w nowym języku.
Testowanie zasobów domyślnych
Aby sprawdzić, czy aplikacja zawiera wszystkie potrzebne zasoby tekstowe, wykonaj te czynności:
- Ustaw na emulatorze lub urządzeniu język, którego Twoja aplikacja nie obsługuje. Jeśli na przykład aplikacja zawiera ciągi znaków w języku francuskim w
res/values-fr/, ale nie zawiera ciągów znaków w języku hiszpańskim wres/values-es/, ustaw język emulatora na hiszpański. Za pomocą aplikacji Custom Locale możesz ustawić na emulatorze nieobsługiwane ustawienia regionalne. - Uruchom aplikację.
- Jeśli aplikacja wyświetla komunikat o błędzie i przycisk Wymuś zamknięcie, może to oznaczać, że szuka ciągu znaków, który nie jest dostępny. Upewnij się, że plik
res/values/strings.xmlzawiera definicję każdego ciągu znaków używanego przez aplikację.
Jeśli test się powiedzie, powtórz go w przypadku innych typów konfiguracji. Jeśli na przykład aplikacja ma plik tekstowy o nazwie res/values-land/strings.xml, ale nie zawiera pliku o nazwie res/values-port/strings.xml, ustaw emulator lub urządzenie w orientacji pionowej i sprawdź, czy aplikacja działa.
Dodatkowe materiały
Więcej informacji o lokalizacji znajdziesz w tych materiałach: