Eine iOS-App lokalisieren

Übersetze Apple-String-Kataloge oder ältere Ressourcen, ohne Sprachen in gemeinsam genutzten Dateien zu verlieren, und kontrolliere das Ergebnis anschließend in Xcode und in der App.

Eine iOS-App kann ihre bisherigen lokalisierten Textabrufe beibehalten, während ihre Ressourcendateien um eine weitere Sprache ergänzt werden. Lingo.dev übersetzt diese Ressourcen; Xcode und die App bestimmen weiterhin, welches Bundle, welche Tabelle, welche Sprache und welche Variante die Nutzer sehen.

Verwende das Format, das dein Projekt bereits lädt. String-Kataloge enthalten mehrere Sprachen in einer einzigen .xcstrings-Datei, während .strings- und .stringsdict-Ressourcen separate Dateien pro Sprache verwenden. Dieser Unterschied bestimmt, wo das Ergebnis gespeichert wird und was bei einer Aktualisierung geschützt werden muss.

Lege fest, welche Ressourcen maßgeblich sind #

Ermittle bei einem Projekt mit String-Katalogen die Entwicklungssprache, die unterstützten Zielsprachen und die von der App geladenen Kataloge. Mit Xcode 15 wurde .xcstrings eingeführt, meist unter dem Dateinamen Localizable.xcstrings. Mehrere Kataloge können Texte nach Funktion oder Bundle aufteilen. Beziehe jeden Katalog ein, der Texte für den Bildschirm bereitstellt, den du lokalisierst.

Ermittle bei älteren Ressourcen die relevanten .lproj-Verzeichnisse, String-Tabellen und Plural-Wörterbücher. Base.lproj kann Basisressourcen für die Benutzeroberfläche enthalten. Gehe nicht davon aus, dass allein deren Vorhandensein der Übersetzung vorgibt, welche Ausgangssprache oder String-Tabelle zu verwenden ist. Achte darauf, dass die Einstellung der Entwicklungssprache und die Dateikonfiguration des Projekts zusammenpassen.

Verknüpfe die Bildschirmtexte vor der Übersetzung mit lokalisierten Textabrufen. Die Übersetzung von Dateien ersetzt weder fest codierte UI-Texte noch registriert sie Ressourcen für ein Xcode-Target. Behalte Kommentare bei, die Bewertern erläutern, wer spricht und auf welchem Bildschirm der Text erscheint. Der bestehende Handler für String-Kataloge erhält diese Kommentare, übernimmt sie aber nicht in die Hinweise für Übersetzungseinheiten. Hinterlege den für die Generierung erforderlichen Kontext daher in den von der Lokalisierungs-Engine unterstützten Vorgaben.

Konfiguriere einen gemeinsam genutzten String-Katalog #

Installiere und verknüpfe die aktuelle CLI im Stammverzeichnis des Projekts:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'App/Localizable.xcstrings' --yes
lingo link

Für einen Katalog unter diesem Pfad sollte die erzeugte .lingo/config.json so aufgebaut sein:

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr"],
  "files": [{ "pattern": "App/Localizable.xcstrings" }]
}

Behalte die beim Verknüpfen erzeugten Kennungen bei, statt die Platzhalter zu kopieren. Die Dateiendung legt xcode-xcstrings fest. Jede Zielsprache wird in denselben Katalogpfad geschrieben. Dabei werden Spracheinträge ergänzt, während die Ausgangssprache und die anderen Sprachen erhalten bleiben. Eine separate targetPath ist für dieses Format mit gemeinsam genutzter Datei nicht zulässig.

Der Ausgangswert liegt innerhalb der gemeinsam genutzten Struktur:

json
{
  "sourceLanguage": "en",
  "strings": {
    "Welcome": {
      "comment": "Greeting on the signed-in home screen",
      "localizations": {
        "en": { "stringUnit": { "state": "translated", "value": "Welcome" } }
      }
    }
  },
  "version": "1.0"
}

Suche nach der Übersetzung neben en nach den Einträgen für die angeforderten Sprachen. Der Handler unterstützt auch die Endknoten der Plural- und Gerätevarianten der Ausgangssprache und überspringt Einträge, die mit shouldTranslate: false markiert sind. Fehlt einem Eintrag die Lokalisierung in der Ausgangssprache, wird sein Schlüssel als Ausgangstext verwendet. Ein technischer Schlüssel ersetzt nicht den eigentlich vorgesehenen Text. Apple-String-Kataloge erläutert diese Auswahlregeln und erklärt, warum die aktuelle Ausgangsversion und der bestehende Katalog aufeinander abgestimmt bleiben müssen.

Behalte für ältere Dateien separate Pfade bei #

Verwende bei einem älteren Projekt diese Dateieinträge anstelle des Eintrags für den gemeinsam genutzten Katalog:

json
[{ "pattern": "App/en.lproj/Localizable.strings" }, { "pattern": "App/en.lproj/Localizable.stringsdict" }]

Beziehe nur Ressourcen ein, die im Projekt tatsächlich vorhanden sind. Die Dateiendungen bestimmen die jeweiligen Handler; die spanische Ausgabe gehört in App/es.lproj/. Achte darauf, dass die Einstellung der Entwicklungssprache des Projekts zu dieser Auswahl der Ausgangssprache passt.

