Flutter-Lokalisierung: ARB-Dateien, Intl & Automatisierung

Das integrierte Lokalisierungssystem von Flutter verwendet ARB-Dateien (Application Resource Bundle) und das intl-Paket, um vollständig native Erlebnisse in jeder Sprache zu bieten. Dieser Leitfaden deckt alles ab, von der Projekteinrichtung und Details zum ARB-Format bis hin zum Sprachwechsel, der 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 den flutter_gen-Codegenerator zur Erstellung typsicherer Dart-Zugriffsmethoden. Zur Laufzeit wählt Flutter die richtige ARB-Datei basierend auf der Geräte-Sprachversion aus – ein Neustart ist beim programmgesteuerten Wechsel der Sprachversionen nicht erforderlich.

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 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 @ als Präfix) enthalten Beschreibungen, Platzhalterdefinitionen und Kontext für Übersetzer.

• @@locale: Deklariert die Sprachversion 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 bewahren. 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 Sprachversionscode und der Erweiterung .arb. Flutter und l10n.dev verwenden Unterstriche zur Trennung von Sprach- und Regionscodes.

# 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 Einstellung arb-dir 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

Verknüpfen Sie die generierte Dart-Lokalisierungsklasse mit MaterialApp, indem Sie die localizationsDelegates und supportedLocales bereitstellen. Flutter löst dann die korrekten ARB-Daten für die Geräte-Sprachversion auf.

MaterialApp-Einrichtung

Übergeben Sie die vier erforderlichen Delegaten – Ihren generierten AppLocalizations.delegate sowie die drei Flutter SDK-Delegaten – und listen Sie jede Sprachversion auf, die Ihre App unterstützt. Verwenden Sie AppLocalizations.of(context)! an einer beliebigen Stelle 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, die App-Sprachversion zur Laufzeit durch Aktualisierung der locale-Eigenschaft in MaterialApp zu wechseln. Ein gängiges Muster ist es, eine Locale in einem StatefulWidget oder einer State-Management-Lösung zu halten und einen Callback zum Ändern bereitzustellen. Der Widget-Baum wird automatisch mit der neuen Sprachversion 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" }
    }
  }
}

Vollständige 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 erhalten 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-Sprachversionsformat: ARB-Sprachversionscodes verwenden Unterstriche (en_US, zh_CN) anstelle von Bindestrichen – l10n.dev verarbeitet dies korrekt, sodass generierte Dateien direkt in Ihr Flutter-Projekt übernommen 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.

Übersetzungen mit npm automatisieren

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 einem einzigen Befehl in beliebig viele 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

Sie können ai-l10n direkt in Ihren Flutter-Build-Prozess einbinden, damit Übersetzungen immer auf dem neuesten Stand sind, bevor die App kompiliert wird. Zwei gängige Ansätze sind ein package.json-Skript oder ein Makefile.

Über package.json-Skripte

Fügen Sie ein translate-Skript hinzu und verwenden Sie den prebuild-Lifecycle-Hook von npm, um es automatisch vor jedem Build auszuführen. Führen Sie npm run build:android (oder build:ios / build:web) aus, und ai-l10n übersetzt zuerst und übergibt dann an Flutter.

{
  "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 Makefile

Wenn Ihr Team Make verwendet, deklarieren Sie ein translate-Ziel und lassen Sie 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 Übersetzungen, Batch-Übersetzung über mehrere Dateien und Beispiele für GitHub Actions-Workflows, siehe den Lokalisierungsautomatisierungs-Leitfaden.

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.

In Aktion sehen

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 Nutzer zu erreichen? Sie können ARB-Dateien direkt im l10n.dev-Arbeitsbereich übersetzen, mit dem npm CLI automatisieren oder direkt in VS Code übersetzen: