So Internationalisieren Sie Ihre Flutter-App mit ARB-Dateien: Vollständiges Tutorial

Der Aufbau einer Flutter-App, die Nutzer weltweit erreicht, erfordert eine ordnungsgemäße Internationalisierung (i18n). Während Flutter von Anfang an hervorragende i18n-Unterstützung bietet, kann das Verständnis der effektiven Verwendung von ARB-Dateien (Application Resource Bundle) den Unterschied zwischen einem umständlichen Lokalisierungs-Workflow und einem optimierten, wartbaren System ausmachen. Dieses umfassende Tutorial führt Sie durch alles, was Sie über die Internationalisierung Ihrer Flutter-App mit ARB-Dateien wissen müssen, von der Grundeinrichtung bis zu fortgeschrittenen Mustern und modernen Tools mit IntlPull.

Was sind ARB-Dateien und Warum Sollte Man Sie Verwenden?

ARB (Application Resource Bundle) ist ein JSON-basiertes Format, das speziell für die Speicherung lokalisierbarer Ressourcen entwickelt wurde. Ursprünglich von Google erstellt, sind ARB-Dateien zum Standard für Flutter-Internationalisierung geworden, da sie mehrere wichtige Vorteile bieten:

Typsicherheit: ARB-Dateien arbeiten mit Flutters Code-Generierung zusammen, um typsichere Übersetzungsmethoden zu erstellen und Fehler zur Kompilierzeit statt zur Laufzeit zu erkennen.

Umfangreiche Metadaten: Im Gegensatz zu einfachem JSON unterstützen ARB-Dateien Metadaten für jede Übersetzung, einschließlich Beschreibungen, Platzhaltern und Beispielen, die Übersetzern helfen, den Kontext zu verstehen.

ICU MessageFormat-Unterstützung: Integrierte Unterstützung für komplexe Grammatikregeln wie Plurale, Geschlechtsformen und bedingten Text.

Tool-Integration: ARB-Dateien integrieren sich nahtlos in Übersetzungsmanagementsysteme und erleichtern die Teamzusammenarbeit.

So sieht eine grundlegende ARB-Datei aus:

JSONCopy
1{
2  "@@locale": "de",
3  "helloWorld": "Hallo Welt!",
4  "@helloWorld": {
5    "description": "Die konventionelle Begrüßung des Programmieranfängers"
6  }
7}

Der Schlüssel @@locale identifiziert die Sprache, helloWorld ist Ihr Übersetzungsschlüssel, und @helloWorld enthält Metadaten, die Übersetzern helfen, den Kontext zu verstehen.

Einrichtung der Flutter-Internationalisierung

Lassen Sie uns eine vollständige Internationalisierungs-Einrichtung von Grund auf aufbauen. Wir erstellen eine einfache App, die alle Schlüsselkonzepte demonstriert.

Schritt 1: Erforderliche Abhängigkeiten Hinzufügen

Aktualisieren Sie zunächst Ihre pubspec.yaml, um die erforderlichen Pakete einzuschließen:

YAMLCopy
1dependencies:
2  flutter:
3    sdk: flutter
4  flutter_localizations:
5    sdk: flutter
6  intl: ^0.19.0
7
8flutter:
9  generate: true

Das Paket flutter_localizations bietet Lokalisierungsunterstützung für Material- und Cupertino-Widgets, während intl die Formatierung von Nachrichten, Datum/Uhrzeit und Zahlen übernimmt.

Schritt 2: Code-Generierung Konfigurieren

Erstellen Sie eine Datei namens l10n.yaml im Stammverzeichnis Ihres Projekts:

YAMLCopy
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Diese Konfiguration teilt Flutter mit, wo Ihre ARB-Dateien zu finden sind und wo der Lokalisierungscode generiert werden soll.

Schritt 3: Ihre Erste ARB-Datei Erstellen

Erstellen Sie das Verzeichnis lib/l10n und fügen Sie Ihre Vorlagendatei app_en.arb hinzu:

