W Xcode 26 i nowszych katalogi ciągów mogą generować akcesory Swift, które zastępują ręcznie wpisywane klucze lokalizacji. W tym poradniku podsumowanie zaznaczenia w małej aplikacji Mac zostaje przeniesione do typowanych właściwości i funkcji, a następnie sprawdzamy, co faktycznie chroni kompilator.

Zakres zadania jest celowo wąski: wyświetlenie nagłówka okna i podsumowania zawierającego dwie liczby całkowite. Wszystkie etykiety i wartości są przykładowe. Utworzysz kontrakt katalogu, połączysz go ze SwiftUI oraz sprawdzisz diagnostykę kompilatora i widoczny wynik.

Co sprawia, że akcesor lokalizacji jest sprawdzany podczas kompilacji?

Apple wprowadziło natywne generowanie symboli z katalogów ciągów w Xcode 26. Wpis bez symboli zastępczych tworzy właściwość statyczną, a wpis z symbolami zastępczymi — funkcję z typowanymi parametrami. Oba zwracają LocalizedStringResource. W nowych projektach Xcode 26 generowanie jest domyślnie włączone; w istniejących projektach może być konieczne włączenie ustawienia kompilacji. Ćwiczenie z kodowaniem: poznaj lokalizację w Xcode

Przydatna zmiana zachodzi w miejscu wywołania. Literał tekstowy może zawierać klucz wyszukiwania bez odwołania do deklaracji Swift. Wygenerowany akcesor odwołuje się do elementu, który musi istnieć, a wygenerowana funkcja wymaga argumentów zgodnych z jej sygnaturą. Z tych udokumentowanych mechanizmów wynika praktyczna korzyść: błędnie wpisany element lub niezgodny argument powoduje błąd kompilatora.

Ta ochrona ma określony zakres. Swift może sprawdzić, czy akcesor istnieje i czy jego argumenty pasują. Nie potrafi ustalić, czy tekst opisuje zamierzony interfejs ani czy dwie poprawne wartości całkowite oznaczają właściwe liczby. Traktuj akcesory jako sprawdzany interfejs programistyczny do komunikatów.

Skonfiguruj małą aplikację Mac i jej kontrakt komunikatów

Użyj Xcode 26 lub nowszego oraz celu aplikacji SwiftUI dla macOS. W tym przykładzie ustaw cel wdrożenia na macOS 15 lub nowszy. Typ LocalizedStringResource jest dostępny od macOS 13; wyższy cel przykładu jest wymaganiem wybranym na potrzeby tego przykładu, a nie minimalną wersją tego typu. Zasób reprezentuje tekst podlegający lokalizacji, którego wyszukiwanie można odroczyć do chwili, gdy będzie potrzebny. LocalizedStringResource

Dodaj katalog przez File > New > File from Template. W sekcji Resource wybierz String Catalog, nadaj mu nazwę Workbench i dołącz go do celu aplikacji. Apple dokumentuje, że każdy katalog reprezentuje tabelę; użycie osobnej tabeli pozwala zebrać dwa komunikaty przykładu w jednym miejscu. Lokalizowanie i różnicowanie tekstu za pomocą katalogu ciągów

W edytorze projektu otwórz Build Settings, wyszukaj Generate String i ustaw Generate String Catalog Symbols na Yes dla efektywnej konfiguracji celu. To udokumentowany przełącznik dla starszych projektów. Używanie w kodzie wygenerowanych symboli lokalizowalnych

W pliku Workbench.xcstrings wybierz angielską lokalizację źródłową. Dodaj poniższe dwa wpisy za pomocą przycisku + na pasku narzędzi edytora katalogu. Komentarze określają znaczenie komunikatów, w tym rolę ich argumentów.

Klucz Angielska wartość źródłowa Komentarz
TITLE Selection overview Heading above the selection summary.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Selection summary. selectedCount is the number selected; availableCount is the total number available, including selected items.

W przypadku SUBTITLE możesz wprowadzić każdy symbol zastępczy za pomocą menu uzupełniania Xcode: wpisz %, wybierz symbol zastępczy typu całkowitego i nadaj mu nazwę selectedCount lub availableCount. Apple dokumentuje nazwane zmienne i generowane parametry dla tych specyfikatorów formatu. Wybierz każdy wpis i sprawdź Generate Swift Symbol oraz Example Usages w inspektorze atrybutów. Używanie w kodzie wygenerowanych symboli lokalizowalnych

