Eine Flutter-App lokalisieren
Übersetze ARB-Nachrichten, generiere Flutter-Ressourcen und kontrolliere die fertige Ansicht in jeder Zielsprache.
Flutters Lokalisierungswerkzeuge wandeln ARB-Nachrichten in Methoden um, die deine Widgets aufrufen. Lingo.dev übersetzt diese ARB-Ressourcen. So kannst du weitere Sprachen hinzufügen und dabei dieselbe generierte API beibehalten. Starte mit einer Ansicht, in der du anhand einer Begrüßung und einer Elementanzahl Text, Variablen und Pluralverhalten gemeinsam kontrollieren kannst.
Diese Anleitung setzt voraus, dass das Projekt seine Quell-ARB-Datei bereits über Flutters Lokalisierungsgenerierung lädt. Behalte das vorhandene l10n.yaml, den Generator und die Widget-Aufrufe bei. Lingo.dev übernimmt hier die Übersetzung der Dateien; Flutter wählt weiterhin die Sprache aus und stellt die Nachrichten dar.
Gib jeder Nachricht die nötigen Informationen #
Für eine Quelldatei unter lib/l10n/app_en.arb kannst du einen Katalog wie diesen verwenden:
{
"@@locale": "en",
"welcome": "Welcome, {name}",
"@welcome": {
"description": "Greeting on the signed-in account screen",
"placeholders": { "name": { "type": "String" } }
},
"itemCount": "{count, plural, =0{No items} =1{One item} other{{count} items}}",
"@itemCount": {
"description": "Number of items in the cart",
"placeholders": { "count": { "type": "int" } }
}
}Die Beschreibung erklärt, wofür die Nachricht verwendet wird, und hilft so bei der Übersetzung. Die Platzhalterdefinitionen teilen Flutter mit, welche Werte der aufrufende Code liefert. Der ARB-Handler übersetzt die beiden Nachrichtentexte, behält die Metadaten bei und setzt das vorhandene Feld @@locale auf die Zielsprache.
Führe den Lokalisierungsgenerator des Projekts zunächst für die Quelle aus und verwende die generierten Begrüßungs- und Zählmethoden in der Ansicht. So stellst du sicher, dass der ursprüngliche Katalog und der aufrufende Code zusammenpassen, bevor eine weitere Sprache hinzukommt.
Verknüpfe den Katalog mit einer Lokalisierungs-Engine #
Installiere die aktuelle CLI vom Stammverzeichnis des Projekts aus und authentifiziere dich:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets de,fr --files 'lib/l10n/app_en.arb' --yes
lingo linkinit schreibt .lingo/config.json; link wählt die Organisation und die Lokalisierungs-Engine aus. Behalte die generierten Kennungen bei. Die Lokalisierungsfelder sollten ausschließlich die Quelldatei auswählen:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [
{ "pattern": "lib/l10n/app_en.arb", "format": "flutter" }
]
}Dies ist nur der Lokalisierungsteil der verknüpften Konfiguration. Er ersetzt nicht die IDs der Organisation und der Lokalisierungs-Engine. Die Dateiendung .arb wählt außerdem automatisch flutter aus. Mit dieser Struktur entstehen app_de.arb und app_fr.arb; stelle sicher, dass der Generator des Projekts beide einliest. Lege für eine andere Struktur einen expliziten Zielpfad fest.
Vermeide ein Muster für Quelldateien wie app_*.arb, das auch übersetzte Kataloge auswählt. Stimme bei regionalen Sprachvarianten die Schreibweise der Dateinamen auf die Konfiguration des Flutter-Projekts ab. Gehe nicht davon aus, dass jede Sprachkennung unverändert in einem Dateinamen funktioniert.
Übersetze und generiere die Zielressourcen #
Führe für fehlende Zieldateien Folgendes aus:
lingo push --backfill-missing --waitDer Befehl wartet auf den Abschluss und ruft die Dateien ab. Wenn der Lauf auf eine Prüfung wartet oder fehlschlägt, kläre zuerst diesen Status, bevor du Release-Ressourcen generierst. Mit einem einfachen ersten Push kannst du den Ausgangsstand der Quelle festhalten, ohne die fehlenden Übersetzungen anzufordern.
Sieh dir in den Zieldateien die Schlüssel, Beschreibungen, Platzhalternamen und -typen sowie @@locale an. Führe anschließend die Flutter-Lokalisierungsgenerierung, die Analyse, die Tests und den Build des Projekts aus. Korrigiere ungültige ICU-Ausdrücke, fehlende Platzhalter oder inkompatible Typen, bevor du fortfährst. Die ARB-Rekonstruktion erhält die Metadaten, validiert aber nicht jede übersetzte Nachricht anhand des Flutter-Generators.
Öffne die Ansicht auf Deutsch und Französisch. Gib einen kurzen und einen langen Namen ein und verwende anschließend die Anzahlen 0, 1, 2 und eine größere Zahl. Lies die Pluralformulierungen, statt nur zu kontrollieren, ob eine Zahl erscheint. Sprachen können Pluralkategorien benötigen, die in der englischen Quelle nicht vorkommen. Führe deshalb eine Prüfung der erforderlichen Formen in der Zielsprache durch. Kontrolliere die Sprachauswahl, das Fallback-Verhalten, die Textausdehnung und gegebenenfalls die Textrichtung. Die Formatierung von Datumsangaben und Zahlen bestimmt weiterhin Flutter zur Laufzeit.
Halte spätere Aktualisierungen mit der Quelle verknüpft #
Halte Konfiguration, Quelle, akzeptierte Zieldateien und .lingo/lock.json zusammen. Führe nach der Änderung einer Quellnachricht lingo push --wait aus und sieh dir die geänderte Nachricht neben einer unveränderten benachbarten Nachricht an. Eine reine Beschreibungsänderung macht den Nachrichtentext noch nicht zu einer neuen Übersetzungsaufgabe. Verwende eine begrenzte Aktualisierung, wenn der überarbeitete Kontext eine erneute Übersetzung auslösen soll.
Bearbeite keine Zieldateien, solange das Zurückschreiben noch aussteht. Um lokale Korrekturen an den Zieldateien zu schützen, reiche den Auftrag ohne --wait ein, sieh dir lingo pull --dry-run an und rufe die Ergebnisse anschließend mit lingo pull im selben checkout ab, aus dem du den Auftrag eingereicht hast. Andere Rechner benötigen Übersetzungen, die per Commit gespeichert wurden, oder eine ausdrückliche Übergabe der Artefakte. Gehe nicht davon aus, dass sie auf denselben letzten Lauf zugreifen können. Details zur Wiederherstellung findest du unter Übersetzungen nach der Prüfung bewahren.
Sobald dieser Ablauf funktioniert, nutze die GitHub App oder die CI-Automatisierung, um Übersetzung und Ressourcengenerierung vor der Prüfung zu wiederholen. Native Android-XML-Dateien und Apple-Ressourcen haben andere Vorgaben für Dateien und Laufzeitverhalten. Halte sie in einem plattformübergreifenden Projekt von der ARB-Generierung getrennt.