JSONCopy
1{
2  "@@locale": "en",
3  "appTitle": "Meine Großartige App",
4  "@appTitle": {
5    "description": "Der Titel der Anwendung"
6  },
7  "welcomeMessage": "Willkommen in unserer App!",
8  "@welcomeMessage": {
9    "description": "Nachricht auf dem Startbildschirm angezeigt"
10  },
11  "greeting": "Hallo, {name}!",
12  "@greeting": {
13    "description": "Personalisierte Begrüßung",
14    "placeholders": {
15      "name": {
16        "type": "String",
17        "example": "Alice"
18      }
19    }
20  }
21}

Schritt 4: Zusätzliche Sprachen Hinzufügen

Erstellen Sie app_de.arb für Deutsch:

JSONCopy
1{
2  "@@locale": "de",
3  "appTitle": "Meine Großartige App",
4  "welcomeMessage": "Willkommen in unserer App!",
5  "greeting": "Hallo, {name}!"
6}

Beachten Sie, dass Sie nur die Übersetzungen einschließen müssen, nicht die Metadaten. Die Metadaten aus der Vorlagendatei werden automatisch verwendet.

Schritt 5: Lokalisierungscode Generieren

Führen Sie den Code-Generierungsbefehl aus:

TerminalCopy
flutter gen-l10n

Dies erstellt typsichere Dart-Klassen in .dart_tool/flutter_gen/gen_l10n/, die Sie für den Zugriff auf Ihre Übersetzungen verwenden.

Schritt 6: Ihre App Konfigurieren

Aktualisieren Sie Ihre main.dart, um die Lokalisierung zu aktivieren:

DARTCopy
1import 'package:flutter/material.dart';
2import 'package:flutter_localizations/flutter_localizations.dart';
3import 'package:flutter_gen/gen_l10n/app_localizations.dart';
4
5void main() {
6  runApp(const MyApp());
7}
8
9class MyApp extends StatelessWidget {
10  const MyApp({super.key});
11
12  @override
13  Widget build(BuildContext context) {
14    return MaterialApp(
15      title: 'Flutter i18n Demo',
16      localizationsDelegates: const [
17        AppLocalizations.delegate,
18        GlobalMaterialLocalizations.delegate,
19        GlobalWidgetsLocalizations.delegate,
20        GlobalCupertinoLocalizations.delegate,
21      ],
22      supportedLocales: const [
23        Locale('en'),
24        Locale('de'),
25      ],
26      home: const HomeScreen(),
27    );
28  }
29}

Schritt 7: Übersetzungen in Ihren Widgets Verwenden

Jetzt können Sie in jedem Widget auf Übersetzungen zugreifen:

DARTCopy
1class HomeScreen extends StatelessWidget {
2  const HomeScreen({super.key});
3
4  @override
5  Widget build(BuildContext context) {
6    final l10n = AppLocalizations.of(context)!;
7
8    return Scaffold(
9      appBar: AppBar(
10        title: Text(l10n.appTitle),
11      ),
12      body: Center(
13        child: Column(
14          mainAxisAlignment: MainAxisAlignment.center,
15          children: [
16            Text(
17              l10n.welcomeMessage,
18              style: Theme.of(context).textTheme.headlineMedium,
19            ),
20            const SizedBox(height: 20),
21            Text(l10n.greeting('Alice')),
22          ],
23        ),
24      ),
25    );
26  }
27}

Das war's! Ihre App unterstützt jetzt mehrere Sprachen. Das Gebietsschema des Geräts bestimmt automatisch, welche Sprache angezeigt wird.

Umgang mit Pluralen und Geschlechtsformen

Eine der leistungsstärksten Funktionen von ARB-Dateien ist die Unterstützung für ICU MessageFormat, das komplexe Grammatikregeln behandelt, die zwischen Sprachen variieren.

Pluralformen

Verschiedene Sprachen haben unterschiedliche Pluralregeln. Englisch hat zwei Formen (eins/andere), aber Polnisch hat drei und Arabisch hat sechs. ARB-Dateien handhaben dies automatisch:

JSONCopy
1{
2  "itemCount": "{count, plural, =0{Keine Artikel} =1{Ein Artikel} other{{count} Artikel}}",
3  "@itemCount": {
4    "description": "Anzahl der Artikel im Warenkorb",
5    "placeholders": {
6      "count": {
7        "type": "int"
8      }
9    }
10  }
11}

Verwendung in Dart:

