Aby usunąć nieużywane klucze lokalizacyjne w Xcode, traktuj wpisy Stale jako kandydatów do weryfikacji. Przed usunięciem sprawdź, czy klucze są konstruowane w czasie działania, zachowaj wymagane dynamiczne komunikaty jako wpisy zarządzane ręcznie i po porządkach przetestuj ekrany aplikacji Mac, których dotyczy zmiana.

Ten poradnik jest przeznaczony dla programisty utrzymującego aplikację Mac w SwiftUI, która korzysta z katalogów ciągów. Zadanie polega na uporządkowaniu jednego katalogu: wskazaniu komunikatów, które można usunąć, przy zachowaniu etykiet i komunikatów licznikowych nadal wyświetlanych przez aplikację. Poniższa pomoc w podejmowaniu decyzji oddziela dowody ekstrakcji od zachowania w czasie działania.

Co właściwie oznacza nieaktualny klucz lokalizacyjny?

Xcode wykrywa ciągi podlegające lokalizacji podczas kompilacji. Apple wyjaśnia, że ekstrakcja obejmuje bieżący schemat i platformę. Gdy wcześniej wyodrębniony ciąg znika, Xcode może automatycznie usunąć nieprzetłumaczony wpis; wpis z tłumaczeniami pozostaje i otrzymuje stan Stale. Ten stan oznacza, że Xcode nie znajduje już ciągu w kodzie. Apple wyraźnie uzależnia usunięcie od potwierdzenia, że ciąg nie jest już potrzebny. Odkrywanie katalogów ciągów

W praktyce brak odwołania w kodzie źródłowym rozpoczyna dochodzenie. Dokładne wyszukanie panel.compact może znaleźć odwołanie literalne, ale nie pozwoli ustalić, czy kod konstruuje ten klucz przez połączenie panel. z wybranym trybem. Sprawdź zarówno podejrzany klucz, jak i kod tworzący klucze wyszukiwania.

Dla każdego kandydata użyj poniższej tabeli weryfikacyjnej. To pomoc w podejmowaniu decyzji oparta na udokumentowanych granicach ekstrakcji, a nie dodatkowa funkcja Xcode.

Dowody znalezione podczas weryfikacji Decyzja Następne działanie
Jedynym odbiorcą był usunięty ekran; nie pozostał żaden element tworzący klucz w czasie działania Kandydat do usunięcia Usuń wpis, a następnie ponownie skompiluj i sprawdź zmianę
Kod działający w czasie wykonania może nadal utworzyć dokładnie ten klucz Zachowaj Zachowaj wpis, zarządzając nim ręcznie, albo zastąp wyszukiwanie jawnymi odwołaniami lokalizowanymi
Klucz jest nadal używany w innym celu kompilacji lub przy innym warunku kompilacji Zachowaj Skompiluj i sprawdź odpowiednią konfigurację
Podobnie nazwany klucz istnieje w innej tabeli Sprawdź osobno Potwierdź tabelę i pakiet zasobów używane przez każde wyszukiwanie
Nie znaleziono odbiorcy, ale nie wiadomo, jak kod tworzy klucz Odłóż decyzję Prześledź sposób tworzenia klucza przed podjęciem decyzji o usunięciu

Jak ustalić przydatny punkt odniesienia w Xcode?

Najpierw zapisz możliwą do odzyskania kopię katalogu albo zatwierdź jego bieżący stan. Następnie otwórz projekt aplikacji i wybierz schemat Mac, który chcesz sprawdzić. Zapisz, które cele i konfiguracje warunkowe mogą dostarczać komunikaty do interfejsu, którego dotyczy zmiana; dzięki temu weryfikacja będzie miała jasno określony zakres.

Wybierz katalog w nawigatorze projektu i kliknij Product > Build. Apple dokumentuje, że kompilacja wypełnia i aktualizuje katalogi ciągów na podstawie lokalizowalnego tekstu źródłowego. Po zaznaczeniu katalogu wybierz Editor > Assistant, a następnie klucz, aby sprawdzić jego lokalizację w kodzie źródłowym. Katalog umożliwia też przejście do kodu źródłowego. Lokalizowanie i różnicowanie tekstu za pomocą katalogu ciągów

Jeśli oczekiwanych ciągów w Swift brakuje, sprawdź, czy ustawienie kompilacji Use Compiler to Extract Swift Strings jest włączone dla celu. Apple dokumentuje ten warunek wstępny ekstrakcji kompilatorem. Katalog wypełniony niekompletnymi danymi z ekstrakcji to słaby punkt odniesienia przy decyzji, co usunąć. Lokalizowanie aplikacji SwiftUI

Dla każdego kandydata zapisz klucz, katalog, podejrzewanego odbiorcę i decyzję. Najpierw wyszukaj dokładny klucz, a następnie jego stabilny prefiks i odpowiednie mechanizmy lokalizacji. Sprawdź wartości modelu oraz dane wyszukiwania z pakietu, które zasilają te mechanizmy. Powtórz odpowiednie kompilacje, jeśli inny cel lub warunek kompilacji zmienia uwzględniany kod źródłowy.

