Ein hilfreicher Übersetzerkommentar erklärt, was ein Label bedeutet, wo es erscheint und was passiert, wenn jemand es verwendet. Diese Anleitung zeigt anhand synthetischer englischer Labels, wie solche Kommentare in Xcode für einen einfachen Mac-Formenbrowser verfasst und hinzugefügt werden.

Was sollte ein Übersetzerkommentar erklären?

Beginnen Sie mit der Entscheidung, die ein Übersetzer treffen muss. Bei einem kurzen Label wie Round bleiben die grammatische Rolle und die beabsichtigte Bedeutung unklar. Ein Kommentar kann es als Adjektiv kennzeichnen, das eine Formenkategorie beschreibt, und erklären, dass es über einer Gruppe von Vorschauen erscheint. Apple empfiehlt Kommentare, die verdeutlichen, wo und wie ein String in der Benutzeroberfläche verwendet wird. Discover String Catalogs

Wer die Labels einer Mac-App für die Übersetzung vorbereitet, sollte jeden mehrdeutigen String in eine kurze, eigenständige Erklärung umwandeln. Übersetzer sollten den Zweck verstehen können, ohne den Quellcode durchsuchen zu müssen.

Verwenden Sie diese vierteilige Schreibhilfe. Sie ist eine redaktionelle Methode, die aus Apples Empfehlungen abgeleitet ist, und kein von Apple vorgeschriebenes Kommentarformat:

Teil Zu beantwortende Frage Beispieldetail
Bedeutung Worauf bezieht sich der Ausgangstext? Round beschreibt Formen mit geschwungenen Umrissen.
Rolle in der Benutzeroberfläche Um welche Art von Oberflächentext handelt es sich? Eine Kategorieüberschrift über Formenvorschauen.
Verhalten oder Position Was geschieht, oder was befindet sich in der Nähe? Expand zeigt Details unter der Vorschau an.
Variabler Inhalt Welche Inhalte kann jeder eingefügte Wert enthalten? Der erste Wert ist ein Formenname, der zweite ein Sammlungsname.

Nehmen Sie nur Teile auf, die für die Interpretation wichtig sind. Eine statische Überschrift braucht keine Erklärung einer Aktion. Bei einer Schaltfläche ist eine klare Beschreibung dessen hilfreich, was ein Klick bewirkt. Bei einer Meldung mit zwei eingefügten Namen sollte der Zusammenhang zwischen diesen Namen erläutert werden.

Apple empfiehlt ausdrücklich, das Oberflächenelement, die umgebende Benutzeroberfläche und den durch Platzhalter dargestellten Inhalt zu erklären. Betrachten Sie diese Details als praktischen Übersetzungskontext. Discover String Catalogs

Vage Kommentare in hilfreiche Nachrichtenbeschreibungen umwandeln

Die folgenden Beispiele stammen aus einem veranschaulichenden Mac-Formenbrowser. Jeder verbesserte Kommentar beschreibt ein angenommenes, ausdrücklich benanntes Verhalten der Benutzeroberfläche. Passen Sie dieses Verhalten an das tatsächliche Steuerelement an, bevor Sie die Formulierung verwenden.

Quelltext Schwacher Kommentar Hilfreicherer Kommentar
Shapes Label für Formen. Navigationselement in der Seitenleiste, das die Liste geometrischer Formen öffnet. Substantiv im Plural.
Round Formtext. Kategorieüberschrift über Vorschauen von Formen mit geschwungenen Umrissen. Adjektiv, das die Formen beschreibt.
Expand Schaltflächentitel. Schaltfläche unter einer Formenvorschau, die deren Details darunter anzeigt. Verb, das eine Aktion ausdrückt.
Selected Auswahl-Label. Status neben der Form, die aktuell für die Vorschau ausgewählt ist. Beschreibt den aktuellen Zustand der Form.

Die schwachen Fassungen wiederholen, was Übersetzer bereits sehen können. Die stärkeren Fassungen liefern fehlende Zusammenhänge: welches Objekt das Adjektiv beschreibt, welche Inhalte die Schaltfläche anzeigt oder welches Element sich in einem bestimmten Zustand befindet.

Im Englischen bezeichnet ein Substantiv etwas, ein Adjektiv beschreibt etwas und ein Verb im Imperativ fordert zu einer Handlung auf. Diese Unterschiede helfen dabei, knappe Formulierungen in der Benutzeroberfläche zu erläutern. Selected beschreibt in diesem Beispiel etwa einen bestehenden Zustand; Select auf einer Schaltfläche würde eine Aktion anfordern. Geben Sie an, welche Interpretation die Benutzeroberfläche erfordert.