DARTCopy
Text(l10n.itemCount(0)); // "Keine Artikel"
Text(l10n.itemCount(1)); // "Ein Artikel"
Text(l10n.itemCount(5)); // "5 Artikel"

Geschlechtsformen

Einige Sprachen erfordern unterschiedlichen Text je nach Geschlecht:

JSONCopy
1{
2  "replyMessage": "{gender, select, male{Er hat auf Ihre Nachricht geantwortet} female{Sie hat auf Ihre Nachricht geantwortet} other{Sie haben auf Ihre Nachricht geantwortet}}",
3  "@replyMessage": {
4    "description": "Benachrichtigungsnachricht für Antworten",
5    "placeholders": {
6      "gender": {
7        "type": "String"
8      }
9    }
10  }
11}

Verwendung:

DARTCopy
Text(l10n.replyMessage('female')); // "Sie hat auf Ihre Nachricht geantwortet"

Kombination von Pluralen und Geschlecht

Sie können diese Muster für komplexe Szenarien verschachteln:

JSONCopy
1{
2  "friendRequest": "{count, plural, =1{{gender, select, male{Er} female{Sie} other{Sie}} hat Ihnen eine Freundschaftsanfrage gesendet} other{{count} Personen haben Ihnen Freundschaftsanfragen gesendet}}",
3  "@friendRequest": {
4    "placeholders": {
5      "count": {"type": "int"},
6      "gender": {"type": "String"}
7    }
8  }
9}

Datums-, Zeit- und Zahlenformatierung

ARB-Dateien unterstützen gebietsschema-bewusste Formatierung für Daten, Zeiten und Zahlen.

Datumsformatierung

JSONCopy
1{
2  "lastSeen": "Zuletzt gesehen: {date}",
3  "@lastSeen": {
4    "placeholders": {
5      "date": {
6        "type": "DateTime",
7        "format": "yMMMd"
8      }
9    }
10  }
11}

Gängige Datumsformate:

• yMMMd: 12. Feb. 2026
• yMMMMd: 12. Februar 2026
• jm: 17:30
• yMd: 12.2.2026

Verwendung:

DARTCopy
Text(l10n.lastSeen(DateTime.now()));
// Deutsch: "Zuletzt gesehen: 12. Feb. 2026"

Zahlen- und Währungsformatierung

JSONCopy
1{
2  "price": "Preis: {amount}",
3  "@price": {
4    "placeholders": {
5      "amount": {
6        "type": "double",
7        "format": "currency",
8        "optionalParameters": {
9          "symbol": "€",
10          "decimalDigits": 2
11        }
12      }
13    }
14  },
15  "discount": "Sparen Sie {percent}%",
16  "@discount": {
17    "placeholders": {
18      "percent": {
19        "type": "int",
20        "format": "compact"
21      }
22    }
23  }
24}

Verwendung:

DARTCopy
Text(l10n.price(29.99)); // "Preis: 29,99 €"
Text(l10n.discount(15)); // "Sparen Sie 15%"

Organisation Großer Übersetzungsdateien

Wenn Ihre App wächst, wird die Verwaltung von Übersetzungen komplexer. Hier sind Strategien, um die Dinge organisiert zu halten.

Namensraum nach Funktion

Anstelle einer massiven ARB-Datei teilen Sie Übersetzungen nach Funktionen auf:

lib/l10n/
  ├── app_de.arb          # Globale Zeichenketten
  ├── auth_de.arb         # Authentifizierung
  ├── profile_de.arb      # Benutzerprofil
  ├── settings_de.arb     # Einstellungen
  └── ...

Aktualisieren Sie l10n.yaml:

YAMLCopy
1arb-dir: lib/l10n
2template-arb-file: app_en.arb
3output-localization-file: app_localizations.dart
4synthetic-package: false

Beschreibende Schlüsselnamen Verwenden

Schlecht:

JSONCopy
1{
2  "btn1": "Absenden",
3  "msg2": "Ein Fehler ist aufgetreten"
4}

Gut:

JSONCopy
1{
2  "submitButton": "Absenden",
3  "networkErrorMessage": "Ein Fehler ist aufgetreten"
4}

Kontext mit Metadaten Hinzufügen

Fügen Sie immer Beschreibungen und Beispiele hinzu:

