Für eine wiederverwendbare macOS-Bezeichnung akzeptieren Sie lokalisierbare Nachrichten als LocalizedStringResource, behalten einen separaten verbatim:-Pfad für wörtlichen Text bei und bewahren Interpolationen bis zur Lokalisierung. Dieses Tutorial setzt diesen Vertrag für einen Desktop-Elementzähler um und prüft die Extraktion getrennt von der Anzeige.

Was sollte die wiederverwendbare Text-API versprechen?

Angenommen, eine Mac-App benötigt eine kompakte Zusammenfassung mit einer Elementanzahl und einer Bezeichnung für eine synthetische Sammlung wie Sample Set. Die wiederverwendbare Komponente muss drei Eingaben unterscheiden: eine von der App verfasste Nachricht, die übersetzt werden muss, einen vorhandenen SwiftUI-Lokalisierungsschlüssel und Text, der exakt wie angegeben erscheinen soll.

Apple empfiehlt LocalizedStringResource, um lokalisierbare Zeichenfolgen in benutzerdefinierten Ansichten und anderem Swift-Code darzustellen und weiterzugeben. Die aktuelle Anleitung zeigt, wie Eigenschaften benutzerdefinierter Ansichten dieses Typs mit Text angezeigt werden. Verwenden Sie ihn als primären Nachrichtenvertrag, wenn Sie eine neue Komponente entwerfen. Preparing your app’s text for translation.

Die folgende Entscheidungstabelle leitet ein API-Design aus diesen dokumentierten Verhaltensweisen ab. Die expliziten Argumentbezeichnungen machen die Absicht des Aufrufers nachvollziehbar, ohne sich auf zwei konkurrierende, nicht beschriftete String-Überladungen zu verlassen.

Absicht des Aufrufers Vorgeschlagener Einstiegspunkt Darstellungspfad
Eine übersetzbare Nachricht mit optionalem Kontext übergeben SummaryLabel(localized:) Text(resource)
Einen SwiftUI-Schlüssel übergeben, einschließlich SwiftUI-Interpolation SummaryLabel(key:) Text(key, tableName:bundle:)
Eine exakte Bezeichnung anzeigen SummaryLabel(verbatim:) Text(verbatim:)
Vom Aufrufer bereits zusammengesetzten Text bereitstellen SummaryLabel(text:) Den übergebenen Text speichern

Behalten Sie LocalizedStringKey bei, wenn die Komponente ausdrücklich das schlüsselbasierte Verhalten von SwiftUI benötigt. Apple dokumentiert, dass ein Zeichenfolgenliteral, das direkt an Text übergeben wird, einen Lokalisierungsschlüssel erzeugt, während eine String-Variable normalerweise einen Lokalisierung umgehenden Pfad nimmt. Ein Wrapper, der nur String akzeptiert, verändert daher die Bedeutung ähnlich aussehender Aufrufe. LocalizedStringKey.

Eine vollständige Komponente mit expliziten Einstiegspunkten erstellen

Verwenden Sie für dieses Beispiel ein macOS-SwiftUI-App-Projekt in Xcode 26 oder neuer mit dem Bereitstellungsziel macOS 26. Ersetzen Sie die generierten Deklarationen für App und Content-View durch das vollständige Programm unten; behalten Sie im Ziel nur eine @main-Deklaration bei. Alle Bezeichnungen und Zählwerte sind synthetisch. Der Code wurde anhand der dokumentierten APIs geprüft, aber hier nicht kompiliert, da diese Umgebung keinen Swift-Compiler enthält.

import Foundation
import SwiftUI

struct SummaryLabel: View {
    private let text: Text

    init(localized resource: LocalizedStringResource) {
        text = Text(resource)
    }

    init(
        key: LocalizedStringKey,
        tableName: String? = nil,
        bundle: Bundle? = nil,
        comment: StaticString? = nil
    ) {
        text = Text(
            key,
            tableName: tableName,
            bundle: bundle,
            comment: comment
        )
    }

    init(verbatim value: String) {
        text = Text(verbatim: value)
    }

    init(text: Text) {
        self.text = text
    }

    var body: some View {
        text
            .font(.callout)
            .padding(8)
    }
}

struct ContentView: View {
    @State private var itemCount = 2
    private let collectionLabel = "Sample Set"

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Stepper(value: $itemCount, in: 0...12) {
                Text("Item count")
            }

            SummaryLabel(
                localized: LocalizedStringResource(
                    "summary.item-count",
                    defaultValue: "\(itemCount) items",
                    comment: "Summary below the item-count control. The integer is the number of items."
                )
            )

            SummaryLabel(
                key: "Collection: \(collectionLabel)"
            )

            SummaryLabel(verbatim: collectionLabel)

            SummaryLabel(
                text: Text(
                    "Preview",
                    comment: "Heading for a preview of the current item selection."
                ).bold()
            )
        }
        .padding(20)
        .frame(minWidth: 320)
    }
}

@main
struct TextContractDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Der Resource-Initializer trennt bewusst den stabilen Schlüssel summary.item-count von seiner Standardnachricht \(itemCount) items. Apple dokumentiert für diesen Initializer einen statischen Schlüssel, einen lokalisierbaren Standardwert, eine Tabelle, eine Locale, ein Bundle und einen Kommentar für Übersetzer. Der Standardwert wird verwendet, wenn der Schlüssel in der angegebenen Tabelle fehlt. LocalizedStringResource initializer.

Der verbatim:-Initializer legt ein ebenso klares Versprechen fest: Die angegebene Zeichenfolge wird ohne Lokalisierung angezeigt. Er funktioniert sowohl mit einem Literalargument als auch mit einer Variablen. Verwenden Sie diesen Pfad für die synthetische Sammlungsbezeichnung, wenn deren exakte Schreibweise angezeigt werden soll. Text.init(verbatim:).

Der Einstiegspunkt text: ermöglicht es dem Aufrufer, lokalisierten oder formatierten Text zu erstellen, bevor er ihn übergibt. Diese Komponente ergänzt gemeinsame Typografie und Abstände; die Semantik der Nachricht bestimmt weiterhin der Aufrufer. Die Übergabe von Text ist ein Ausweg. Eine Komponente, die einen engeren Vertrag durchsetzen muss, kann diesen Initializer weglassen.

Worin unterscheiden sich Extraktion und Laufzeitformatierung?

Behandeln Sie Lokalisierung als zwei getrennte Prüfungen. Während eines Builds erkennt Xcode lokalisierbare Quellausdrücke und aktualisiert den String Catalog. Zur Laufzeit löst die App die Nachricht auf und ersetzt ihre Argumente. Apples Sitzung zu String Catalogs beschreibt ausdrücklich, wie Literale erkannt werden, die an einem Aufrufpunkt einer benutzerdefinierten Ansicht zum Erstellen von LocalizedStringResource verwendet werden. Sie nennt auch die Build-Einstellung Use Compiler to Extract Swift Strings. Discover String Catalogs.

Die Interpolation muss einen lokalisierungsfähigen Typ erreichen, bevor sie zu einer gewöhnlichen fertigen Zeichenfolge wird. Apple erklärt, dass der Interpolations-Builder von SwiftUI den Formatierungsschlüssel und die Argumentwerte getrennt hält und so die Lokalisierung vor dem Einsetzen ermöglicht. Eine bereits interpolierte String nachträglich in einen Schlüssel umzuwandeln, kann diese ursprünglichen typisierten Argumente nicht wiederherstellen. What’s New in Swift.

Dieser Diagnoseausschnitt zeigt den Unterschied; er ist keine zweite App. Alle darin verwendeten Werte sind lokal definiert.

import SwiftUI

let count = 2

// Ordinary String interpolation has already produced "2 items".
let completed: String = "\(count) items"
let exactDisplay = Text(completed)

// Looks up the completed value as a key.
// This does not restore a count placeholder.
let completedValueLookup = Text(LocalizedStringKey(completed))

// Preserves localization-aware interpolation from the beginning.
let messageKey: LocalizedStringKey = "\(count) items"
let interpolatedDisplay = Text(messageKey)

LocalizedStringKey aus einer Variablen zu erstellen, ist eine dokumentierte Möglichkeit, eine Suche zur Laufzeit anzufordern. Das ist nützlich, wenn die Variable absichtlich einen bekannten Schlüssel enthält. Dadurch wird nicht sichergestellt, dass Xcode jeden möglichen Wert dieser Variablen in einen Katalog extrahiert. Pflegen Sie beabsichtigte dynamische Schlüssel explizit oder verwenden Sie literale Resource-Deklarationen für die begrenzte Menge an Nachrichten, die Ihrer App gehören. Das Suchverhalten und der Fallback sind in Text.init(_:tableName:bundle:comment:) dokumentiert.

Bewahren Sie die gesamte Nachricht einschließlich Satzzeichen und Platzhalterpositionen in einem einzigen lokalisierbaren Ausdruck. Halten Sie für dieses Beispiel Collection: \(collectionLabel) zusammen. Wenn Sie eine fertige Nachricht aus separat aufgelösten Fragmenten zusammensetzen, muss der Aufrufer für deren Reihenfolge und Abstände sorgen.

Den Katalog ergänzen und das Pluralverhalten konfigurieren

Fügen Sie zunächst über File > New > File from Template einen String Catalog hinzu, wählen Sie String Catalog aus und nennen Sie ihn Localizable. Wählen Sie dann Product > Build. Apple dokumentiert, dass der Build den Katalog anhand lokalisierbarer APIs füllt und ihn aktualisiert, wenn sich die Quellnachrichten ändern. Localizing and varying text with a string catalog.

