Um alle Lokalisierungsschlüssel in einer Mac-App zu überprüfen, erstellen Sie die relevanten Targets, gleichen Sie jede String-Tabelle mit allen unterstützten Sprachen ab und testen Sie anschließend die Nachrichtenvarianten in der laufenden App. Die Vollständigkeit des Katalogs und die korrekte Anzeige zur Laufzeit müssen separat überprüft werden.

Dieser Workflow richtet sich an Entwickler, die eine Mac-Desktop-App in Xcode pflegen. Ziel ist es, einen nachvollziehbaren Bericht über fehlende Nachrichten, unvollständige Übersetzungen, fehlerhafte Argumente und Anzeigeprobleme zu erstellen. Die Beispiele verwenden fiktive Bezeichnungen und Zahlen; sie beschreiben eine Prüfmethode, die Sie auf Ihr eigenes Projekt anwenden können.

Festlegen, wann eine Nachricht als vollständig gilt

Beginnen Sie mit einem kurzen Prüfblatt. Notieren Sie App-Target, Ressourcen-Bundle, String-Tabelle, Schlüssel, unterstützte Lokalisierung, erforderliche Varianten, Übersetzungsstatus und Laufzeitergebnis. Behandeln Sie jede Kombination aus Bundle, Tabelle und Schlüssel als eigene Nachrichtenidentität, damit identische Schlüsseltexte in verschiedenen Ressourcen keine Auslassung verdecken.

Apple dokumentiert, dass lokalisierbare APIs eine Tabelle und ein Bundle angeben können und dass Ressourcen außerhalb des Haupt-Bundles für die Suche das entsprechende Bundle benötigen. Wenn Sie nur die standardmäßige Datei Localizable.xcstrings prüfen, können daher Nachrichten an anderen Stellen der App übersehen werden. Siehe Preparing your app’s text for translation.

Lesen Sie die unterstützten Lokalisierungen des Projekts im Projekteditor ab: Wählen Sie unter Project das Projekt aus, öffnen Sie Info und prüfen Sie Localizations. Sehen Sie sich auch an, welche Ressourcen an diesen Lokalisierungen beteiligt sind. Apples Adding support for languages and regions erläutert diese Projekteinstellungen und die Ressourcenauswahl.

Für das Prüfblatt können Sie fiktive Kürzel wie Lokalisierung A, Lokalisierung B und Lokalisierung C verwenden. Halten Sie in Ihren Arbeitsunterlagen fest, welchen tatsächlichen Lokalisierungskennungen des Projekts diese Kürzel entsprechen. Es handelt sich um Bezeichnungen für das Prüfblatt, nicht um Werte, die Sie in Xcode eingeben.

Verwenden Sie für die Prüfung die folgende Definition von Vollständigkeit. Dabei handelt es sich um eine vorgeschlagene Prüfmethode, nicht um einen von Apple definierten Abschlussstatus.

Prüfung Zu dokumentierende Nachweise
Inventar Für die Nachricht sind Target, Bundle, Tabelle und Schlüssel erfasst.
Ermittlung Die Nachricht wurde aus dem Code extrahiert oder wird bewusst manuell gepflegt.
Abdeckung Für jede erforderliche Lokalisierung sind die nötigen Nachrichtenvarianten vorhanden.
Argumente Jedes Argument behält seine beabsichtigte Bedeutung und einen kompatiblen Typ.
Laufzeit Die richtige Nachricht und die richtigen Werte erscheinen in der betreffenden Mac-Oberfläche.
Ergebnis Jeder Befund wurde behoben, mit Begründung bewusst ausgeschlossen oder ist noch offen.

Zuerst das Kataloginventar erstellen, dann Übersetzungen prüfen

Öffnen Sie die vorhandenen String-Kataloge des Projekts. Wenn ein Target keinen Katalog hat, lautet der von Apple dokumentierte Weg zur Erstellung File > New > File from Template; wählen Sie anschließend String Catalog aus. Der Standardname lautet Localizable; verwenden Sie den Tabellennamen, den Ihr Code erwartet. Wählen Sie Product > Build, um den Katalog zu befüllen und zu aktualisieren. Siehe Localizing and varying text with a string catalog.