JSONCopy
1{
2  "tapToEdit": "Zum Bearbeiten tippen",
3  "@tapToEdit": {
4    "description": "Hinweistext unter bearbeitbaren Feldern angezeigt",
5    "context": "Wird im Profilbildschirm für das Bio-Feld verwendet"
6  }
7}

Dies hilft Übersetzern zu verstehen, wo und wie der Text verwendet wird, was zu besseren Übersetzungen führt.

Optimierung von Workflows mit IntlPull

Die manuelle Verwaltung von ARB-Dateien funktioniert für kleine Projekte, aber wenn Ihr Team und die Anzahl der Übersetzungen wachsen, benötigen Sie bessere Tools. IntlPull bietet eine vollständige Übersetzungsmanagement-Plattform, die speziell für Entwickler entwickelt wurde.

Warum IntlPull für Flutter?

Native ARB-Unterstützung: IntlPull versteht die ARB-Dateistruktur, einschließlich ICU MessageFormat, Platzhalter und Metadaten.

Visueller ICU-Editor: Erstellen Sie komplexe Plural- und Geschlechtsformen, ohne die ICU-Syntax auswendig zu lernen.

CLI-Integration: Automatisieren Sie die Übersetzungssynchronisierung in Ihrer CI/CD-Pipeline.

OTA-Updates: Stellen Sie Übersetzungskorrekturen sofort bereit, ohne App-Store-Einreichungen.

Chrome-Erweiterung: Bearbeiten Sie Übersetzungen direkt in Ihrer laufenden App.

Einrichtung von IntlPull CLI

Installieren Sie die CLI global:

TerminalCopy
npm install -g @intlpullhq/cli

Initialisieren Sie in Ihrem Flutter-Projekt:

TerminalCopy
cd my_flutter_app
intlpull init --framework flutter

Die CLI erkennt automatisch Ihre ARB-Dateien und erstellt eine Konfigurationsdatei:

JSONCopy
1{
2  "projectId": "ihre-projekt-id",
3  "apiKey": "ip_live_...",
4  "framework": "flutter",
5  "sourcePath": "lib/l10n",
6  "format": "arb",
7  "languages": ["en", "es", "fr", "de"],
8  "defaultLanguage": "en"
9}

Push und Pull von Übersetzungen

Laden Sie Ihre vorhandenen ARB-Dateien hoch:

TerminalCopy
intlpull push

Laden Sie die neuesten Übersetzungen herunter:

TerminalCopy
intlpull pull

Überwachen Sie Änderungen während der Entwicklung:

TerminalCopy
intlpull watch

Dieser Befehl synchronisiert Übersetzungen in Echtzeit, während Ihr Team Updates im IntlPull-Dashboard vornimmt.

Visuelle Übersetzungsbearbeitung

Das IntlPull-Dashboard bietet eine umfassende Bearbeitungserfahrung:

• Alle Sprachen nebeneinander sehen
• Visueller ICU-Editor für Plurale und Geschlechtsformen
• Screenshot-Kontext für jede Übersetzung
• Kommentar-Threads für Übersetzer-Fragen
• Übersetzungsspeicher-Vorschläge
• KI-gestützte Übersetzung mit Kontextbewusstsein

Automatisierte String-Extraktion

IntlPull kann Ihren Dart-Code scannen und hartcodierte Strings extrahieren:

TerminalCopy
intlpull scan --auto-wrap

Vorher:

DARTCopy
Text('Willkommen in unserer App')

Nachher:

DARTCopy
Text(AppLocalizations.of(context)!.welcomeToOurApp)

Die CLI fügt den neuen Schlüssel automatisch zu Ihren ARB-Dateien hinzu.

OTA-Übersetzungsupdates

Eine der leistungsstärksten Funktionen von IntlPull sind Over-The-Air (OTA)-Updates. Beheben Sie Tippfehler und aktualisieren Sie Übersetzungen, ohne den App-Store-Überprüfungsprozess zu durchlaufen.

Fügen Sie das OTA-Paket hinzu:

TerminalCopy
flutter pub add intlpull_ota

Initialisieren Sie in Ihrer App:

DARTCopy
1import 'package:intlpull_ota/intlpull_ota.dart';
2
3void main() async {
4  WidgetsFlutterBinding.ensureInitialized();
5
6  final ota = IntlPullOTA(
7    projectId: 'ihre-projekt-id',
8    apiKey: 'ip_live_...',
9    environment: 'production',
10  );
11
12  await ota.initialize();
13
14  runApp(MyApp(ota: ota));
15}

Integrieren Sie mit Ihrer Lokalisierung:

DARTCopy
1class MyApp extends StatelessWidget {
2  final IntlPullOTA ota;
3  const MyApp({required this.ota, super.key});
4
5  @override
6  Widget build(BuildContext context) {
7    return OTAProvider(
8      ota: ota,
9      child: MaterialApp(
10        localizationsDelegates: [
11          OTALocalizationsDelegate(ota),
12          AppLocalizations.delegate,
13          GlobalMaterialLocalizations.delegate,
14          GlobalWidgetsLocalizations.delegate,
15        ],
16        supportedLocales: const [
17          Locale('en'),
18          Locale('es'),
19          Locale('de'),
20        ],
21        home: const HomeScreen(),
22      ),
23    );
24  }
25}

Wenn Sie jetzt Updates von der CLI veröffentlichen:

TerminalCopy
intlpull publish --version 1.2.0 --message "Tippfehler im Checkout-Button behoben"

Alle Benutzer erhalten das Update beim nächsten App-Start. Keine App-Store-Einreichung, kein Warten auf Überprüfung, kein Zwingen der Benutzer zum Aktualisieren.

CI/CD-Integration

Fügen Sie Übersetzungsvalidierung zu Ihrer CI-Pipeline hinzu:

YAMLCopy
1# .github/workflows/ci.yml
2name: CI
3
4on: [push, pull_request]
5
6jobs:
7  validate-translations:
8    runs-on: ubuntu-latest
9    steps:
10      - uses: actions/checkout@v3
11      
12      - name: Node einrichten
13        uses: actions/setup-node@v3
14        with:
15          node-version: '18'
16      
17      - name: IntlPull CLI installieren
18        run: npm install -g @intlpullhq/cli
19      
20      - name: Übersetzungen validieren
21        env:
22          INTLPULL_API_KEY: ${{ secrets.INTLPULL_API_KEY }}
23        run: |
24          intlpull validate --missing --unused --fail-on-error
25      
26      - name: Neueste Übersetzungen herunterladen
27        run: intlpull pull
28      
29      - name: Lokalisierungen generieren
30        run: flutter gen-l10n

Dies stellt sicher:

• Keine fehlenden Übersetzungen in irgendeiner Sprache
• Keine ungenutzten Schlüssel, die Ihre ARB-Dateien überladen
• Die neuesten Übersetzungen sind immer in Builds enthalten

Testen Ihrer Internationalisierung

Ordnungsgemäße Tests stellen sicher, dass Ihre App in allen unterstützten Sprachen korrekt funktioniert.

Unit-Tests für Übersetzungen

Testen Sie, dass Übersetzungen korrekt geladen werden:

DARTCopy
1import 'package:flutter_test/flutter_test.dart';
2import 'package:flutter_gen/gen_l10n/app_localizations.dart';
3
4void main() {
5  test('Deutsche Übersetzungen werden geladen', () async {
6    final localizations = await AppLocalizations.delegate.load(
7      const Locale('de'),
8    );
9    
10    expect(localizations.appTitle, 'Meine Großartige App');
11    expect(localizations.greeting('Alice'), 'Hallo, Alice!');
12  });
13
14  test('Pluralformen funktionieren korrekt', () async {
15    final localizations = await AppLocalizations.delegate.load(
16      const Locale('de'),
17    );
18    
19    expect(localizations.itemCount(0), 'Keine Artikel');
20    expect(localizations.itemCount(1), 'Ein Artikel');
21    expect(localizations.itemCount(5), '5 Artikel');
22  });
23}

Widget-Tests

Testen Sie, dass Ihre UI Übersetzungen korrekt anzeigt:

DARTCopy
1testWidgets('Startbildschirm zeigt übersetzten Titel', (tester) async {
2  await tester.pumpWidget(
3    MaterialApp(
4      locale: const Locale('de'),
5      localizationsDelegates: const [
6        AppLocalizations.delegate,
7        GlobalMaterialLocalizations.delegate,
8        GlobalWidgetsLocalizations.delegate,
9      ],
10      supportedLocales: const [Locale('de')],
11      home: const HomeScreen(),
12    ),
13  );
14
15  expect(find.text('Meine Großartige App'), findsOneWidget);
16});

Best Practices und Häufige Fehler

Tun: Beschreibende Schlüssel Verwenden

Schlüssel sollten den Inhalt beschreiben, nicht den Ort:

Schlecht:

JSONCopy
1{
2  "homeScreen_title": "Willkommen",
3  "screen2_button1": "Absenden"
4}

Gut:

JSONCopy
1{
2  "welcomeTitle": "Willkommen",
3  "submitButton": "Absenden"
4}

Tun: Kontext Bereitstellen

Fügen Sie immer Beschreibungen und Beispiele hinzu:

JSONCopy
1{
2  "save": "Speichern",
3  "@save": {
4    "description": "Button-Text zum Speichern von Benutzerprofil-Änderungen",
5    "context": "Profil-Bearbeitungsbildschirm"
6  }
7}

Nicht Tun: Übersetzungen Verketten

Schlecht:

DARTCopy
Text(l10n.hello + ' ' + userName + '!');

Gut:

JSONCopy
{
  "greeting": "Hallo, {name}!"
}

DARTCopy
Text(l10n.greeting(userName));

Verschiedene Sprachen haben unterschiedliche Wortreihenfolgen, daher bricht Verkettung Übersetzungen.

Nicht Tun: Schlüssel für Verschiedene Kontexte Wiederverwenden

Schlecht:

JSONCopy
{
  "delete": "Löschen"
}

Verwendet sowohl für "Konto löschen" als auch "Nachricht löschen" Buttons.

Gut:

JSONCopy
1{
2  "deleteAccount": "Konto löschen",
3  "deleteMessage": "Nachricht löschen"
4}

Kontext ist wichtig für genaue Übersetzung.

Produktions-Checkliste

Vor dem Start Ihrer internationalisierten App:

• Alle ARB-Dateien enthalten dieselben Schlüssel
• Metadaten enthalten Beschreibungen für alle Strings
• Pluralformen für alle Sprachen getestet
• Datums-/Zeitformate pro Gebietsschema überprüft
• Zahlen-/Währungsformate getestet
• RTL-Layouts getestet (bei Unterstützung von Arabisch/Hebräisch)
• Übersetzungsspeicher in IntlPull gefüllt
• CI/CD validiert Übersetzungen vor Merge
• OTA-Updates für Produktion konfiguriert
• Team in ARB-Datei-Bearbeitungs-Workflow geschult
• Fallback-Gebietsschema konfiguriert (normalerweise Englisch)

Fazit

Die Internationalisierung Ihrer Flutter-App mit ARB-Dateien bietet eine robuste, typsichere Grundlage für die Erreichung globaler Zielgruppen. Indem Sie den Mustern in diesem Tutorial folgen, vermeiden Sie häufige Fallstricke und bauen ein wartbares Lokalisierungssystem auf, das mit Ihrer App skaliert.

Wichtige Erkenntnisse:

1. ARB-Dateien bieten umfangreiche Metadaten und ICU MessageFormat-Unterstützung
2. Flutters Code-Generierung gewährleistet Typsicherheit und erkennt Fehler früh
3. Ordnungsgemäße Organisation und Namenskonventionen halten Übersetzungen handhabbar
4. IntlPull optimiert Teamzusammenarbeit und Bereitstellungs-Workflows
5. OTA-Updates beseitigen den App-Store-Engpass für Übersetzungskorrekturen
6. Umfassende Tests gewährleisten Qualität in allen unterstützten Sprachen

Bereit, Ihren Flutter-Lokalisierungs-Workflow zu optimieren? Testen Sie IntlPull kostenlos mit 100 Schlüsseln und 3 Sprachen, oder erkunden Sie unsere Flutter-Dokumentation für erweiterte Integrationsmuster. Ihre globalen Benutzer werden die Aufmerksamkeit für sprachliche Details zu schätzen wissen, und Ihr Entwicklungsteam wird die eingesparte Zeit zu schätzen wissen.