Flutter-Lokalisierung: ARB-Dateien, Intl & Automatisierung

Das integrierte Lokalisierungssystem von Flutter verwendet Application Resource Bundle (ARB)-Dateien und das intl-Paket, um vollständig native Erlebnisse in jeder Sprache bereitzustellen. Dieser Leitfaden deckt alles ab, von der Projekteinrichtung und ARB-Formatdetails bis hin zum Sprachwechsel, Pluralisierung und der Automatisierung von Übersetzungen mit l10n.dev.

Was ist Flutter-Lokalisierung?

Die Flutter-Lokalisierung ist der offizielle Ansatz, um Ihre App an mehrere Sprachen und Regionen anzupassen. Sie stützt sich auf ARB-Dateien zum Speichern übersetzter Zeichenfolgen und auf den flutter_gen-Codegenerator, um typsichere Dart-Zugriffsmethoden zu erstellen. Zur Laufzeit wählt Flutter die richtige ARB-Datei basierend auf dem Gebietsschema des Geräts aus – kein Neustart erforderlich, wenn Gebietsschemas programmgesteuert gewechselt werden.

Projekteinrichtung

Die Lokalisierungspipeline von Flutter wird durch zwei Konfigurationsdateien gesteuert: pubspec.yaml und l10n.yaml. Aktivieren Sie die Codegenerierung in pubspec.yaml und verweisen Sie Flutter auf Ihr ARB-Verzeichnis.

1. pubspec.yaml aktualisieren

Fügen Sie flutter_localizations und intl als Abhängigkeiten hinzu und aktivieren Sie dann das generate-Flag, damit Flutter die Dart-Lokalisierungsklassen automatisch aus Ihren ARB-Dateien generiert.

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

2. l10n.yaml erstellen

Platzieren Sie eine l10n.yaml-Datei im Stammverzeichnis Ihres Projekts, um das ARB-Verzeichnis, die Vorlagendatei und den Namen der generierten Ausgabedatei zu konfigurieren.

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

Das ARB-Dateiformat

ARB (Application Resource Bundle) ist ein JSON-basiertes Format, das speziell für die Flutter-Internationalisierung entwickelt wurde. Jeder Schlüssel wird einer übersetzbaren Zeichenfolge zugeordnet, und optionale Metadatenschlüssel (mit @ vorangestellt) enthalten Beschreibungen, Platzhalterdefinitionen und Kontext für Übersetzer.

• @@locale: Deklariert das Gebietsschema für die Datei (z. B. "en", "fr", "zh_CN"). l10n.dev aktualisiert dies automatisch auf den Zielsprachencode.
• @@last_modified: Zeitstempel der letzten Änderung. l10n.dev setzt dies beim Generieren übersetzter Dateien automatisch auf den aktuellen UTC-Zeitstempel.
• @key-Metadaten: Metadateneinträge wie Beschreibung, Beispiel und Platzhalter werden standardmäßig NICHT übersetzt – sie bleiben unverändert, um den Kontext für Übersetzer zu wahren. Aktivieren Sie die Einstellung translateMetadata, wenn diese übersetzt werden sollen.
• Platzhalter und ICU-Nachrichten: Zeichenfolgen können benannte Platzhalter ({name}) und ICU-Nachrichtensyntax für Pluralisierung und Auswahl enthalten – all dies bleibt während der Übersetzung korrekt erhalten.

Quell-ARB-Datei (Englisch)