Erstellen Sie jedes relevante Mac-Schema, statt einen erfolgreichen Build als vollständiges Inventar zu betrachten. Apple erläutert, dass die Extraktion Zeichenfolgen für das aktuelle Schema und die aktuelle Plattform ermittelt. Fehlt eine Nachricht in einem Build, sollten Sie dies untersuchen, bevor Sie zu dem Schluss kommen, dass sie ungenutzt ist. Diese Einschränkung wird unter Discover String Catalogs beschrieben.

Prüfen Sie die Build-Einstellung Use Compiler to Extract Swift Strings. Laut Apple muss sie aktiviert sein, damit der Lokalisierungsexport sämtlichen lokalisierbaren Swift-Text enthält. Wenn Sie eine Austauschkopie für Übersetzungsarbeiten benötigen, wählen Sie das Projekt aus und dann Product > Export Localizations; wählen Sie anschließend die erforderlichen Lokalisierungen aus. Das exportierte .xcloc-Paket ist ein Xcode-Lokalisierungskatalog und unterscheidet sich von einer einzelnen .xcstrings-String-Tabelle. Siehe Exporting localizations.

Gehen Sie anschließend die üblichen Oberflächen der Desktop-App durch: Hauptfenster, Menüs, Symbolleiste, Einstellungen, Bereiche, leere Zustände und von der Anzahl abhängige Beschriftungen. Suchen Sie für jede app-eigene Nachricht, auf die Sie stoßen, den zugehörigen Eintrag im Prüfblatt. Diese Rückwärtsprüfung von der sichtbaren Oberfläche zum Inventar hilft, Text zu finden, der nie in einem Katalog gelandet ist.

Gehen Sie nicht davon aus, dass die Extraktion jede beliebige Zeichenfolgenexpression findet. Apple beschreibt die Extraktion über lokalisierbare APIs. Wenn eine erwartete Nachricht fehlt, untersuchen Sie, wie der Code sie erstellt und weitergibt, bevor Sie manuell einen zweiten Eintrag hinzufügen. Siehe Preparing your app’s text for translation.

Extraktion, Suche und Formatierung zur Laufzeit getrennt prüfen

Diese Vorgänge beantworten unterschiedliche Fragen. Bei der Extraktion geht es darum, ob Xcode während der Entwicklung eine Nachricht finden kann. Bei der Suche geht es darum, welche lokalisierte Ressource die laufende App abfragt. Die Formatierung zur Laufzeit liefert die variablen Inhalte, die in der ausgewählten Nachricht angezeigt werden.

In SwiftUI sind die Argumenttypen wichtig. Ein Literal wie Text("Open collection") wird bei der lokalisierten Suche berücksichtigt. Wenn Sie dem entsprechenden Initializer eine einfache String-Variable übergeben, wird diese Variable normalerweise ohne Lokalisierung angezeigt. Apple dokumentiert diesen Unterschied unter LocalizedStringKey.

Wenn Sie aus einer Variablen ausdrücklich einen LocalizedStringKey erstellen, wird damit eine Suche angefordert. Das belegt jedoch nicht, dass die Extraktion zur Build-Zeit alle möglichen Variablenwerte gefunden hat. Vergleichen Sie bei dynamisch ausgewählten Schlüsseln die vollständige Menge zulässiger Schlüssel mit dem Katalog. Untersuchen Sie jeden nicht passenden Wert, statt sich auf den Wert zu verlassen, der zufällig während eines Tests vorkam.

Interpolation spielt auch auf Nachrichtenebene eine Rolle. SwiftUI kann eine lokalisierte Nachricht mit einem Formatbezeichner suchen und den interpolierten Wert vor der Darstellung einsetzen. Apple empfiehlt in der Text-Dokumentation die Interpolation, um lokalisierbaren Text zusammenzusetzen.

