Aby przeprowadzić audyt wszystkich kluczy lokalizacji w aplikacji na Maca, zbuduj odpowiednie cele, sprawdź każdą tabelę ciągów znaków dla wszystkich obsługiwanych języków, a następnie przetestuj warianty komunikatów w uruchomionej aplikacji. Uzupełnienie katalogu i poprawne wyświetlanie w czasie działania wymagają osobnych kontroli.

Ten przepływ pracy jest przeznaczony dla dewelopera utrzymującego aplikację desktopową na Maca w Xcode. Jego konkretnym celem jest przygotowanie możliwego do prześledzenia rejestru brakujących komunikatów, nieukończonych tłumaczeń, nieprawidłowych argumentów i problemów z wyświetlaniem. Przykłady wykorzystują syntetyczne etykiety i liczby; opisują metodę audytu, którą możesz zastosować we własnym projekcie.

Określ, co uznajesz za kompletny komunikat

Zacznij od krótkiego arkusza audytu. Zapisz cel aplikacji, pakiet zasobów, tabelę ciągów znaków, klucz, obsługiwaną lokalizację, wymagane warianty, stan tłumaczenia i wynik w czasie działania. Każdą kombinację pakietu, tabeli i klucza traktuj jako odrębną tożsamość komunikatu, aby identyczny tekst klucza w różnych zasobach nie ukrywał pominięcia.

Apple dokumentuje, że lokalizowalne interfejsy API mogą określać tabelę i pakiet, a zasoby spoza głównego pakietu wymagają właściwego pakietu do wyszukiwania. Sprawdzanie wyłącznie domyślnego pliku Localizable.xcstrings może więc pominąć komunikaty znajdujące się gdzie indziej w aplikacji. Zobacz Przygotowywanie tekstu aplikacji do tłumaczenia.

Sprawdź obsługiwane lokalizacje projektu w edytorze projektu: wybierz projekt w sekcji Project, otwórz Info i sprawdź Localizations. Sprawdź też, które zasoby uczestniczą w tych lokalizacjach. Artykuł Apple Dodawanie obsługi języków i regionów opisuje te ustawienia projektu i wybór zasobów.

W arkuszu możesz użyć syntetycznych aliasów, takich jak Lokalizacja A, Lokalizacja B i Lokalizacja C. Zachowaj mapowanie tych aliasów na rzeczywiste identyfikatory lokalizacji projektu w roboczym rejestrze. Te aliasy to etykiety arkusza, a nie wartości do wpisania w Xcode.

W audycie zastosuj następujące kryteria ukończenia. To proponowana metoda przeglądu, a nie status ukończenia zdefiniowany przez Apple.

Kontrola Dowód do zapisania
Inwentarz Komunikat ma określony cel, pakiet, tabelę i klucz.
Wykrywanie Komunikat jest wyodrębniany z kodu lub celowo utrzymywany ręcznie.
Pokrycie Każda wymagana lokalizacja zawiera potrzebne warianty komunikatu.
Argumenty Każdy argument zachowuje zamierzone znaczenie i zgodny typ.
Czas działania W odpowiednim interfejsie Maca pojawiają się prawidłowy komunikat i wartości.
Rozstrzygnięcie Każde ustalenie zostało naprawione, celowo wyłączone z uzasadnieniem albo pozostaje otwarte.

Zbuduj inwentarz katalogu przed przeglądem tłumaczeń

Otwórz istniejące katalogi ciągów znaków projektu. Jeśli cel nie ma katalogu, udokumentowana przez Apple ścieżka jego utworzenia to File > New > File from Template, a następnie wybór String Catalog. Domyślna nazwa to Localizable; użyj nazwy tabeli oczekiwanej przez kod. Wybierz Product > Build, aby wypełnić i zaktualizować katalog. Zobacz Lokalizowanie tekstu i tworzenie jego wariantów za pomocą katalogu ciągów znaków.

Zbuduj każdy odpowiedni schemat Maca, zamiast traktować pojedynczą udaną kompilację jako kompletny inwentarz. Apple wyjaśnia, że wyodrębnianie wykrywa ciągi znaków dla bieżącego schematu i platformy. Komunikat nieobecny w jednej kompilacji wymaga sprawdzenia, zanim uznasz go za nieużywany. Tę kwestię opisano w Wykrywanie katalogów ciągów znaków.

Sprawdź ustawienie kompilacji Use Compiler to Extract Swift Strings. Apple wyraźnie wymaga jego włączenia, aby eksport lokalizacji obejmował cały lokalizowalny tekst w języku Swift. Jeśli potrzebujesz kopii do przekazania na potrzeby tłumaczenia, wybierz projekt i użyj Product > Export Localizations, a następnie wybierz wymagane lokalizacje. Wyeksportowany pakiet .xcloc to katalog lokalizacji Xcode, odrębny od pojedynczej tabeli ciągów znaków .xcstrings. Zobacz Eksportowanie lokalizacji.