{
  "@@locale": "en",
  "@@last_modified": "2026-01-15T10:30:00Z",

  "appTitle": "My App",
  "@appTitle": {
    "description": "The title of the application"
  },

  "welcome": "Welcome, {name}!",
  "@welcome": {
    "description": "Welcome message shown on the home screen",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  },

  "unreadMessages": "{count, plural, =0{No unread messages} =1{1 unread message} other{{count} unread messages}}",
  "@unreadMessages": {
    "description": "Number of unread messages",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Übersetzte ARB-Datei (Französisch)

Nach der Übersetzung sind die UI-Zeichenfolgen lokalisiert, während die Metadatenstruktur intakt bleibt. l10n.dev aktualisiert @@locale und @@last_modified automatisch.

{
  "@@locale": "fr",
  "@@last_modified": "2026-01-15T10:30:01Z",

  "appTitle": "Mon Application",
  "@appTitle": {
    "description": "The title of the application"
  },

  "welcome": "Bienvenue, {name} !",
  "@welcome": {
    "description": "Welcome message shown on the home screen",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  },

  "unreadMessages": "{count, plural, =0{Aucun message non lu} =1{1 message non lu} other{{count} messages non lus}}",
  "@unreadMessages": {
    "description": "Number of unread messages",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Namenskonventionen für Dateien

ARB-Dateien folgen einem einfachen Benennungsmuster: ein Präfix (standardmäßig app_) gefolgt vom Gebietsschemacode und der Erweiterung .arb. Flutter und l10n.dev verwenden Unterstriche, um Sprach- und Regionscodes zu trennen.

# Default pattern (recommended)
app_en.arb
app_fr.arb
app_en_US.arb          # Locale with region (underscore format)
app_zh_CN.arb          # Chinese Simplified

# Custom prefix patterns also supported
my_app_en.arb
my_app_fr.arb

# Note: ARB files use underscores, not hyphens
# ✓  app_en_US.arb
# ✗  app_en-US.arb

Projektstruktur

Organisieren Sie alle Ihre ARB-Dateien in einem dedizierten l10n-Ordner innerhalb von lib/. Der Codegenerator von Flutter erkennt sie automatisch basierend auf der arb-dir-Einstellung in l10n.yaml und gibt gebrauchsfertige Dart-Klassen aus.

lib/
├── l10n/
│   ├── app_en.arb        ← Source (English)
│   ├── app_fr.arb        ← French
│   ├── app_de.arb        ← German
│   ├── app_ja.arb        ← Japanese
│   ├── app_zh_CN.arb     ← Chinese Simplified
│   └── app_es.arb        ← Spanish
├── main.dart
└── ...

# Generated output (do not edit manually)
.dart_tool/
└── flutter_gen/
    └── gen_l10n/
        └── app_localizations.dart

Initialisierung

Verbinden Sie die generierte Dart-Lokalisierungsklasse mit MaterialApp, indem Sie die localizationsDelegates und supportedLocales bereitstellen. Flutter löst dann die korrekten ARB-Daten für das Gebietsschema des Geräts auf.

MaterialApp-Einrichtung

Übergeben Sie die vier erforderlichen Delegaten – Ihren generierten AppLocalizations.delegate plus die drei Flutter SDK-Delegaten – und listen Sie jedes Gebietsschema auf, das Ihre App unterstützt. Verwenden Sie AppLocalizations.of(context)! überall im Widget-Baum, um auf übersetzte Zeichenfolgen zuzugreifen.

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',

      // Required delegates
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],

      // Supported locales
      supportedLocales: AppLocalizations.supportedLocales,

      home: const HomePage(),
    );
  }
}

// Use in a widget
class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    final l10n = AppLocalizations.of(context)!;

    return Scaffold(
      appBar: AppBar(title: Text(l10n.appTitle)),
      body: Center(child: Text(l10n.welcome('Alice'))),
    );
  }
}

Sprachwechsel zur Laufzeit

Flutter ermöglicht es Ihnen, das App-Gebietsschema zur Laufzeit durch Aktualisieren der locale-Eigenschaft in MaterialApp zu wechseln. Ein gängiges Muster ist es, ein Locale in einem StatefulWidget oder einer State-Management-Lösung zu halten und einen Callback zum Ändern bereitzustellen. Der Widget-Baum wird automatisch mit dem neuen Gebietsschema neu aufgebaut.

// Manage locale state at the app level
class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  Locale _locale = const Locale('en');

  void _changeLocale(Locale locale) {
    setState(() => _locale = locale);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      locale: _locale,
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: AppLocalizations.supportedLocales,
      home: SettingsPage(onLocaleChange: _changeLocale),
    );
  }
}

// Language selector widget
class LanguageSelector extends StatelessWidget {
  final void Function(Locale) onLocaleChange;

  const LanguageSelector({super.key, required this.onLocaleChange});

  @override
  Widget build(BuildContext context) {
    return DropdownButton<Locale>(
      value: Localizations.localeOf(context),
      items: AppLocalizations.supportedLocales
          .map((locale) => DropdownMenuItem(
                value: locale,
                child: Text(locale.toLanguageTag()),
              ))
          .toList(),
      onChanged: (locale) {
        if (locale != null) onLocaleChange(locale);
      },
    );
  }
}

Pluralisierung

Flutter verwendet ICU-Nachrichtensyntax für die Pluralisierung innerhalb von ARB-Dateien. Das intl-Paket verarbeitet alle CLDR-Pluralkategorien und wendet automatisch die korrekte Form basierend auf den Regeln der Zielsprache an.

• Verwenden Sie die Syntax {count, plural, =0{...} =1{...} other{...}} innerhalb von ARB-Zeichenfolgenwerten.
• Deklarieren Sie den count-Platzhalter mit dem Typ int in den @key-Metadaten.
• l10n.dev generiert alle erforderlichen Pluralformen für jede Zielsprache – einschließlich komplexer Sprachen wie Arabisch, Russisch und Polnisch – ohne manuellen Eingriff.

{
  "cartItems": "{count, plural, =0{Your cart is empty} =1{1 item in your cart} other{{count} items in your cart}}",
  "@cartItems": {
    "description": "Cart item count",
    "placeholders": {
      "count": { "type": "int" }
    }
  },

  "daysLeft": "{days, plural, =1{1 day left} other{{days} days left}}",
  "@daysLeft": {
    "description": "Days remaining",
    "placeholders": {
      "days": { "type": "int" }
    }
  }
}

Volle ARB-Unterstützung in l10n.dev

l10n.dev wurde speziell entwickelt, um nahtlos mit dem ARB-Workflow von Flutter zusammenzuarbeiten. Laden Sie Ihre Quell-ARB-Datei hoch und erhalten Sie präzise, korrekt strukturierte Übersetzungen zurück:

