Um die Platzhalter einer Übersetzung auf deinem Mac zu überprüfen, vergleiche die Position, den Typ und den vorgesehenen Gebrauch jedes Arguments mit der Quellnachricht. Nutze die Diagnosemeldungen zu Abweichungen in Xcode, überprüfe anschließend Pluralersetzungen und teste das gerenderte Label mit unterschiedlichen Beispielwerten.

Diese Anleitung richtet sich an Personen, die lokalisierte Labels einer Mac-App in Xcode überprüfen. Dabei wird eine Nachricht samt Übersetzungen mit den von der App bereitgestellten Werten abgeglichen. Alle folgenden Labels sind synthetische englische Beispiele. Sie veranschaulichen Formatierungsmechanismen und sind keine tatsächlichen Übersetzungen.

Was gehört zum Argumentvertrag einer Nachricht?

Ein Argumentvertrag ist ein Prüfvermerk, der die Werte einer Nachricht beschreibt: ihre Positionen, Formattypen, Bedeutungen und erwartete Verwendung. Er ist eine praktische, aus Quellcode und Katalog abgeleitete Checkliste und kein separates Apple-Dateiformat.

Swifts String.LocalizationValue unterstützt lokalisierbare Strings mit interpolierten Laufzeitwerten. Die Dokumentation unterscheidet außerdem zwischen der Verwendung des Quelltexts als Lokalisierungsschlüssel und der Angabe eines separaten Schlüssels und Standardwerts. Daher lässt sich aus einer Kennung allein möglicherweise nicht auf die Argumente der Nachricht schließen: Prüfe den Standardquelltext und die Aufrufstelle. String.LocalizationValue

Betrachte den Formatstring Added %lld items to %@. In diesem Beispiel übergibt die App zuerst eine ganzzahlige Anzahl und danach ein objektbasiertes Label für eine Sammlung. Halte den Vertrag fest, bevor du die Übersetzung bearbeitest:

Argumentposition Bedeutung Erwartetes Format Beispielwert
1 Anzahl hinzugefügter Elemente %lld 7
2 Label der Zielsammlung %@ Canvas

Apples Formatreferenz definiert %@ als Objektkonvertierung, %d als vorzeichenbehaftete 32-Bit-Ganzzahl, %f als Double-Konvertierung und ll als Ganzzahl-Längenmodifikator für long long. Außerdem werden Positionsformate wie %1$@ dokumentiert. Bewahre die vollständige Typangabe: Wenn du %lld in %d änderst, ändert sich der erwartete Ganzzahltyp. Die Referenz ist archiviert. Nutze sie daher zusammen mit der aktuellen Katalogdokumentation für die Formatsyntax. String Format Specifiers

Ergänze die Bedeutung der Argumente im Prüfvermerk, auch wenn ihre Typen identisch sind. Bei Moved %@ to %@ kann eine Typprüfung das Label des Elements nicht vom Label des Ziels unterscheiden. Auch bei korrekter Syntax muss die Zuordnung zwischen Werten und Wörtern stimmen.

Wie findest du die maßgebliche Quelle in Xcode?

Öffne das Projekt in Xcode und bestimme den Katalog, der die Nachricht enthält. Wenn sich die Quelle geändert hat, wähle Product > Build, um die extrahierten Strings zu aktualisieren. Wähle den Katalog im Projekt-Navigator aus, dann Editor > Assistant, und wähle den Nachrichtenschlüssel, um die Quelle anzuzeigen. Apple dokumentiert diesen Arbeitsablauf zum Auffinden und Aktualisieren von Katalogeinträgen. Localizing and varying text with a string catalog

Prüfe, welche Werte die Aufrufstelle tatsächlich übergibt, in welcher Reihenfolge und über welche Lokalisierungs-API. Apple empfiehlt lokalisierbare APIs wie String(localized:). Bei einem Initializer mit separatem defaultValue ist der erste Parameter der Schlüssel und der zweite der Standardquelltext. Das ist wichtig, wenn eine neutrale Kennung wie collection.added.summary die Nachricht enthält. Preparing your app’s text for translation

Halte drei Dinge gemeinsam fest: Katalog und Schlüssel, den Standardquelltext sowie die geordneten Bedeutungen und Typen der Argumente. Wenn diese Angaben voneinander abweichen, kläre den Widerspruch, bevor du Übersetzungen anpasst. Andernfalls könnte die Übersetzung zu einer veralteten Quelle passen statt zu den aktuellen Eingaben der App.

Gib auch Kontext für spätere Bearbeitungen an. Apple unterstützt Kommentare zu lokalisierbaren Strings, die deren Verwendung erläutern. Ein hilfreicher synthetischer Kommentar könnte festhalten, dass Argument 1 die Anzahl der Elemente und Argument 2 das Label der Zielsammlung ist. So erhält die lokalisierende Person Informationen, die ein Formatbezeichner nicht vermitteln kann. Preparing your app’s text for translation

Wie prüfst du Anzahl, Typen und Argumentpositionen?

Apple hat die Validierung von String-Katalogen für häufige Probleme eingeführt, darunter abweichende Formatbezeichner. Für manche Probleme stehen Korrekturen zur Verfügung. Prüfe alle Diagnosemeldungen, die Xcode für den Eintrag anzeigt. Betrachte einen vorgeschlagenen Korrekturvorschlag als Syntaxreparatur und vergewissere dich, dass er die Bedeutung der Nachricht erhält. Build multilingual-ready apps

Für eine einfache Nachricht ohne Pluralersetzungen gehst du bei der Überprüfung so vor:

  1. Ermittle alle Platzhalter, die Argumente verbrauchen, im Quelltext und im zu prüfenden Text.
  2. Ordne jeden Platzhalter seiner Argumentposition zu.
  3. Vergleiche den vollständigen Formattyp mit dem Vertrag.
  4. Prüfe, ob jeder erforderliche Wert an der Stelle erscheint, an der ihn der Wortlaut erwartet.
  5. Untersuche einzeln, ob Verweise hinzugekommen sind, fehlen oder wiederholt werden.

Mit Positionsangaben kann eine Übersetzung die Wortstellung ändern und trotzdem die Argumentzuordnung beibehalten. In %2$@: added %1$lld items verweist der erste sichtbare Platzhalter auf Argument 2, der zweite auf Argument 1. Apple dokumentiert die Positionssyntax n$. String Format Specifiers

Die folgende Entscheidungstabelle gilt für den obigen beispielhaften Vertrag mit zwei Argumenten. Sie zeigt mögliche Prüfergebnisse und keine Resultate eines Xcode-Laufs:

Formattext im Entwurf Prüfergebnis Begründung
Added %lld items to %@ Entspricht dem einfachen Vertrag Erst die Anzahl, dann das Ziel
%2$@: added %1$lld items Entspricht dem Vertrag nach Umstellung Explizite Positionen erhalten beide Argumentzuordnungen
Added %d items to %@ Ganzzahltyp korrigieren Argument 1 verwendet nicht mehr den erwarteten Längenmodifikator
Added %lld items Auslassung untersuchen Das für diese Nachricht erforderliche Ziel fehlt
Added %1$lld items to %1$@ Verweise korrigieren Für Argument 1 werden widersprüchliche Typen verwendet; Argument 2 fehlt
Added %1$lld items to %2$@ (%2$@) Wiederholung überprüfen Es gibt drei Vorkommen, aber nur zwei verschiedene referenzierte Argumente

Unterscheide zwischen der Anzahl der Vorkommen und der Anzahl verschiedener Argumente. Die letzte Zeile zeigt den Unterschied: Eine Wiederholung von Argument 2 erzeugt keinen dritten übergebenen Wert. Ob die Wiederholung in den Wortlaut gehört, ist eine redaktionelle Entscheidung. Bei dieser Prüfung solltest du sie markieren, bis ihr Zweck geklärt ist.

Zähle ebenso wenig jedes Prozentzeichen als Argument. Apple definiert %% als literales Prozentzeichen. Ein Formatstring wie Scale: %lld%% enthält einen Wertplatzhalter und ein maskiertes Prozentzeichen. String Format Specifiers

Warum müssen Pluralersetzungen anders geprüft werden?

Bei Nachrichtentexten mit Pluralformen müssen sowohl der Auswahlmechanismus als auch der Text geprüft werden, der einen Wert anzeigt. In seiner Sitzung zu String-Katalogen erklärt Apple, dass Ersetzungen Wörterbücher mit Pluralfällen enthalten können. Der Inspektor zeigt die Position des steuernden Arguments und den C-Formatbezeichner. Eine Ersetzung kann sich daher auf ein Argument stützen, auch wenn ein bestimmter Zweig dieses Argument nicht als Zahl ausgibt. Discover String Catalogs