Halten Sie Kommentare konkret. Erklären Sie bei Expand, ob das Steuerelement Detailtext anzeigt, eine Vorschau vergrößert oder eine Gruppe in der Seitenleiste öffnet. Die konkrete Aktion zu nennen ist hilfreicher als zu sagen, dass dadurch etwas größer wird.

Vermeiden Sie unnötige englische Formatierungsregeln. Wenn die Benutzeroberfläche eine knappe Kategorieüberschrift benötigt, schreiben Sie das. Erfinden Sie keine feste Zeichenbegrenzung und verlangen Sie nicht, dass die Übersetzung die englische Wortstellung beibehält. Dokumentieren Sie eine tatsächliche Layoutbeschränkung nur, wenn Sie wissen, dass sie gilt.

Übersetzerkommentare in SwiftUI hinzufügen

Apple dokumentiert den Parameter comment: von Text als Möglichkeit, Übersetzungshinweise einzufügen. Wenn der praktische String-Initializer eines Steuerelements den benötigten Kommentar nicht bereitstellt, verwenden Sie den Content-Builder mit einer expliziten Text-Ansicht. Apple zeigt dieses Muster für Label und erklärt, dass es von vielen SwiftUI-Steuerelementen unterstützt wird. Preparing views for localization

Das vollständige Beispiel unten ist eine kleine macOS-SwiftUI-App. Erstellen Sie in Xcode ein macOS-App-Projekt mit SwiftUI, legen Sie das Bereitstellungsziel auf macOS 13 oder neuer fest und ersetzen Sie den generierten App- und Content-View-Code durch diese einzelne Datei. Behalten Sie nur einen App-Einstiegspunkt bei. Das Beispiel verwendet feste, synthetische Namen und zeigt einen Detailsatz an, wenn der Benutzer auf Expand klickt.

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

Dieses Beispiel wurde anhand der dokumentierten API-Muster geprüft. Es wurde hier nicht kompiliert oder ausgeführt, da die verfügbare Umgebung keine Swift-Toolchain enthält.

Für benutzerseitig sichtbare Strings, die außerhalb einer SwiftUI-Ansicht erstellt werden, dokumentiert Apple String(localized:comment:). Verwenden Sie das Kommentarargument der Lokalisierungs-API, um den Kontext an die Nachricht anzuhängen. Apple unterstützt außerdem einen separaten Suchschlüssel und einen standardmäßigen Ausgangswert, falls diese voneinander abweichen müssen. Preparing your app’s text for translation

Eingefügte Werte anhand ihrer Bedeutung und Beziehung erklären

Die Beschriftung im Beispiel enthält zwei Swift-Interpolationen: \(shapeName) und \(collectionName). Bei einer Swift-Interpolation werden die Werte von Ausdrücken in ein String-Literal eingefügt. Die Variablennamen gehören zum Quellcode; die Erklärung sollte auch für jemanden verständlich sein, der diese Namen nicht sehen kann. Strings and Characters

Für die gezeigten synthetischen Werte lautet die englische Beschriftung Circle A in Shape Set A. Der Kommentar erläutert sowohl die Reihenfolge der eingefügten Werte als auch ihre Beziehung: Einer bezeichnet die Form, der andere die Sammlung, zu der sie gehört. Das liefert hilfreichere Informationen, als lediglich zwei String-Argumente zu beschreiben.

Stellen Sie sich bei der Überprüfung einer interpolierten Nachricht drei Fragen:

  1. Welche Art von Inhalt kann an jeder Position erscheinen: ein Name, eine Anzahl oder eine andere Art von Wert?
  2. Wie stehen die Werte zueinander?
  3. Trifft der Kommentar auf jeden Wert zu, den die App einsetzen kann?

Kennzeichnen Sie Beispiele eindeutig als solche. Hier veranschaulichen Circle A und Shape Set A die Rollen der Argumente. Sie legen weder eine erforderliche Übersetzung noch eine vollständige Liste möglicher Namen fest.

Bei Anzahlen ist eine separate Implementierungsentscheidung nötig. Wenn Sie später eine Beschriftung wie 3 shapes hinzufügen, kann ein Kommentar erklären, was gezählt wird; die grammatischen Varianten gehören jedoch in den Katalog. Apple dokumentiert die Verwendung von Vary by Plural für interpolierte Anzahlen, einschließlich getrennter englischer Formen wie 1 item und 2 items. Localizing and varying text with a string catalog