Betrachten Sie als Beispiel eine Nachricht, die die Anzahl der Elemente angibt. Der Katalog enthält die lokalisierbare Nachrichtenstruktur und ihre Varianten; die veränderliche Anzahl gehört zum Laufzeitverhalten. Zum Testen der Anzahlen 1 und 24 sollten nicht allein deshalb zwei unabhängig gepflegte Schlüssel nötig sein, weil sich die Zahl geändert hat.

Eine plausibel wirkende Beschriftung ist kein starker Nachweis für eine erfolgreiche Suche. Apple weist darauf hin, dass SwiftUI den Schlüssel selbst anzeigen kann, wenn der lokalisierte Wert nicht gefunden wird. Ist ein Schlüssel lesbarer Quelltext, kann ein Suchproblem wie eine gewöhnliche Beschriftung aussehen. Prüfen Sie neben dem angezeigten Ergebnis auch die ausgewählte Lokalisierung und den Katalogeintrag. Siehe Preparing views for localization.

Jede Sprache und jede erforderliche Variante prüfen

Arbeiten Sie Tabelle für Tabelle und Lokalisierung für Lokalisierung durch. Prüfen Sie für jede Nachricht den Übersetzungsstatus, den Text, die Argumente und die erweiterten Varianten. Lassen Sie unvollständige Zeilen offen, auch wenn die übrigen Nachrichten vollständig sind.

Apples Katalog-Workflow unterscheidet zwischen New, Needs Review, übersetzten Einträgen und Stale-Zeichenfolgen. Ein veralteter Eintrag wurde im Code nicht mehr gefunden; manuell gepflegte Einträge werden bei der Synchronisierung nicht automatisch aktualisiert oder entfernt. Vergewissern Sie sich, dass ein veralteter Schlüssel nicht mehr benötigt wird, bevor Sie seine Übersetzungen löschen. Siehe Discover String Catalogs.

Klicken Sie bei anzahlabhängigen Nachrichten mit gedrückter Ctrl-Taste auf den interpolierten Schlüssel und wählen Sie Vary by Plural. Prüfen Sie jede Form, die Xcode für die jeweilige Lokalisierung bereitstellt. Die erforderlichen Formen können unterschiedlich sein; dieselbe Anzahl von Zeilen wie in der Ausgangslokalisierung reicht daher nicht als Prüfung aus. Wenn der Katalog Gerätevarianten enthält, prüfen Sie den Mac-spezifischen und den allgemeinen Wert. Apple dokumentiert beide Steuerelemente unter Localizing and varying text with a string catalog.

Prüfen Sie Argumente sowohl auf ihre Bedeutung als auch auf ihr Aussehen. Bestimmen Sie bei einer fiktiven Nachricht über Elemente in Gruppen, welches Argument die Anzahl der Elemente und welches die Anzahl der Gruppen darstellt. Eine Übersetzung kann ihre Position ändern, muss aber diese Bedeutungen beibehalten. Apples Katalog-Anleitung erläutert Argumentpositionen, Typspezifizierer und Pluralersetzungen unter Discover String Catalogs.

Ergänzen Sie Kontext, wenn eine kurze Beschriftung mehrdeutig ist. Ein Kommentar zu Open könnte erklären, dass es sich um die Aktion für eine Sammlungszeile handelt. Der SwiftUI-Parameter comment überträgt diesen Kontext in die Lokalisierungsausgabe; Apple beschreibt ihn unter Preparing views for localization.

Eine Abdeckungsmatrix verwenden, die offene Arbeit sichtbar macht

Ein einzelner Prozentwert eignet sich, um den Fortschritt des Katalogs zu verfolgen. Für die Prüfung sind jedoch getrennte Spalten für Abdeckung und Verhalten nötig. Das folgende ausgearbeitete Beispiel veranschaulicht den Grund. Die Zahlen sind fiktiv und beziehen sich auf Nachrichten-Lokalisierungs-Paare, nicht auf Messwerte einer App.