Zamierzony kontrakt to właściwość tytułu i funkcja podtytułu przyjmująca dwie wartości Int. Przed kontynuowaniem sprawdź w inspektorze faktycznie wygenerowaną pisownię: Apple informuje, że nazwy symboli wykorzystują zarówno klucz, jak i jego wartość. Poniższe przykłady używają .Workbench.title i .Workbench.subtitle(selectedCount:availableCount:), zgodnie z udokumentowanym przez Apple wzorcem klucza pisanego wielkimi literami. Ćwiczenie z kodowaniem: poznaj lokalizację w Xcode

Ten kontrakt jasno określa, że availableCount obejmuje zaznaczone elementy. Bez tego komentarza osoba wywołująca mogłaby rozsądnie uznać, że chodzi o liczbę pozostałych elementów. Obie interpretacje przeszłyby kontrolę typów, dlatego opisanie znaczenia jest częścią tworzenia użytecznego akcesora.

Użyj wygenerowanych akcesorów w kompletnym oknie

Po utworzeniu katalogu wybierz Product > Build. Zastąp deklarację aplikacji z szablonu i widok zawartości poniższym programem, pozostawiając w celu dokładnie jedną deklarację @main. Katalog jest wymaganym zasobem tego programu; wklejenie kodu Swift do samodzielnego pliku nie wygeneruje jego akcesorów.

import Foundation
import SwiftUI

@main
struct SelectionOverviewApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionOverviewView(
                selectedCount: 3,
                availableCount: 12
            )
        }
    }
}

struct SelectionOverviewView: View {
    let selectedCount: Int
    let availableCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(.Workbench.title)
                .font(.title2)

            Text(
                .Workbench.subtitle(
                    selectedCount: selectedCount,
                    availableCount: availableCount
                )
            )
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 140)
    }
}

Przy aktywnej angielskiej lokalizacji źródłowej przykładowe dane powinny wyświetlić Selection overview, a pod nim 3 selected; 12 available. Liczby są stałe, aby można było sprawdzić położenie argumentów bez dodawania kodu zarządzającego zaznaczeniem.

Apple dokumentuje możliwość używania wygenerowanych zasobów w SwiftUI, w tym w Text, oraz za pośrednictwem inicjalizatora Foundation String(localized:). Jeśli istniejący interfejs Mac wymaga rozstrzygniętego typu String, przekonwertuj wygenerowany zasób na tej granicy. Ćwiczenie z kodowaniem: poznaj lokalizację w Xcode

Na przykład poniższa kompletna funkcja pomocnicza może zostać dodana do tego samego celu aplikacji po utworzeniu katalogu:

import Foundation

func selectionSummary(
    selectedCount: Int,
    availableCount: Int
) -> String {
    String(
        localized: .Workbench.subtitle(
            selectedCount: selectedCount,
            availableCount: availableCount
        )
    )
}

Zwracanie LocalizedStringResource z własnego interfejsu zachowuje zasób do późniejszego wyszukania; zwrócenie String rozstrzyga go w chwili wywołania inicjalizatora. Wybierz wariant zależnie od wymagań interfejsu odbierającego wartość. Apple opisuje to rozróżnienie między odroczonym a natychmiastowym wyszukiwaniem w dokumentacji Foundation. LocalizedStringResource

Przykłady sprawdzono na podstawie pobranej dokumentacji. Nie zostały tu skompilowane, ponieważ dostępne środowisko nie zawiera pliku wykonywalnego Swift ani Xcode.

Dlaczego kropka na początku i etykiety argumentów mają znaczenie

Kropka na początku to składnia niejawnego elementu członkowskiego w Swift. Jest skrótem dostępu do elementu członkowskiego typu, gdy otaczający kontekst pozwala Swift wywnioskować typ. To zwykła składnia Swift, a nie specjalny operator klucza tekstowego. Wyrażenia — wyrażenie niejawnego elementu członkowskiego

W przypadku wygenerowanych symboli lokalizacji elementy członkowskie domyślnej tabeli Localizable są dostępne bezpośrednio, natomiast nazwana tabela wprowadza przestrzeń nazw tabeli. Dlatego ten przykład zawiera .Workbench przed nazwą elementu członkowskiego. Apple dokumentuje obie formy. Używanie w kodzie wygenerowanych symboli lokalizowalnych

Etykiety selectedCount: i availableCount: należą do wywołania funkcji. Swift rozróżnia etykiety argumentów widoczne w miejscu wywołania od nazw parametrów używanych wewnątrz funkcji. Gdy parametr wymaga etykiety, osoba wywołująca musi ją podać. Funkcje — etykiety argumentów i nazwy parametrów funkcji

Czytelne etykiety pomagają zapobiegać pomyłkom, ale oba argumenty mają tutaj ten sam typ. Zamiana miejscami dwóch wartości całkowitych nadal daje poprawny kod Swift. Dlatego kontrakt komunikatu i kontrola widocznego wyniku uzupełniają pracę kompilatora.