Prüfen Sie für das Beispiel den Eintrag summary.item-count und seine interpolierte Ganzzahl. Klicken Sie bei gedrückter Ctrl-Taste auf den Eintrag und wählen Sie Vary by Plural. Legen Sie in der englischen Ausgangslokalisierung für One den Wert %lld item und für Other den Wert %lld items fest; behalten Sie dabei den von Xcode bereitgestellten Ganzzahl-Platzhalter bei. Ergänzen Sie beim Hinzufügen weiterer Lokalisierungen die erforderlichen Formen; die Pluralkategorien hängen von der Sprache ab. Localizing and varying text with a string catalog.

Die Interpolation liefert den Zählwert, verfasst aber nicht von selbst die Formulierung im Singular. Apples Code-along zeigt, wie Pluralvarianten im Katalog ergänzt werden und das System zur Laufzeit die passende Variante auswählt. Deshalb sind ein erfolgreicher Build und eine extrahierte Nachricht nur ein Teil der Überprüfung. Code-along: Explore localization with Xcode.

Verwenden Sie nach der Konfiguration der Pluralformen für die Ausgangssprache diese kleine Abnahmematrix. Dies sind erwartete Ergebnisse für das illustrative Programm, keine berichteten Ausführungsergebnisse.

Prüfung Erwartetes Ergebnis
Erstellen und summary.item-count prüfen Ein Nachrichteneintrag mit einer Ganzzahlersetzung
Den Zählwert auf 0 setzen 0 items
Den Zählwert auf 1 setzen 1 item
Den Zählwert auf 2 setzen 2 items
Die Zeile mit der exakten Bezeichnung prüfen Sample Set bleibt wörtlich erhalten
Die Sammlungsnachricht prüfen Die Bezeichnung ist ein Argument innerhalb der vollständigen Nachricht

Fehlende Einträge getrennt von fehlerhafter Anzeige diagnostizieren

Wenn eine Nachricht im Katalog fehlt, prüfen Sie zuerst ihren Quelltyp. Ein String-Parameter kann den lokalisierbaren Ausdruck bereits gelöscht haben, bevor er die Komponente erreicht. Prüfen Sie das Ziel des Katalogs, erstellen Sie das Schema, das den betreffenden Aufrufpunkt enthält, und kontrollieren Sie Use Compiler to Extract Swift Strings. Apple beschreibt die Extraktion als einen Vorgang für das aktuelle Schema und die aktuelle Plattform. Prüfen Sie daher die Konfiguration, die die Nachricht tatsächlich kompiliert. Discover String Catalogs.

Wenn ein Eintrag vorhanden ist, die App aber einen Schlüssel oder Fallback-Text anzeigt, prüfen Sie die Suchkonfiguration. Der schlüsselbasierte Text-Initializer durchsucht die angegebene Tabelle und das angegebene Bundle; ausgelassene Werte wählen die Standardtabelle und das Haupt-Bundle. Ein fehlender Schlüssel oder eine fehlende Tabelle führt zur Zeichenfolgendarstellung des Schlüssels. Ein lesbarer Fallback kann daher eine unvollständige Suche verdecken. Text.init(_:tableName:bundle:comment:).

Wenn Sie die Komponente in ein Framework oder Paket verschieben, entscheiden Sie, wo die Nachrichten abgelegt werden. Von der Komponente verwaltete Nachrichten benötigen das Ressourcen-Bundle der Komponente; Ressourcen des Aufrufers sollten die übergebenen Suchinformationen beibehalten. Apples aktuelle Anleitung unterstützt die Übergabe von #bundle an Lokalisierungs-APIs, um das Bundle des enthaltenden Ziels anzugeben. Benannte Tabellen benötigen ebenfalls passende Kataloge. Preparing your app’s text for translation.

Gehen Sie schließlich nicht davon aus, dass jede von SwiftUI unterstützte Interpolation auch zu einer Foundation-Resource gehört. LocalizedStringKey verfügt über eigene Interpolationsmethoden, darunter formatbasierte Varianten und Varianten mit Formatierer. Wählen Sie den Nachrichtentyp, bevor Sie den Ausdruck zusammensetzen, und prüfen Sie die unterstützten Interpolationsoperationen, wenn ein Argument nicht kompiliert. LocalizedStringKey.StringInterpolation.

Eine wiederverwendbare Textkomponente ist einsatzbereit, wenn Aufrufer ihre Absicht klar ausdrücken und sie in beiden Phasen prüfen können: Der Build erzeugt die vorgesehene Katalognachricht, und die laufende Mac-App zeigt die richtige Ersetzung, Pluralform oder exakte Bezeichnung an. Behalten Sie diese Prüfungen bei Änderungen der Komponente zusammen mit dem API-Vertrag bei.

Quellen