Angenommen, das Inventar enthält 48 erforderliche Nachrichten und drei unterstützte Lokalisierungen. Das ergibt 144 erforderliche Paare: 48 multipliziert mit 3. Jedes Paar kann zusätzliche Plural- oder Gerätevarianten enthalten, die separat geprüft werden müssen.

Lokalisierung Erforderliche Paare Katalogprüfungen abgeschlossen Laufzeitprüfungen abgeschlossen
Lokalisierung A 48 48 48
Lokalisierung B 48 46 44
Lokalisierung C 48 48 45
Gesamt 144 142 137

Hier müssen zwei Paare noch im Katalog bearbeitet werden, und für sieben sind die Laufzeitprüfungen noch nicht abgeschlossen. Diese Gruppen können sich überschneiden; ihre Summe ergibt daher keine verlässliche Anzahl unterschiedlicher unvollständiger Nachrichten. Ordnen Sie beide Befunde den jeweiligen Zeilen zu.

Notieren Sie für jede unvollständige Zeile einen konkreten nächsten Schritt: eine fehlende Ausgangsnachricht finden, einen Pluralzweig vervollständigen, ein Argument prüfen, die Bundle-Auswahl untersuchen oder die Oberfläche bei geringerer Breite erneut ansehen. So wird aus der Matrix eine Liste abzuarbeitender Korrekturen statt eines bloßen Fortschrittsberichts.

Die Mac-App in jeder unterstützten Lokalisierung ausführen

Verwenden Sie für wiederholbare Prüfungen auf App-Ebene die Schemaeinstellungen von Xcode. Wählen Sie Product > Scheme > Edit Scheme, dann Run, öffnen Sie Options und wählen Sie App Language und App Region. Schließen Sie den Dialog, wählen Sie das Mac-Ausführungsziel und starten Sie die App. Wiederholen Sie die Schritte für die unterstützten Kombinationen Ihrer Prüfung. Apple dokumentiert diese Abfolge unter Testing localizations when running your app.

Gehen Sie bei jedem Lauf denselben Weg durch die Oberfläche. Prüfen Sie jede Nachricht in den relevanten Zuständen: eine leere Sammlung, ein einzelnes Element, mehrere Elemente und längere fiktive Beschriftungen. Wählen Sie bei Pluralnachrichten zusätzlich die Werte, die zum Durchlaufen der in der jeweiligen Lokalisierung vorhandenen Zweige nötig sind. Eine kleine feste Menge von Zählwerten belegt keine vollständige Abdeckung der Zweige.

Prüfen Sie vollständige Sätze, eingesetzte Werte, Zeilenumbrüche, abgeschnittenen Text sowie die Breite von Menüs und Steuerelementen. Wenn eine Nachricht zwei Anzahlen enthält, variieren Sie diese unabhängig voneinander. Ändern Sie beispielsweise die Anzahl der Elemente, während die Anzahl der Gruppen gleich bleibt. So lässt sich ein Fehler bei der Zuordnung der Argumente leichter erkennen.

SwiftUI-Vorschauen können die Korrekturschleife verkürzen. Apple unterstützt das Festlegen des Umgebungswerts locale für die Vorschau und das Erstellen mehrerer lokalisierter Vorschauen, nachdem Sie diese Lokalisierungen hinzugefügt oder importiert haben. Nutzen Sie sie, um eine problematische Ansicht erneut zu prüfen, und verifizieren Sie anschließend den tatsächlichen Ablauf in der App. Siehe Previewing localizations.

Schließen Sie die Prüfung ab, wenn für jedes erforderliche Nachrichten-Lokalisierungs-Paar ein Ergebnis dokumentiert ist und die nötigen Zweige geprüft wurden. Bewahren Sie Inventar, Testablauf und offene Befunde gemeinsam auf. So lässt sich die nächste Prüfung gezielt angehen: Für eine geänderte Nachricht sind ihr Speicherort, die erwarteten Argumente, die erforderlichen Varianten und eine wiederholbare Möglichkeit zur Kontrolle der Anzeige bekannt.

Quellen