Android-App-Lokalisierung mit strings.xml

Die Lingo.dev CLI übersetzt Android-String-Ressourcen (strings.xml) über eine konfigurierte Lokalisierungs-Engine. Mit dem Format android versteht die CLI <resources>-, <string>-, <string-array>- und <plurals>-Elemente nativ, bewahrt die XML-Struktur und erzeugt für jede Zielsprache die passenden Pluralkategorien.

Dieser Leitfaden zeigt dir den kompletten Lokalisierungsprozess für eine Android-App: von der Konfiguration der CLI über lokale Übersetzungen bis zur Automatisierung in CI, damit bei jedem Push aktuelle Übersetzungen mitgeliefert werden.

So funktioniert Android-Lokalisierung#

Android folgt einer Konvention für Ressourcenverzeichnisse, bei der jede Sprache ihr eigenes Verzeichnis values-[locale]/ erhält. Zur Laufzeit lädt das System anhand der Spracheinstellung des Geräts die passende strings.xml.

app/src/main/res/
  values/              # Default (source) strings
    strings.xml
  values-es/           # Spanish
    strings.xml
  values-fr/           # French
    strings.xml
  values-ja/           # Japanese
    strings.xml

Eine typische strings.xml enthält drei Elementtypen:

<resources>
  <!-- Simple strings -->
  <string name="app_name">My App</string>
  <string name="welcome_message">Welcome back!</string>

  <!-- String arrays -->
  <string-array name="planets">
    <item>Mercury</item>
    <item>Venus</item>
    <item>Earth</item>
  </string-array>

  <!-- Plurals -->
  <plurals name="items_count">
    <item quantity="one">%d item</item>
    <item quantity="other">%d items</item>
  </plurals>
</resources>

Die CLI parst alle drei Elementtypen, übersetzt ihren Inhalt über die Lokalisierungs-Engine und schreibt für jede Sprache eigene Dateien in die richtigen Verzeichnisse values-[locale]/.

Voraussetzungen#

node -v

npm install -g @lingo.dev/cli

lingo login

CLI konfigurieren#

Führe lingo init im Stammverzeichnis deines Projekts aus, um .lingo/config.json mit deiner Quell- und Zielsprache sowie den Dateimustern zu erstellen, und anschließend lingo link, um deine Organisation und Engine zu verknüpfen. Das Ergebnis sieht dann so aus:

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android"
    }
  ]
}

Das Muster verweist auf Ihr Standard-Ressourcenverzeichnis – das unqualifizierte values/, genau dort, wo Android die Quell-Strings erwartet. Es enthält keinen Sprache-Code, und das ist auch nicht nötig.

{
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android"
    },
    {
      "pattern": "app/src/main/res/values/arrays.xml",
      "format": "android"
    }
  ]
}

Committe .lingo/config.json in dein Repository.

Sprachverzeichnisse und Qualifier#

Android legt die Standardsprache in einem unqualifizierten values/-Verzeichnis ab, daher enthält der Quellpfad keinen Sprache-Code. Die CLI erkennt das: Sie behandelt ein schlichtes values/ als Quell-Sprache und hängt für jede andere Sprache den Ziel-Qualifier an.

Regionale und skriptbasierte Sprachen sollte man hier verstehen, denn ein Ressourcen-Qualifier ist kein rohes BCP-47-Tag. Android akzeptiert zwei Schreibweisen: die ältere Sprach-Regions-Form (values-pt-rBR/) und eine BCP-47-Form mit vorangestelltem b+ (values-b+pt+BR/, ab API 24). Ein Verzeichnis namens values-pt-BR/ wird komplett ignoriert – die Strings wären zwar vorhanden, würden aber nie geladen.

Wenn Sie "format": "android" festlegen, gibt die CLI automatisch die richtige Schreibweise für Sie aus: die ältere Form überall dort, wo sie die Sprache abbilden kann, und b+ für Skripte, dreibuchstabige Sprachen und numerische Regionen.