Die String-Schlüssel und Formatierungsplatzhalter sind Teil des Laufzeitvertrags. Behalte %@, Positionsargumente und die vom aufrufenden Code erwarteten Typen bei. Eine .stringsdict enthält eine Struktur für Pluralvariablen, die mit ihrem Formatstring konsistent bleiben muss. Orientiere dich an Apple-Strings und String-Wörterbüchern, um die jeweiligen Vorgaben einzuhalten, statt diese Dateien als beliebiges XML oder beliebigen Text zu behandeln.

Übersetze und kontrolliere das zusammengeführte Ergebnis #

Sichere den aktuellen Katalog vor dem Ersetzen in der Versionsverwaltung oder als separate Kopie. Um lokale Änderungen zu schützen, übermittle ohne --wait und sieh dir lingo pull --dry-run vor dem Abruf an. Gleiche Abweichungen ab, statt ein Überschreiben zu erzwingen. Beim Zurückschreiben nach der Wartezeit fehlt die erneute Konfliktkontrolle von Pull; siehe Übersetzungen nach der Prüfung erhalten.

Verwende für eine saubere erste Übersetzung den folgenden Befehl nur, wenn der Katalog während der Wartezeit unverändert bleibt. Bevor du einem bestehenden Projekt Sprachen hinzufügst, schließe die regulären Aktualisierungen des Ausgangstexts für bestehende Sprachen ab, rufe die Ergebnisse ab und sieh sie dir an. Halte diese Ausgangsversion anschließend beim Hinzufügen und nachträglichen Befüllen unverändert. Eine Sprache hinzufügen erläutert die erforderliche Reihenfolge:

bash
lingo push --backfill-missing --wait

Bei gemeinsam genutzten Katalogen erfolgt die Planung pro Sprache, obwohl die Datei bereits existiert. Sieh dir die Einträge für die angeforderten Sprachen an, statt nach einem neuen Dateinamen zu suchen. Ein einfacher erster Push kann den Ausgangsstand festlegen, ohne eine Übersetzung auszuführen. Verwende nach regulären Änderungen am Ausgangstext lingo push --wait. Wenn du nicht wartest, rufe das gespeicherte Ergebnis mit lingo pull in dem checkout ab, aus dem du es übermittelt hast.

Um eine Formulierung zu korrigieren, bearbeite den Zielspracheneintrag in Xcode. Der CLI-Befehl --force kann weiterhin Übersetzungen wiederverwenden, die in einem unveränderten Katalog enthalten sind. Um nach einer Änderung der Vorgaben einen einzelnen Eintrag neu zu generieren, verwende das Verfahren zur Katalogkorrektur. Dabei bleiben der Ausgangstext und die benachbarten Übersetzungen erhalten.

lingo purge überspringt String-Kataloge, da Ausgangs- und Zielsprachen denselben Pfad verwenden. Um eine ausgewählte Übersetzung neu zu generieren, verwende den Workflow zur Korrektur von String-Katalogen.

Kontrolliere das Ergebnis in Xcode und auf repräsentativen Bildschirmen #

Öffne die Ausgabe in Xcode und vergewissere dich, dass der Katalog oder die ältere Datei im vorgesehenen Target und Bundle enthalten ist. Erstelle den Build mit dem vorhandenen Schema des Projekts. Führe die App mit einer Konfiguration in der Zielsprache aus und sieh dir einen Bildschirm mit einer einfachen Beschriftung, einem formatierten Wert sowie einer Plural- oder Gerätevariante an.

Vergleiche die Platzhalter der Zielsprache mit dem aufrufenden Code. Teste Mengenangaben, die in jeder Sprache unterschiedliche Pluralformen auslösen. Die englischen Kategorien sind keine vollständige Spezifikation für jede Zielsprache. Stelle sicher, dass unveränderte Sprachen im zusammengeführten Katalog erhalten bleiben. Führe eine Prüfung langer Beschriftungen, von Texten zur Barrierefreiheit, Textkürzungen und gegebenenfalls des Rechts-nach-links-Verhaltens durch.

Die Build-Kontrollen von Xcode können Ressourcenprobleme erkennen. Die Bedeutung wird dagegen durch einen sprachlichen Bewerter oder eine geeignete Messung kontrolliert. lingo check weist weder die Vollständigkeit von .xcstrings noch das korrekte Verhalten der Apple-Pluralformen nach.

Sorge dafür, dass die Automatisierung die gemeinsam genutzte Datei erhält #

Halte Ausgangstexte, akzeptierte Zieltexte, Konfiguration und .lingo/lock.json zusammen und wähle dann die GitHub App oder einen CI-Runner für wiederkehrende Aufgaben. Der Runner verwaltet seine eigene Authentifizierung, seinen Zustand und das Zurückschreiben der Ergebnisse so, dass eine Prüfung möglich ist. Behandle einen String-Katalog-Diff bei der Prüfung als Änderung an einer gemeinsam genutzten Datei: Ermittle die Ausgangsversion sowie die geänderten und erhaltenen Sprachen, bevor du die Änderung akzeptierst.

Verwende bei plattformübergreifenden Projekten die separaten Workflows für Android und Flutter, um XML-Qualifizierer und die ARB-Generierung abzudecken. Jede Plattform benötigt weiterhin eigene Kontrollen des Ladens von Ressourcen und der dargestellten Bildschirme.