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 den kompletten Prozess der iOS-App-Lokalisierung: von der CLI-Konfiguration über lokale Übersetzungen bis zur Automatisierung mit GitHub Actions, 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.

Der Bucket-Typ xcode-xcstrings der CLI 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

Die CLI konfigurieren#

Erstelle im Stammverzeichnis deines Projekts eine i18n.json-Datei. Der Bucket xcode-xcstrings weist die CLI an, das String-Catalog-Format zu verarbeiten und die Datei direkt zu aktualisieren:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "xcode-xcstrings": {
      "include": ["MyApp/Localizable.xcstrings"]
    }
  }
}

Da String Catalogs alle Sprachen in einer einzigen Datei speichern, brauchst du im Include-Muster keinen [locale]-Platzhalter. Die CLI liest die Einträge der Ausgangssprache, übersetzt sie und schreibt alle Zielsprachen zurück in dieselbe .xcstrings-Datei.

{
  "buckets": {
    "xcode-xcstrings": {
      "include": [
        "MyApp/Localizable.xcstrings",
        "MyAppWidgets/Localizable.xcstrings"
      ]
    }
  }
}

Lokal übersetzen#

Lege deinen API-Schlüssel fest und führe die CLI aus:

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

Die CLI liest deinen String Catalog, identifiziert mithilfe der lockfile nicht übersetzte Einträge, übersetzt das Delta über deine Lokalisierungs-Engine und schreibt die Ergebnisse zurück in die .xcstrings-Datei. Öffne die Datei in Xcode, um die eingetragenen Übersetzungen für jede konfigurierte Sprache zu sehen.

So targetest du während der Entwicklung eine bestimmte Sprache:

npx lingo.dev@latest run --target-locale es

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 GitHub Actions automatisieren#

Füge unter .github/workflows/translate.yml eine Workflow-Datei hinzu, um bei jedem Push automatisch zu übersetzen:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Speichere deinen API-Schlüssel als LINGODOTDEV_API_KEY unter Settings > Secrets and variables > Actions in deinem GitHub-Repository.

Vor dem Deployment prüfen#

Verwende das Flag --frozen als Deployment-Gate, um sicherzustellen, dass keine unübersetzten Strings in Produktion gelangen. Die CLI beendet sich mit einem Fehlerstatus ungleich null, wenn Einträge noch übersetzt werden müssen:

npx lingo.dev@latest run --frozen

Füge das als separaten CI-Schritt vor deinem Build hinzu:

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

Nächste Schritte#