Ab Xcode 26 können String-Kataloge Swift-Zugriffe generieren, die manuell eingegebene Lokalisierungsschlüssel ersetzen. Diese Anleitung migriert die Auswahlzusammenfassung einer kleinen Mac-App zu typisierten Eigenschaften und Funktionen und prüft anschließend, was der Compiler tatsächlich schützt.

Die Aufgabe ist bewusst eng gefasst: eine Fensterüberschrift und eine Zusammenfassung mit zwei Ganzzahlwerten anzeigen. Alle Bezeichnungen und Werte sind synthetisch. Du erstellst den Katalogvertrag, bindest ihn an SwiftUI an und überprüfst sowohl Compilerdiagnosen als auch die sichtbare Ausgabe.

Was macht einen Lokalisierungszugriff zur Compile-Zeit geprüft?

Apple hat mit Xcode 26 die native Generierung von String-Katalogsymbolen eingeführt. Ein Eintrag ohne Platzhalter erzeugt eine statische Eigenschaft; ein Eintrag mit Platzhaltern erzeugt eine Funktion mit typisierten Parametern. Beide geben LocalizedStringResource zurück. Bei neuen Xcode-26-Projekten ist die Generierung standardmäßig aktiviert; bei bestehenden Projekten muss möglicherweise die Build-Einstellung aktiviert werden. Mitmachanleitung: Lokalisierung mit Xcode erkunden

Die nützliche Änderung zeigt sich am Aufrufort. Ein Stringliteral kann einen Suchschlüssel angeben, ohne auf eine Swift-Deklaration zu verweisen. Ein generierter Zugriff verweist auf ein Mitglied, das vorhanden sein muss, und eine generierte Funktion verlangt Argumente, die ihrer Signatur entsprechen. Aus diesen dokumentierten Mechanismen ergibt sich in der Praxis: Ein falsch geschriebenes Mitglied oder ein inkompatibles Argument führt zu einem Compilerfehler.

Dieser Schutz hat einen klaren Geltungsbereich. Swift kann prüfen, ob der Zugriff vorhanden ist und ob die Argumente passen. Es kann nicht feststellen, ob der Wortlaut die beabsichtigte Oberfläche beschreibt oder ob zwei gültige Ganzzahlargumente den richtigen Zählwerten entsprechen. Betrachte Zugriffe als geprüfte Programmierschnittstelle zu deinen Meldungen.

Eine kleine Mac-App und ihren Nachrichtenvertrag einrichten

Verwende Xcode 26 oder neuer und ein macOS-SwiftUI-Appziel. Lege für dieses Beispiel das Bereitstellungsziel auf macOS 15 oder neuer fest. Der zugrunde liegende Typ LocalizedStringResource ist ab macOS 13 verfügbar; das höhere Ziel des Beispiels ist eine Voraussetzung dieser Wahl und nicht die Mindestversion für diesen Typ. Eine Ressource stellt lokalisierbaren Text dar, dessen Suche bis zum benötigten Zeitpunkt aufgeschoben werden kann. LocalizedStringResource

Füge über File > New > File from Template einen Katalog hinzu. Wähle unter Resource die Option String Catalog, nenne ihn Workbench und füge ihn dem App-Ziel hinzu. Apple dokumentiert, dass jeder Katalog eine Tabelle darstellt; hier werden die beiden Meldungen in einer eigenen Tabelle zusammengefasst. Text mit einem String-Katalog lokalisieren und variieren

Öffne im Projekteditor Build Settings, filtere nach Generate String und setze Generate String Catalog Symbols für die effektive Konfiguration des Ziels auf Yes. Dies ist der dokumentierte Schalter für ältere Projekte. Generierte lokalisierbare Symbole im Code verwenden

Wähle in Workbench.xcstrings die englische Ausgangslokalisierung. Füge die folgenden beiden Einträge über die Schaltfläche + in der Symbolleiste des Katalogeditors hinzu. Die Kommentare legen fest, was die Meldungen bedeuten, einschließlich der Rollen ihrer Argumente.

Schlüssel Englischer Ausgangswert Kommentar
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.

Für SUBTITLE kannst du jeden Platzhalter über das Vervollständigungsmenü von Xcode eingeben: Tippe %, wähle den Ganzzahlplatzhalter und nenne ihn selectedCount oder availableCount. Apple dokumentiert benannte Variablen und generierte Parameter für diese Formatspezifizierer. Wähle jeden Eintrag aus und prüfe im Attributes-Inspektor Generate Swift Symbol und Example Usages. Generierte lokalisierbare Symbole im Code verwenden

Der vorgesehene Vertrag besteht aus einer Titeleigenschaft und einer Untertitelfunktion, die zwei Int-Werte entgegennimmt. Prüfe die tatsächliche generierte Schreibweise im Inspektor, bevor du fortfährst: Apple zufolge verwenden Symbolnamen sowohl den Schlüssel als auch dessen Wert. Die folgenden Beispiele verwenden .Workbench.title und .Workbench.subtitle(selectedCount:availableCount:) und folgen damit Apples dokumentiertem Muster mit Großbuchstabenschlüsseln. Mitmachanleitung: Lokalisierung mit Xcode erkunden

Dieser Vertrag macht einen wichtigen Unterschied deutlich: availableCount schließt ausgewählte Elemente ein. Ohne diesen Kommentar könnte ein Aufrufer den Wert plausiblerweise als Anzahl der verbleibenden Elemente auffassen. Beide Interpretationen würden die Typprüfung bestehen; deshalb gehört die Bedeutung zu dokumentieren dazu, den Zugriff nützlich zu machen.

Die generierten Zugriffe in einem vollständigen Fenster verwenden

Wähle nach dem Erstellen des Katalogs Product > Build. Ersetze die App-Deklaration und die Inhaltsansicht der Vorlage durch das folgende Programm und behalte genau eine @main-Deklaration im Ziel bei. Der Katalog ist eine erforderliche Ressource für dieses Programm; durch Einfügen des Swift-Codes in eine eigenständige Datei werden die Zugriffe nicht generiert.

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)
    }
}

Bei aktiver englischer Ausgangslokalisierung sollte die beispielhafte Eingabe Selection overview gefolgt von 3 selected; 12 available anzeigen. Die Zählwerte sind festgelegt, damit du die Argumentpositionen prüfen kannst, ohne Code für die Auswahlverwaltung einzuführen.

Apple dokumentiert, dass generierte Ressourcen in SwiftUI, einschließlich Text, und über den String(localized:)-Initialisierer von Foundation verwendet werden können. Wenn eine bestehende Mac-Oberfläche einen aufgelösten String benötigt, wandle die generierte Ressource an dieser Schnittstelle um. Mitmachanleitung: Lokalisierung mit Xcode erkunden

Beispielsweise kannst du nach dem Vorhandensein des Katalogs diese vollständige Hilfsfunktion zum selben App-Ziel hinzufügen:

import Foundation

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

Wenn deine eigene Schnittstelle LocalizedStringResource zurückgibt, bleibt die Ressource für eine spätere Suche erhalten; bei der Rückgabe von String wird sie beim Aufruf des Initialisierers aufgelöst. Entscheide anhand der Anforderungen der empfangenden Schnittstelle. Apple beschreibt diesen Unterschied zwischen aufgeschobener und sofortiger Suche in der Foundation-Dokumentation. LocalizedStringResource

Die Beispiele wurden anhand der abgerufenen Dokumentation überprüft. Hier wurden sie nicht kompiliert, da in der verfügbaren Umgebung weder ein Swift-Programm noch Xcode vorhanden ist.

Warum der führende Punkt und die Argumentbezeichnungen wichtig sind

Der führende Punkt ist Swifts implizite Member-Syntax. Sie kürzt den Zugriff auf ein Typmitglied ab, wenn Swift den Typ aus dem umgebenden Kontext ableiten kann. Es handelt sich um gewöhnliche Swift-Syntax und nicht um einen speziellen Operator für String-Schlüssel. Ausdrücke — Impliziter Member-Ausdruck

Bei generierten Lokalisierungssymbolen stellt die standardmäßige Tabelle Localizable Mitglieder direkt bereit, während eine benannte Tabelle einen Tabellennamensraum einführt. Deshalb steht in diesem Beispiel .Workbench vor dem Mitgliedsnamen. Apple dokumentiert beide Formen. Generierte lokalisierbare Symbole im Code verwenden

Die Bezeichnungen selectedCount: und availableCount: gehören zum Funktionsaufruf. Swift unterscheidet Argumentbezeichnungen, die am Aufrufort erscheinen, von Parameternamen, die innerhalb einer Funktion verwendet werden. Wenn ein Parameter eine Bezeichnung erfordert, muss der Aufrufer sie angeben. Funktionen — Argumentbezeichnungen und Parameternamen

Aussagekräftige Bezeichnungen helfen, Fehler zu vermeiden, aber beide Argumente haben hier denselben Typ. Die beiden Ganzzahlwerte zu vertauschen bleibt gültiges Swift. Der Nachrichtenvertrag und die Prüfung der sichtbaren Ausgabe ergänzen daher die Compilerprüfung.

Bestehende Schlüssel migrieren, ohne ihre Bedeutung zu verlieren