Kommentare in Xcode finden und prüfen

Gehen Sie wie von Apple dokumentiert vor, um die Kommentare im Quellcode mit dem Katalog zu verknüpfen:

  1. Wählen Sie File > New > File from Template.
  2. Filtern Sie nach string, wählen Sie unter Resource die Option String Catalog und erstellen Sie den Katalog mit dem Standardnamen Localizable.
  3. Wählen Sie Product > Build, um lokalisierbare Strings zu extrahieren.
  4. Wählen Sie Localizable.xcstrings im Projektnavigator aus.
  5. Wählen Sie Editor > Assistant und dann einen Schlüssel aus, um dessen Quelle neben dem Katalog zu prüfen. Localizing and varying text with a string catalog

Prüfen Sie den Kommentar im Katalog anhand der tatsächlichen Verwendung. Im Beispiel sollte Round als Kategorieüberschrift erklärt werden und Expand das Anzeigen von Details beschreiben. Fehlt ein String, prüfen Sie, ob der Code eine lokalisierbare API verwendet und ob Use Compiler to Extract Swift Strings aktiviert ist. Apple nennt diese Build-Einstellung als Voraussetzung für die compilerbasierte Extraktion von Swift-Strings. Discover String Catalogs

Apple unterstützt auch das direkte Bearbeiten des Kontexts in der Kommentarsäule des String Catalogs. Die automatische Kommentargenerierung wurde mit Xcode 26 eingeführt; die aktuelle Dokumentation beschreibt, wie man bei gedrückter Control-Taste auf einen Schlüssel klickt und Generate Comment auswählt. Ist diese Option in Ihrer Konfiguration nicht verfügbar, fügen Sie einen Kommentar im Code hinzu oder tragen Sie ihn im Katalog ein. Code-along: Explore localization with Xcode, Localizing and varying text with a string catalog

Prüfen Sie die generierte Formulierung anhand des Verhaltens der Benutzeroberfläche. Eine Beschreibung kann eine Schaltfläche korrekt identifizieren und muss dennoch das Objekt oder Ergebnis genauer erläutern. In diesem Beispiel ist der wichtige Unterschied, dass Expand einen Detailsatz unter der Vorschau anzeigt.

Entscheiden, ob zwei identische Labels denselben Kontext verwenden können

Eine übereinstimmende englische Schreibweise bedeutet nicht, dass auch die Bedeutung übereinstimmt. Angenommen, auf einem anderen Bildschirm wird Round als Aktion zum Runden eines Zahlenwerts verwendet. Würde dieser Einsatz mit der Überschrift für eine Formenkategorie zusammengeführt, müsste ein Katalogeintrag zwei verschiedene grammatische Rollen beschreiben.

Apple erklärt, dass ein lokalisierbarer String einen Suchschlüssel hat und zu einer Tabelle gehört; Schlüssel sind innerhalb ihrer Tabelle eindeutig. Apples Swift-Dokumentation bietet außerdem eine unterstützte Möglichkeit, einen eigenen Schlüssel zusammen mit einem standardmäßigen Ausgangswert zu verwenden. Nutzen Sie getrennte Schlüssel, wenn die Bedeutungen unabhängige Übersetzungen erfordern, selbst wenn die englischen Anzeigewerte übereinstimmen. Discover String Catalogs, Preparing your app’s text for translation

Eine praktische Entscheidungsregel lautet: Fragen Sie sich, ob ein Kommentar jede Verwendung treffend erklären kann. Bleiben Bedeutung und Rolle in der Benutzeroberfläche gleich, kann ein gemeinsamer Kontext passend sein. Muss die Erklärung voneinander unabhängige Vorgänge beschreiben, sollten Sie die Schlüsselstruktur überdenken. Dies ist eine aus Apples Schlüssel- und Tabellenmodell abgeleitete Gestaltungsfolgerung und keine Regel, nach der jedes Steuerelement einen eigenen String benötigt.

Lesen Sie vor der Übergabe eines Labels den Kommentar ohne den Quellcode. Übersetzer sollten daraus die beabsichtigte Bedeutung erkennen, den Text gedanklich in der Benutzeroberfläche verorten und eingefügte Inhalte verstehen können. Überarbeiten Sie den Kommentar, wenn sich Verhalten oder Rolle des Labels ändern, damit die Erklärung weiterhin die Benutzeroberfläche beschreibt, die der Nutzer sieht.

Quellen