Vergleiche bei einer synthetischen Nachricht zur Elementanzahl One item added mit %lld items added. Im ersten Zweig wird die Anzahl ausgeschrieben, im zweiten wird sie angezeigt. Eine Regel, die in jedem Zweig eine identische Anzahl sichtbarer Platzhalter verlangt, würde den ersten unnötigerweise ablehnen. Apples dokumentiertes Verhalten für stringsdict-Wörterbücher erlaubt ausdrücklich, den numerischen Formatbezeichner in Pluralformen auszulassen, und nennt das Ausschreiben der Zahl als Möglichkeit. Stringsdict file format

Prüfe die einzelnen Zweige stattdessen folgendermaßen:

  • Prüfe im Inspektor die Position und den Typ des Arguments, das die Ersetzung steuert.
  • Prüfe alle für die Zielsprache vorhandenen Pluralzweige.
  • Gleiche jeden angezeigten Platzhalter mit dem Argument ab, auf das er verweist.
  • Erkläre durch den Wortlaut des Zweigs, warum eine numerische Anzeige ausgelassen wird.
  • Prüfe andere Nachrichtenargumente separat: Das Ausschreiben einer Anzahl erklärt kein fehlendes Label einer Sammlung.

Bei zwei unabhängig veränderlichen Anzahlen müssen die Rollen getrennt bleiben. In einer synthetischen Nachricht zu Elementen und Sammlungen muss die Elementanzahl die Ersetzung für Elemente steuern und die Sammlungsanzahl die Ersetzung für Sammlungen. Apple dokumentiert mehrere Ersetzungen innerhalb einer Nachricht und erklärt, dass die Laufzeitausgabe die ausgewählten Pluralfälle kombiniert. Discover String Catalogs

Wie bestätigst du die korrigierte Nachricht auf deinem Mac?

Baue die App nach der Korrektur des Eintrags und prüfe alle verbleibenden Diagnosemeldungen im Katalog. Führe dann den betreffenden Bildschirm in der Zielsprache aus. Der von Apple beschriebene Arbeitsablauf: Wähle Product > Scheme > Edit Scheme, dann Run, öffne Options, wähle App Language und die passende App Region, klicke auf Close und starte das ausgewählte Ziel. Testing localizations when running your app

Wähle Beispielwerte, bei denen Vertauschungen auffallen. Verwende für zwei Argumente mit Anzahlen verschiedene Zahlen, etwa 2 und 7. Verwende für zwei Textargumente unterschiedliche Labels wie Tile und Canvas. Das sind beispielhafte Testeingaben. Sie sollen zeigen, welcher übergebene Wert in welchem Teil der Nachricht erscheint.

Teste bei Nachrichten mit Pluralformen Werte, die die zu prüfenden Zweige auswählen. Wenn zwei Ersetzungen unabhängig voneinander variieren, nimm Kombinationen auf, bei denen sich eine Anzahl ändert und die andere gleich bleibt. Prüfe sowohl den ausgewählten Wortlaut als auch die Position jedes angezeigten Werts. Eine erfolgreiche Darstellung bei nur einer Kombination lässt die übrigen Zweige ungeprüft.

Behandle den Übersetzungsstatus getrennt von der Vertragsprüfung. Apple beschreibt das grüne Häkchen im Katalog als Status „übersetzt“, nachdem Text eingegeben wurde. Halte die tatsächlich ausgeführten Prüfungen fest – Argumentzuordnung, Typvergleich, Überprüfung der Zweige und gerenderte Beispiele –, statt das Statussymbol als Beleg für alle vier zu betrachten. Localizing and varying text with a string catalog

Die Nachricht kann weiterverwendet werden, wenn ihre Platzhalter den vorgesehenen übergebenen Argumenten zugeordnet sind, ihre Typen stimmen und jede zweigspezifische Auslassung oder Wiederholung nachvollziehbar erklärt ist. Ein kompakter Vertrag neben der Nachricht erleichtert die Beurteilung der nächsten Änderung an Quelle oder Übersetzung.

Quellen