Przenieś istniejące klucze, zachowując ich znaczenie

W przypadku istniejących ciągów podlegających lokalizacji Apple udostępnia przepływ pracy refaktoryzacji. Wybierz wpisy w katalogu ciągów, kliknij je z wciśniętym klawiszem Control i wybierz Refactor > Convert Strings to Symbols. Sprawdź podgląd, w razie potrzeby dostosuj proponowane nazwy symboli lub parametrów, a następnie wybierz Convert. Używanie w kodzie wygenerowanych symboli lokalizowalnych

Najpierw przenieś jedną spójną grupę, na przykład nagłówek i podsumowanie tego okna. Zanim zaakceptujesz podgląd, porównaj stary komunikat z nowym kontraktem: czy używają tej samej tabeli, opisują ten sam element interfejsu i przypisują takie samo znaczenie każdemu symbolowi zastępczemu? Sprawdź istniejące zlokalizowane wartości, na które wpłynęła zmiana klucza; nie zakładaj, że refaktoryzacja potwierdza ich poprawność.

Jeśli refaktoryzacja nie zaktualizuje któregoś miejsca wywołania, skorzystaj z wygenerowanego użycia widocznego w inspektorze katalogu i jawnie zastąp to odwołanie. Następnie skompiluj aplikację i sprawdź wynikowy tekst. Nie usuwaj starego wpisu, dopóki nie uwzględnisz wszystkich miejsc, które z niego korzystają.

Jeśli zainstalowana wersja Xcode nie obsługuje natywnego generowania, ten przepływ pracy wymaga nowszego zestawu narzędzi. Apple obsługuje również wyodrębnianie ciągów z interfejsów API podlegających lokalizacji do katalogów i zaleca wyodrębnianie jako początkowy przepływ pracy. Nadal jest to obsługiwany sposób zarządzania lokalizacją, ale sam w sobie nie zapewnia kontraktu wygenerowanych akcesorów opisanego tutaj. Ćwiczenie z kodowaniem: poznaj lokalizację w Xcode

Zweryfikuj migrację za pomocą krótkiej sekwencji diagnostycznej

Wykonaj poniższe kontrole dla przykładowego okna. Pozwalają oddzielić ochronę kompilatora od poprawności komunikatów i integracji zasobów.

  1. Skompiluj niezmieniony przykład, aby uzyskać działający punkt odniesienia.
  2. Tymczasowo wpisz błędnie nazwę elementu członkowskiego tytułu i skompiluj aplikację. Nieistniejący element powinien spowodować diagnostykę kompilatora. Przywróć poprawną nazwę.
  3. Tymczasowo przekaż wartość typu String w miejscu, gdzie podtytuł wymaga Int. Skompiluj aplikację, aby sprawdzić niezgodność typów, a następnie przywróć liczbę całkowitą.
  4. Uruchom aplikację, ustawiając selectedCount na 3, a availableCount na 12. Sprawdź, czy liczby pojawiają się we właściwych miejscach.
  5. Zmień wyłącznie wartość tytułu w katalogu na Current selection, skompiluj aplikację i sprawdź wyświetlany nagłówek. Upewnij się, że wygenerowana sygnatura nadal odpowiada tej używanej przez kod.

Jeśli element członkowski nieoczekiwanie nie istnieje, najpierw sprawdź wygenerowane użycie wpisu w katalogu. Następnie sprawdź ustawienie generowania, przypisanie katalogu do celu i nazwę tabeli. Diagnostyka kompilatora wskazuje nieudane odwołanie; te kontrole pomagają odróżnić błąd pisowni od braku wygenerowanej deklaracji.

Na koniec przetestuj rzeczywisty interfejs. Udokumentowana przez Apple ścieżka to Product > Scheme > Edit Scheme, a następnie Run > Options, gdzie przed uruchomieniem możesz wybrać App Language. Powtórz test dla lokalizacji obsługiwanych przez projekt. Testowanie lokalizacji podczas uruchamiania aplikacji

Do wstępnej kontroli układu Xcode oferuje również Double-Length Pseudolanguage, które wydłuża lokalizowalny tekst, aby ujawnić problemy z dopasowaniem. Sprawdź podsumowanie przy małej szerokości okna; udana kompilacja nie potwierdza, że tekst się mieści. Testowanie lokalizacji

Ukończona migracja zapewnia każdemu miejscu wywołania rzeczywisty element członkowski Swift, każdej zmiennej udokumentowaną rolę, a także sprawdzaną ścieżkę do zamierzonego wpisu katalogu. Łącz kontrole kompilatora ze sprawdzaniem okna: pierwsze weryfikują kontrakt akcesora, a drugie potwierdzają, że użytkownik widzi zamierzony komunikat.

Źródła