Android-App-Lokalisierung mit strings.xml

Die Lingo.dev CLI übersetzt Android-String-Ressourcen (strings.xml) über eine konfigurierte Lokalisierungs-Engine. Der Bucket-Typ android der CLI versteht <resources>-, <string>-, <string-array>- und <plurals>-Elemente nativ, bewahrt die XML-Struktur und erzeugt für jede Ziel-Sprache die korrekten Pluralkategorien.

Diese Anleitung zeigt dir die Android-Lokalisierung von Anfang bis Ende: CLI konfigurieren, lokal übersetzen und mit GitHub Actions automatisieren, damit Übersetzungen bei jedem Push mit ausgeliefert 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

CLI konfigurieren#

Erstelle im Projektstamm eine Datei i18n.json. Der Bucket android weist die CLI an, Android-XML-Ressourcen zu parsen und pro Sprache separate Dateien anzulegen:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

Der Platzhalter [locale] wird zur Laufzeit in jeden konfigurierten Sprachcode aufgelöst. Die CLI setzt deine Ausgangssprache in das Muster ein – mit source: "en" sucht sie also nach values-en/strings.xml. Für Ziel-Sprachen entstehen values-es/strings.xml, values-fr/strings.xml und so weiter.

Das Standard-Sprachverzeichnis überbrücken#

Android speichert Standard-Strings in values/ (ohne Sprachsuffix), die CLI löst [locale] jedoch wörtlich auf und sucht nach values-en/strings.xml. Erstelle einen Symlink, um die beiden Konventionen zu verbinden:

cd app/src/main/res
ln -s values values-en

So sind die Ausgangs-Strings sowohl unter values/strings.xml sichtbar (wo Android sie erwartet) als auch unter values-en/strings.xml (wo die CLI sucht). Committe den Symlink in dein Repository – git verfolgt Symlinks unter macOS und Linux nativ.

{
  "buckets": {
    "android": {
      "include": [
        "app/src/main/res/values-[locale]/strings.xml",
        "app/src/main/res/values-[locale]/arrays.xml"
      ]
    }
  }
}

Lokal übersetzen#

API-Schlüssel setzen und CLI ausführen:

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

Die CLI liest deine Ausgangs-strings.xml, identifiziert mithilfe der Lockfile 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.

So zielst du während der Entwicklung auf eine bestimmte Sprache:

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

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:

{
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"],
      "lockedKeys": ["app_name", "api_base_url"]
    }
  }
}

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

Mit GitHub Actions automatisieren#

Füge unter .github/workflows/translate.yml eine Workflow-Datei hinzu, damit bei jedem Push übersetzt wird:

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 landen. Die CLI beendet sich mit einem Status ungleich null, wenn noch Einträge übersetzt werden müssen:

npx lingo.dev@latest run --frozen

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

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

Nächste Schritte#