Für bestehende lokalisierbare Zeichenfolgen bietet Apple einen Refactoring-Ablauf. Wähle Einträge im String-Katalog aus, klicke bei gedrückter Control-Taste darauf und wähle Refactor > Convert Strings to Symbols. Prüfe die Vorschau, passe bei Bedarf die vorgeschlagenen Symbol- oder Parameternamen an und wähle Convert. Generierte lokalisierbare Symbole im Code verwenden

Migriere zuerst eine zusammenhängende Gruppe, etwa die Überschrift und Zusammenfassung dieses Fensters. Vergleiche vor dem Übernehmen der Vorschau die alte Meldung mit dem neuen Vertrag: Verwenden sie dieselbe Tabelle, beschreiben sie dasselbe Oberflächenelement und haben alle Platzhalter dieselbe Bedeutung? Prüfe alle vorhandenen lokalisierten Werte, die durch eine Schlüsseländerung betroffen sind, statt anzunehmen, dass das Refactoring ihre Korrektheit gewährleistet.

Wenn das Refactoring einen Aufrufort nicht aktualisiert, verwende die generierte Verwendung im Kataloginspektor und ersetze den Verweis ausdrücklich. Erstelle dann den Build und prüfe den resultierenden Text. Lösche den alten Eintrag erst, wenn du alle Stellen berücksichtigt hast, die ihn aufrufen.

Wenn deine installierte Xcode-Version keine native Generierung unterstützt, ist für diesen Ablauf eine neuere Toolchain erforderlich. Apple unterstützt außerdem das Extrahieren von Zeichenfolgen aus lokalisierbaren APIs in Kataloge und empfiehlt das Extrahieren als Einstieg in den Arbeitsablauf. Es bleibt eine unterstützte Methode zur Verwaltung der Lokalisierung, stellt aber nicht selbst den hier beschriebenen Vertrag mit generierten Zugriffen bereit. Mitmachanleitung: Lokalisierung mit Xcode erkunden

Die Migration mit einer kurzen Diagnosefolge überprüfen

Führe die folgenden Prüfungen für das Beispielfenster durch. Sie trennen den Compilerschutz von der Korrektheit der Meldungen und der Ressourcenintegration.

  1. Erstelle einen Build des unveränderten Beispiels, um eine funktionierende Ausgangsbasis zu erhalten.
  2. Schreibe den Namen des Titelelements vorübergehend falsch und erstelle einen Build. Für das nicht vorhandene Mitglied sollte eine Compilerdiagnose ausgegeben werden. Stelle den ursprünglichen Namen wieder her.
  3. Übergib vorübergehend einen String-Wert, wo der Untertitel ein Int erwartet. Erstelle einen Build, um die Typabweichung zu prüfen, und stelle anschließend den Ganzzahlwert wieder her.
  4. Führe die App mit selectedCount auf 3 und availableCount auf 12 aus. Prüfe, ob die Zahlen an den vorgesehenen Positionen stehen.
  5. Ändere nur den Titelwert im Katalog zu Current selection, erstelle einen neuen Build und prüfe die angezeigte Überschrift. Vergewissere dich, dass die generierte Signatur weiterhin der von deinem Code verwendeten entspricht.

Wenn ein Mitglied unerwartet fehlt, prüfe zuerst die generierte Verwendung des Katalogeintrags. Kontrolliere anschließend die Generierungseinstellung, die Zielmitgliedschaft des Katalogs und den Tabellennamen. Eine Compilerdiagnose weist auf einen fehlgeschlagenen Verweis hin; anhand dieser Prüfungen kannst du feststellen, ob ein Schreibfehler vorliegt oder die generierte Deklaration nicht verfügbar ist.

Prüfe zum Schluss die tatsächliche Oberfläche. Apples dokumentierter Weg lautet Product > Scheme > Edit Scheme, dann Run > Options, wo du vor dem Ausführen die App Language auswählen kannst. Wiederhole dies für die von deinem Projekt unterstützten Lokalisierungen. Lokalisierungen beim Ausführen deiner App testen

Für eine frühe Layoutprüfung bietet Xcode außerdem die Double-Length Pseudolanguage, die lokalisierbaren Text verlängert und so Größenprobleme sichtbar macht. Prüfe die Zusammenfassung bei schmaler Fensterbreite; eine erfolgreiche Kompilierung zeigt nicht, ob der Text hineinpasst. Lokalisierungen testen

Eine abgeschlossene Migration stellt sicher, dass jeder Aufrufort auf ein echtes Swift-Mitglied verweist, jede Variable eine dokumentierte Rolle hat und der vorgesehene Katalogeintrag über einen geprüften Pfad erreichbar bleibt. Führe die Compilerprüfungen und die Fensterprüfungen gemeinsam durch: Erstere prüfen den Zugriffsvertrag, Letztere bestätigen, dass die Leser die beabsichtigte Meldung sehen.

Quellen