Następnie przejdź przez typowe elementy interfejsu aplikacji desktopowej: główne okno, menu, pasek narzędzi, ustawienia, panele, puste stany i etykiety zależne od liczby. Dla każdego napotkanego komunikatu należącego do aplikacji znajdź wpis w arkuszu. Ta kontrola wsteczna — od widocznego interfejsu do inwentarza — pomaga wykryć tekst, który nie trafił do katalogu.

Nie zakładaj, że wyodrębnianie wykryje dowolne wyrażenie tekstowe. Apple opisuje wyodrębnianie za pomocą lokalizowalnych interfejsów API. Jeśli oczekiwany komunikat jest nieobecny, sprawdź, jak kod go tworzy i przekazuje, zanim ręcznie dodasz drugi wpis. Zobacz Przygotowywanie tekstu aplikacji do tłumaczenia.

Rozróżnij wyodrębnianie, wyszukiwanie i formatowanie w czasie działania

Te operacje odpowiadają na różne pytania. Wyodrębnianie sprawdza, czy Xcode potrafi wykryć komunikat podczas programowania. Wyszukiwanie określa, którego zlokalizowanego zasobu używa uruchomiona aplikacja. Formatowanie w czasie działania dostarcza zmienną treść wyświetlaną przez wybrany komunikat.

W SwiftUI znaczenie ma typ argumentu. Literał taki jak Text("Open collection") uczestniczy w lokalizowanym wyszukiwaniu. Przekazanie zwykłej zmiennej String do odpowiedniego inicjalizatora zwykle wyświetla tę zmienną bez lokalizacji. Apple dokumentuje to rozróżnienie w LocalizedStringKey.

Jawne utworzenie LocalizedStringKey ze zmiennej żąda wyszukania lokalizacji, ale nie dowodzi, że wyodrębnianie podczas kompilacji wykryło każdą możliwą wartość zmiennej. W przypadku kluczy wybieranych dynamicznie porównaj pełny dozwolony zbiór kluczy z katalogiem. Zbadaj każdą niedopasowaną wartość, zamiast polegać na tej, która akurat pojawiła się podczas testu.

Interpolacja ma też znaczenie na poziomie komunikatu. SwiftUI może wyszukać zlokalizowany komunikat zawierający specyfikator formatu i podstawić interpolowaną wartość przed renderowaniem. Apple zaleca interpolację do tworzenia lokalizowalnego tekstu w dokumentacji Text.

Rozważ przykładowy komunikat informujący o liczbie elementów. Katalog przechowuje strukturę lokalizowalnego komunikatu i jego warianty; zmieniająca się liczba należy do zachowania w czasie działania. Testowanie wartości 1 i 24 nie powinno wymagać dwóch niezależnie utrzymywanych kluczy tylko dlatego, że zmieniła się liczba.

Etykieta, która wygląda wiarygodnie, jest słabym dowodem na prawidłowe wyszukiwanie. Apple podaje, że SwiftUI może wyświetlić sam klucz, jeśli nie znajdzie zlokalizowanej wartości. Jeśli klucz jest czytelnym tekstem źródłowym, problem z wyszukiwaniem może wyglądać jak zwykła etykieta. Sprawdź wybraną lokalizację i wpis w katalogu obok wyświetlonego wyniku. Zobacz Przygotowywanie widoków do lokalizacji.

Sprawdź każdy język i każdy wymagany wariant

Pracuj nad jedną tabelą i jedną lokalizacją naraz. Dla każdego komunikatu sprawdź stan tłumaczenia, tekst, argumenty i rozwinięte warianty. Pozostaw nieukończone wiersze otwarte, nawet gdy sąsiednie komunikaty są gotowe.

Przepływ pracy katalogu Apple rozróżnia wpisy New, Needs Review, wpisy przetłumaczone i ciągi Stale. Nieaktualny ciąg nie został już znaleziony w kodzie; wpisy zarządzane ręcznie nie są automatycznie aktualizowane ani usuwane podczas synchronizacji. Zanim usuniesz tłumaczenia, upewnij się, że nieaktualny klucz jest zbędny. Zobacz Wykrywanie katalogów ciągów znaków.

W przypadku komunikatów zależnych od liczby kliknij z klawiszem Control interpolowany klucz i wybierz Vary by Plural. Sprawdź każdą formę dostarczoną przez Xcode dla danej lokalizacji. Wymagane formy mogą się różnić, więc dopasowanie liczby wierszy lokalizacji źródłowej nie wystarcza. Jeśli katalog zawiera warianty zależne od urządzenia, sprawdź wartość dla Maca i wartość ogólną. Apple opisuje oba ustawienia w artykule Lokalizowanie tekstu i tworzenie jego wariantów za pomocą katalogu ciągów znaków.