Nie łącz decyzji tylko dlatego, że dwa wpisy wyświetlają ten sam tekst. Interfejsy API lokalizacji Apple przyjmują nazwy tabel, a zasoby spoza głównej aplikacji mogą wymagać innego pakietu. Zanim uznasz inny wpis za zamiennik, prześledź tabelę i pakiet używany do wyszukiwania. Przygotowywanie tekstu aplikacji do tłumaczenia

Jak zachować komunikaty wskazywane dynamicznie?

Apple opisuje zarządzanie ręczne jako rozwiązanie przeznaczone w szczególności dla ciągów, których klucze są konstruowane dynamicznie. Zaznacz wymagany wpis i w inspektorze ustaw go jako zarządzany ręcznie. Takie wpisy nie są aktualizowane ani usuwane przez synchronizację lokalizacji Xcode po kompilacji. W przypadku brakującego wpisu dynamicznego Apple pokazuje również, jak dodać ręcznie zarządzany ciąg za pomocą przycisku plusa w katalogu. Odkrywanie katalogów ciągów

Ręczne zarządzanie wymaga jawnej zasady utrzymania. Zapisz prawidłowe klucze obok kodu lub danych, które je wybierają, i opisz ich zastosowanie w komentarzach katalogu. Gdy później usuniesz obsługiwany tryb, sprawdź również jego ręcznie zarządzany wpis; automatyczna ekstrakcja nie posprząta go za Ciebie.

Sprawdź, czy SwiftUI faktycznie wyszukuje tłumaczenie

Zmienna typu String przekazana do Text jest wyświetlana bez lokalizacji. Aby użyć zmiennej jako klucza wyszukiwania, Apple dokumentuje tworzenie z niej LocalizedStringKey. Literał przekazany bezpośrednio do Text automatycznie korzysta ze ścieżki lokalizowalnej. Te przeciążenia mogą dawać identyczny tekst w języku źródłowym, a mimo to zachowywać się inaczej. LocalizedStringKey

Poniższa kompletna demonstracyjna aplikacja oddziela klucz wybierany w czasie działania od interpolowanej liczby. W tymczasowym projekcie aplikacji Mac w SwiftUI, utworzonym w Xcode 15 lub nowszym i przeznaczonym dla macOS 13, zastąp wygenerowaną deklarację aplikacji tym kodem. Pozostaw tylko jedną deklarację @main. Kod sprawdzono pod kątem zgodności z udokumentowanymi interfejsami API; nie został tu skompilowany, ponieważ nie było dostępnego toolchaina Swift.

import SwiftUI

@main
struct CatalogReviewDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogReviewView()
        }
    }
}

struct CatalogReviewView: View {
    @State private var compact = true
    @State private var itemCount = 2

    private var selectedKey: String {
        "panel." + (compact ? "compact" : "expanded")
    }

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Toggle("Compact layout", isOn: $compact)

            Text(LocalizedStringKey(selectedKey))

            Text("\(itemCount) items",
                 comment: "Number of items in the sample panel.")

            Button("Add item") {
                itemCount += 1
            }
        }
        .padding()
        .frame(minWidth: 320)
    }
}

Dodaj Localizable.xcstrings do celu aplikacji. Dodaj ręcznie zarządzane wpisy panel.compact i panel.expanded z wartościami źródłowymi Compact panel i Expanded panel. Skompiluj projekt, aby wyodrębnić komunikaty literalne. Jawna konwersja do LocalizedStringKey zleca wyszukiwanie w czasie działania; nie dostarcza ekstraktorowi literalnej deklaracji każdego możliwego konstruowanego klucza.

W przypadku niewielkiego, skończonego zestawu opcji rozważ zastąpienie konstruowania kluczy jawnymi lokalizowalnymi literałami w każdej gałęzi. W przypadku własnych interfejsów przekazujących komunikaty między komponentami Apple zaleca LocalizedStringResource, który przenosi informacje o lokalizacji, takie jak tabela, komentarz i wartość domyślna. Wybierz reprezentację, która ułatwia sprawdzenie całego obsługiwanego zestawu komunikatów. Przygotowywanie tekstu aplikacji do tłumaczenia

Czym różnią się zmieniające się liczby od zmieniających się kluczy?

W demonstracji wybór układu zmienia klucz komunikatu wyszukiwany przez aplikację. Zmiana itemCount przekazuje inny argument do jednego lokalizowalnego komunikatu. Interpolacja w SwiftUI przekształca osadzone wartości w symbole zastępcze formatu używane w lokalizacji; renderowanie w czasie działania podstawia ich wartości. Lokalizowanie aplikacji SwiftUI

