iOS-App-Lokalisierung mit Xcode String Catalogs

Die Lingo.dev CLI übersetzt Xcode String Catalogs (.xcstrings) über eine konfigurierte Lokalisierungs-Engine. String Catalogs sind Apples modernes Lokalisierungsformat, eingeführt mit Xcode 15, das alle Sprachen in einer einzigen JSON-Datei speichert. Die CLI aktualisiert diese Datei direkt – Verzeichnisse pro Sprache sind nicht mehr nötig.

Diese Anleitung zeigt dir Schritt für Schritt, wie du eine iOS-App vollständig lokalisierst: die CLI einrichten, lokal übersetzen und mit der GitHub App automatisieren, damit Übersetzungen bei jedem Push mit ausgeliefert werden.

So funktionieren String Catalogs#

Vor Xcode 15 musstest du für die iOS-Lokalisierung separate .strings- und .stringsdict-Dateien in unterschiedlichen [locale].lproj/-Verzeichnissen verwalten. String Catalogs ersetzen dieses Setup durch eine einzelne Localizable.xcstrings-Datei, die Xcode automatisch pflegt.

Wenn du in SwiftUI oder UIKit einen String als lokalisierbar markierst, erkennt Xcode ihn beim Build und fügt dem String Catalog einen Eintrag hinzu. Jeder Eintrag enthält den Ausgangs-String, seine Übersetzungen für jede konfigurierte Sprache und ein optionales Kommentarfeld, das Übersetzenden zusätzlichen Kontext gibt.

Die CLI erkennt das .xcstrings-Format an der Dateiendung, verarbeitet diese JSON-Struktur, übersetzt jeden Eintrag über die Lokalisierungs-Engine und schreibt die Übersetzungen zurück in dieselbe Datei – inklusive Kommentaren, Pluralregeln und Metadaten.

Voraussetzungen#

node -v

CLI installieren und konfigurieren#

Installiere die CLI, authentifiziere dich und richte anschließend das Projekt ein. Die vollständige Anleitung findest du im Quickstart.

npm install -g @lingo.dev/cli
lingo login

Führe lingo init im Projektstamm aus und beantworte die Prompts (Quell-Sprache, Ziel-Sprachen und das Dateimuster für deinen String Catalog). Führe danach lingo link aus, um das Projekt mit deiner Organisation und Engine zu verknüpfen. Zusammen erzeugen diese eine .lingo/config.json:

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

Committe .lingo/config.json – sie ist die maßgebliche Referenz dafür, was übersetzt wird. Das .xcstrings-Format wird über die Dateiendung erkannt. Da String Catalogs alle Sprachen in einer einzigen Datei speichern, brauchst du keinen Sprache-Platzhalter im Muster: Die CLI liest die Einträge in der Ausgangssprache und schreibt alle Zielsprachen zurück in dieselbe Datei. Das vollständige Schema findest du in der Konfigurationsreferenz.

{
  "files": [
    { "pattern": "MyApp/Localizable.xcstrings" },
    { "pattern": "MyAppWidgets/Localizable.xcstrings" }
  ]
}

Lokal übersetzen#

Starte im Projektstamm die erste Übersetzung:

lingo push --backfill-missing

Die CLI liest deinen String Catalog, übersetzt jeden fehlenden Eintrag über deine Lokalisierungs-Engine, wartet, bis der Durchlauf abgeschlossen ist, und schreibt die Ergebnisse zurück in die Datei .xcstrings. Öffne die Datei in Xcode, um die eingetragenen Übersetzungen für jede konfigurierte Sprache zu sehen.

Nachdem du Quelltexte geändert hast, übersetzt ein einfaches lingo push nur das Delta – Einträge, deren Quelle sich nicht geändert hat, werden serverseitig übersprungen und über das Lockfile nachverfolgt:

lingo push

Hinweise für Übersetzende#

String Catalogs unterstützen ein Kommentarfeld pro Eintrag, das die CLI in Übersetzungsanfragen einbezieht. Diese Kommentare liefern der Lokalisierungs-Engine wichtigen Kontext – sie klären Begriffe, geben den Ton vor oder beschreiben, wo ein String in der UI erscheint.

Wähle in Xcode im String-Catalog-Editor einen String aus und füge im Inspektor einen Kommentar hinzu. Der Kommentar wird im .xcstrings-JSON gespeichert:

{
  "sourceLanguage": "en",
  "strings": {
    "Set": {
      "comment": "Refers to a collection of items, not the verb",
      "localizations": { }
    }
  }
}

Die CLI sendet diesen Kommentar zusammen mit dem String und lenkt das Modell so zur richtigen Interpretation. „Set“ könnte ohne Kontext in vielen Sprachen als Verb übersetzt werden – der Kommentar beseitigt diese Mehrdeutigkeit. Weitere Beispiele findest du unter Translator Notes.

Pluralformen#

String Catalogs unterstützen Pluralformen nativ mit CLDR plural rules. Wenn du in Xcode eine Pluralvariante definierst, speichert der String Catalog Regeln für jede Pluralkategorie, die die Zielsprache benötigt (zero, one, two, few, many, other).

Die CLI erhält diese Struktur bei der Übersetzung und erzeugt die passenden Pluralkategorien für jede Zielsprache. Englisch verwendet zwei Kategorien (one und other), Arabisch braucht sechs, Polnisch vier und Japanisch eine. Die Lokalisierungs-Engine berücksichtigt diese Unterschiede automatisch.

Mit der GitHub App automatisieren#

Installiere die Lingo.dev GitHub App in deinem Repository für Kontinuierliche Lokalisierung – ganz ohne CI-Runner, API-Key-Secret oder Lockfile-Verwaltung. Sobald sie installiert ist und auf dein .lingo/config.json (mit seinem engineId) verweist, reagiert sie automatisch auf Pushes und Pull Requests: Sie erkennt geänderte Quelltexte, übersetzt sie über deine Engine und committet die aktualisierte Datei .xcstrings zurück in den Branch oder erstellt einen Pull Request.

Vor dem Deployment prüfen#

Verwende lingo check als Deployment-Gate, damit keine unübersetzten Strings in Produktion gehen. Der Befehl meldet fehlende oder veraltete Übersetzungen und endet mit einem Status ungleich null, wenn noch Arbeit offen ist:

lingo check

Füge es vor dem Build als separaten CI-Schritt hinzu.

Nächste Schritte#