Sprawdzaj argumenty pod kątem znaczenia i wyglądu. W syntetycznym komunikacie o elementach w grupach ustal, który argument oznacza liczbę elementów, a który liczbę grup. Tłumaczenie może zmienić ich kolejność, ale musi zachować ich znaczenie. Sesja Apple poświęcona katalogom wyjaśnia pozycje argumentów, specyfikatory typów i podstawienia form liczby mnogiej w Wykrywaniu katalogów ciągów znaków.

Dodaj kontekst, gdy krótka etykieta jest niejednoznaczna. Komentarz do Open może wskazywać, że chodzi o czynność wykonywaną na wierszu kolekcji. Parametr comment w SwiftUI przekazuje ten kontekst do danych wyjściowych lokalizacji; Apple opisuje go w Przygotowywaniu widoków do lokalizacji.

Użyj macierzy pokrycia, która pokazuje nieukończone prace

Pojedynczy procent jest przydatny do śledzenia postępu prac nad katalogiem, ale audyt wymaga osobnych kolumn dla pokrycia i zachowania. Poniższy przykład pokazuje dlaczego. Liczby są syntetyczne i oznaczają pary komunikat–lokalizacja, a nie pomiary z aplikacji.

Załóżmy, że inwentarz zawiera 48 wymaganych komunikatów i trzy obsługiwane lokalizacje. Daje to 144 wymagane pary: 48 pomnożone przez 3. Każda para może zawierać dodatkowe gałęzie liczby mnogiej lub warianty urządzenia, które wymagają osobnych kontroli.

Lokalizacja Wymagane pary Ukończone kontrole katalogu Ukończone kontrole czasu działania
Lokalizacja A 48 48 48
Lokalizacja B 48 46 44
Lokalizacja C 48 48 45
Razem 144 142 137

W tym przypadku dwie pary nadal wymagają pracy nad katalogiem, a dla siedmiu nie ukończono jeszcze kontroli w czasie działania. Te grupy mogą się pokrywać, więc ich zsumowanie nie da wiarygodnej liczby odrębnych nieukończonych komunikatów. Przypisz oba ustalenia do odpowiednich wierszy.

Dla każdego nieukończonego wiersza zapisz konkretne następne działanie: znajdź brakujący komunikat źródłowy, uzupełnij gałąź liczby mnogiej, sprawdź argument, zbadaj wybór pakietu lub ponownie obejrzyj interfejs przy mniejszej szerokości. Dzięki temu macierz stanie się listą napraw, a nie ozdobnym raportem postępu.

Uruchom aplikację na Macu w każdej obsługiwanej lokalizacji

Korzystaj z ustawień schematu Xcode, aby powtarzalnie sprawdzać aplikację. Wybierz Product > Scheme > Edit Scheme, zaznacz Run, otwórz Options i wybierz App Language oraz App Region. Zamknij okno dialogowe, wybierz miejsce docelowe uruchomienia na Macu i uruchom aplikację. Powtórz dla obsługiwanych kombinacji ujętych w audycie. Apple opisuje tę sekwencję w artykule Testowanie lokalizacji podczas uruchamiania aplikacji.

Podczas każdego uruchomienia przejdź tę samą ścieżkę w interfejsie. Sprawdź każdy komunikat w odpowiednich stanach: pusta kolekcja, jeden element, kilka elementów i dłuższe syntetyczne etykiety. W przypadku komunikatów z formami liczby mnogiej wybierz dodatkowe wartości potrzebne do sprawdzenia gałęzi obecnych w danej lokalizacji; mały, stały zestaw liczb nie potwierdza pełnego pokrycia gałęzi.

Sprawdź całe zdania, podstawione wartości, zawijanie wierszy, obcinanie tekstu oraz szerokości menu i kontrolek. Gdy komunikat zawiera dwie liczby, zmieniaj je niezależnie. Na przykład zmiana liczby elementów przy stałej liczbie grup ułatwia wykrycie błędnego przypisania argumentu.

Podglądy SwiftUI mogą skrócić cykl napraw. Apple umożliwia ustawienie wartości środowiskowej locale dla podglądu i tworzenie wielu podglądów lokalizacji po dodaniu lub zaimportowaniu tych lokalizacji. Użyj ich, aby ponownie sprawdzić problematyczny widok, a następnie zweryfikuj rzeczywistą ścieżkę w aplikacji. Zobacz Podgląd lokalizacji.

Zakończ audyt, gdy każdy wymagany komunikat–lokalizacja ma udokumentowane rozstrzygnięcie, a niezbędne gałęzie zostały sprawdzone. Zachowaj inwentarz, ścieżkę testowania i nierozstrzygnięte ustalenia razem. Dzięki temu kolejny audyt będzie można przeprowadzić sprawnie: zmieniony komunikat będzie miał znaną lokalizację, oczekiwane argumenty, wymagane warianty i powtarzalny sposób sprawdzenia jego wyświetlania.

Źródła