Nie potrzebujesz więc osobnych kluczy dla wyrenderowanych etykiet 2 items, 3 items i 4 items. Skompiluj przykład, znajdź wyodrębniony komunikat licznikowy, kliknij jego klucz z wciśniętym klawiszem Control i wybierz Vary by Plural. Dla źródłowej lokalizacji angielskiej wpisz %lld item dla One i %lld items dla Other, używając symbolu zastępczego liczby całkowitej wyświetlonego przez Xcode. Apple dokumentuje tę procedurę dla komunikatów licznikowych oraz dodawanie odpowiednich wariantów liczby mnogiej dla innych obsługiwanych lokalizacji. Lokalizowanie i różnicowanie tekstu za pomocą katalogu ciągów

Podczas porządków sprawdź komunikat licznikowy jako kompletny zasób, łącznie z jego wariantami. Brak frazy wyświetlanej, takiej jak 4 items, w kodzie źródłowym nic nie mówi o tym, czy używany jest bazowy komunikat z interpolacją. Podobnie zachowanie szablonu licznikowego nie zachowuje niezwiązanego klucza dynamicznego tylko dlatego, że oba komunikaty pojawiają się w tym samym panelu.

Które wpisy należy faktycznie usunąć podczas porządków?

Rozważ przykładową weryfikację 24 kandydatów. Te liczby opisują syntetyczny przykład, a nie wynik pomiaru rzeczywistego projektu.

Wynik weryfikacji Wpisy Działanie
Jedynymi odbiorcami były widoki usuniętego panelu 9 Usuń po potwierdzeniu, że panel i jego dane wyszukiwania zniknęły
Klucze nadal są osiągalne przez wybór w czasie działania 8 Zachowaj i udokumentuj ręczne zarządzanie
Odwołania dotyczą innego celu lub kompilacji warunkowej 5 Zachowaj i zweryfikuj zakres tej kompilacji
Pochodzenie klucza pozostaje niewyjaśnione 2 Zachowaj do czasu wyjaśnienia
Łącznie sprawdzono 24 9 kandydatów do usunięcia

Takie zestawienie sprawia, że decyzję o porządkach można zweryfikować: sprawdzenie 24 wpisów nie oznacza, że należy usunąć 24. Dla każdego z dziewięciu kandydatów do usunięcia zachowaj krótkie uzasadnienie wskazujące usuniętego odbiorcę i sprawdzone ścieżki wyszukiwania w czasie działania. W przypadku ośmiu wpisów dynamicznych zapisz dozwolony zestaw kluczy, aby można było powtórzyć decyzję przy kolejnej weryfikacji.

Usuń tylko potwierdzonych kandydatów, a następnie sprawdź różnice w katalogu. Upewnij się, że zmiana obejmuje zamierzone klucze i powiązane z nimi tłumaczenia oraz że nie zniknęły niepowiązane warianty liczby mnogiej ani warianty urządzeń. Ponownie skompiluj odpowiednie konfiguracje. Jeśli usunięty klucz pojawi się ponownie podczas ekstrakcji, ponownie sprawdź jego odbiorcę, zanim usuniesz go kolejny raz.

Jak zweryfikować zachowane komunikaty na Macu?

Wybierz Product > Scheme > Edit Scheme, zaznacz Run i otwórz Options. Wybierz istniejącą obsługiwaną lokalizację w polu App Language, zamknij edytor i uruchom aplikację dla Maca. Apple dokumentuje te ustawienia schematu do testowania zlokalizowanych kompilacji. Powtórz to dla lokalizacji obsługiwanych przez aplikację. Testowanie lokalizacji podczas uruchamiania aplikacji

Sprawdź wszystkie dozwolone wybory dynamiczne, w tym oba układy z demonstracji. Potwierdź, że aplikacja wyświetla oczekiwane wartości z katalogu, a nie identyfikatory. W przypadku komunikatów licznikowych sprawdź przykładowe wartości, takie jak 0, 1, 2 i 12, oraz dodatkowe kategorie liczby mnogiej, gdy wymagają ich obsługiwane lokalizacje. Zmiana początkowej wartości licznika w przykładzie wystarczy, aby uzyskać te wartości testowe.

Jeśli zachowany komunikat wyświetla się nieprawidłowo, przed zmianą katalogu sprawdź dokładny klucz, tabelę, pakiet i inicjalizator Text. Nowszy mechanizm generowania symboli Apple może również ułatwić odwoływanie się do zasobów zarządzanych ręcznie: Xcode 26 wprowadził generowanie symboli katalogu ciągów, włączane w istniejących projektach za pomocą Generate String Catalog Symbols. To opcjonalna ścieżka refaktoryzacji, a nie dowód na to, że nieużywany zasób zarządzany ręcznie jest zbędny. Kodowanie z przewodnikiem: poznaj lokalizację w Xcode

Zakończ z niewielkim, jasno uzasadnionym zestawem usuniętych wpisów i udokumentowaną listą zachowanych komunikatów dynamicznych. Efektem powinien być katalog, którego pozostałe wpisy mają rozpoznawalnych odbiorców, a klucze wybierane w czasie działania i formatowane komunikaty licznikowe nadal działają w interfejsie Maca.

Źródła