Lokal übersetzen#

Führe die CLI aus. Beim ersten Durchlauf – oder immer dann, wenn du eine neue Zielsprache hinzufügst – verwende --backfill-missing, damit alle vorhandenen Strings übersetzt werden:

lingo push --backfill-missing

Die CLI liest deine Quell-strings.xml, identifiziert mithilfe des run state nicht übersetzte Einträge, übersetzt das Delta über deine Lokalisierungs-Engine und schreibt die Ergebnisse in die Zielverzeichnisse values-[locale]/. Öffne eine beliebige Zieldatei, um dir die übersetzten Strings anzusehen.

Bei allen weiteren Durchläufen übersetzt lingo push nur das, was sich geändert hat:

lingo push

Wenn Sie einen Lauf auf bestimmte Dateien beschränken möchten, übergeben Sie ein Glob-Muster. Die Muster werden mit Quellpfaden abgeglichen, daher grenzen Sie über die Quelldatei ein – nicht über ein Ziel:

lingo push "app/src/main/res/values/strings.xml"

Um Übersetzungen, die an anderer Stelle erzeugt wurden (zum Beispiel in CI), in deinen Arbeitsbaum zu holen, führe lingo pull aus.

Pluralformen#

Android verwendet <plurals>-Elemente mit CLDR-Mengenangaben (zero, one, two, few, many, other), um Pluralformen abzubilden. Unterschiedliche Sprachen brauchen unterschiedliche Pluralkategorien – Englisch zwei (one und other), Russisch vier und Arabisch sechs.

Die CLI bewahrt die Struktur von <plurals> bei der Übersetzung und erzeugt für jede Ziel-Sprache die richtigen Mengenkategorien. Ein Quelleintrag mit zwei Kategorien:

<plurals name="messages_count">
  <item quantity="one">%d new message</item>
  <item quantity="other">%d new messages</item>
</plurals>

So entstehen für jede Zielsprache die korrekten Kategorien. Die Lokalisierungs-Engine weiß, welche CLDR-Pluralregeln für jede Sprache gelten, und erzeugt nur die Kategorien, die diese Sprache tatsächlich benötigt.

Schlüssel sperren#

Einige String-Werte sollten in allen Sprachen identisch bleiben – etwa Markennamen, API-Endpunkte oder Formatmuster. Mit Schlüsselsperrung kannst du diese Werte ohne Übersetzung übernehmen:

{
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android",
      "lockedKeys": ["app_name", "api_base_url"]
    }
  ]
}

Gesperrte Schlüssel werden aus der Quelle in alle Zieldateien kopiert, ohne durch die Übersetzungspipeline zu laufen.

In CI automatisieren#

Die empfohlene Methode, Übersetzungen aktuell zu halten, ist die Lingo.dev GitHub App. Sie läuft serverseitig, liest dein eingechecktes .lingo/config.json und engineId und erstellt Übersetzungsupdates automatisch – ganz ohne Runner, gespeicherte Secrets oder Lockfile-Verwaltung auf deiner Seite. Installiere sie und verbinde sie mit deinem Repository, damit bei jedem Push automatisch übersetzt wird.

Wenn du die CLI lieber in deiner eigenen Pipeline ausführen möchtest, füge einen Workflow hinzu, der die CLI installiert und lingo push ausführt:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push --backfill-missing
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}

Speichere deinen API key als LINGO_API_KEY unter Settings > Secrets and variables > Actions in deinem GitHub-Repository und committe anschließend die aktualisierten Zieldateien (oder öffne als nächsten Schritt einen Pull Request).

Vor dem Deployment prüfen#

Verwende lingo check als Deployment-Gate, um sicherzustellen, dass keine unübersetzten Strings in die Produktion gelangen. Der Befehl endet mit einem Nicht-Null-Status, wenn noch Einträge übersetzt werden müssen:

lingo check

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

- name: Verify translations
  run: lingo check
  env:
    LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}

Nächste Schritte#