• Automatische Metadaten-Aktualisierungen: @@locale wird auf den Zielsprachencode aktualisiert und @@last_modified wird automatisch auf den aktuellen UTC-Zeitstempel gesetzt.
• Kontrolle der Metadatenübersetzung: Standardmäßig werden @key-Metadateneinträge (Beschreibung, Beispiel, Kontext) NICHT übersetzt und bleiben unverändert, wodurch Übersetzerhinweise intakt bleiben. Aktivieren Sie die Einstellung translateMetadata, um sie zusammen mit den UI-Zeichenfolgen zu übersetzen.
• Benutzerdefinierte Dateipräfixe: Jedes Benennungsmuster wird unterstützt – app_en.arb, my_app_en_US.arb, strings_fr.arb und mehr.
• Unterstrich-Gebietsschemaformat: ARB-Gebietsschemacodes verwenden Unterstriche (en_US, zh_CN) statt Bindestriche – l10n.dev handhabt dies korrekt, sodass generierte Dateien direkt in Ihr Flutter-Projekt eingefügt werden können.
• Pluralisierungsbewusst: ICU-Pluralformen werden für jede Zielsprache gemäß den CLDR-Regeln generiert, sodass nach der Übersetzung keine manuelle Pluralbearbeitung erforderlich ist.

Automatisieren Sie Übersetzungen mit npm

Verwenden Sie das ai-l10n npm-Paket, um Ihre Quell-ARB-Datei über die Befehlszeile oder als Teil einer CI/CD-Pipeline zu übersetzen. Einmal installieren, dann in einer einzigen Befehlszeile in eine beliebige Anzahl von Sprachen übersetzen.

# Install the CLI
npm install ai-l10n

# Translate your source ARB to multiple languages
npx ai-l10n translate lib/l10n/app_en.arb \
  --languages fr,de,ja,zh_CN,es,ko

Integration in einen Flutter-Build

Du kannst ai-l10n direkt in deinen Flutter-Build-Prozess einbinden, damit Übersetzungen vor dem Kompilieren der App immer auf dem neuesten Stand sind. Zwei gängige Ansätze sind ein package.json-Skript oder ein Makefile.

Über package.json-Skripte

Füge ein Übersetzungs-Skript hinzu und verwende den prebuild-Lifecycle-Hook von npm, um es automatisch vor jedem Build auszuführen. Führe npm run build:android (oder build:ios / build:web) aus und ai-l10n übersetzt zuerst, bevor es an Flutter übergibt.

{
  "scripts": {
    "translate": "ai-l10n translate lib/l10n/app_en.arb --languages fr,de,ja,zh_CN,es,ko --update",
    "prebuild": "npm run translate",
    "build:android": "flutter build apk",
    "build:ios": "flutter build ios",
    "build:web": "flutter build web"
  }
}

Über ein Makefile

Wenn dein Team Make verwendet, definiere ein Übersetzungs-Ziel (Target) und lass jedes Build-Ziel davon abhängen. Das Ausführen von make build-android (oder build-ios / build-all) übersetzt alle Zielsprachen, bevor flutter build aufgerufen wird.

LANGUAGES = fr,de,ja,zh_CN,es,ko

translate:
	npx ai-l10n translate lib/l10n/app_en.arb --languages $(LANGUAGES) --update

build-android: translate
	flutter build apk

build-ios: translate
	flutter build ios

build-web: translate
	flutter build web

build-all: translate
	flutter build apk
	flutter build ios
	flutter build web

Für CI/CD-Integration, inkrementelle Updates, Stapelübersetzung über mehrere Dateien und Beispiele für GitHub Actions-Workflows siehe den Leitfaden zur Lokalisierungsautomatisierung.

VS Code-Erweiterung

Die l10n.dev VS Code-Erweiterung bringt die Flutter ARB-Übersetzung direkt in Ihren Editor. Klicken Sie mit der rechten Maustaste auf eine beliebige ARB-Datei und übersetzen Sie sie in Ihre Zielsprachen, ohne VS Code zu verlassen.

So funktioniert es in VS Code:

1. Öffnen Sie Ihre Quell-ARB-Datei (z. B. app_en.arb) im Editor.
2. Klicken Sie mit der rechten Maustaste in den Editor und wählen Sie "Translate JSON".
3. Wählen Sie eine oder mehrere Zielsprachen (z. B. Französisch, Japanisch, Deutsch).
4. Die Erweiterung erstellt lokalisierte ARB-Dateien neben Ihrer Quelle, wobei @@locale und @@last_modified automatisch aktualisiert werden.

Sehen Sie es in Aktion

Hier ist ein Live-Beispiel für die Übersetzung einer Flutter ARB-Datei ins Usbekische innerhalb von VS Code:

Beginnen Sie mit der Lokalisierung Ihrer Flutter-App

Bereit, globale Benutzer zu erreichen? Sie können ARB-Dateien direkt im l10n.dev-Arbeitsbereich übersetzen, mit der npm CLI automatisieren oder direkt in VS Code übersetzen: