Localisation Flutter : fichiers ARB, Intl et automatisation

Le système de localisation intégré de Flutter utilise des fichiers ARB (Application Resource Bundle) et le package intl pour offrir des expériences entièrement natives dans n'importe quelle langue. Ce guide couvre tout, de la configuration du projet et des détails du format ARB au changement de langue, à la pluralisation et à l'automatisation des traductions avec l10n.dev.

Qu'est-ce que la localisation Flutter ?

La localisation Flutter est l'approche officielle pour adapter votre application à plusieurs langues et régions. Elle repose sur des fichiers ARB pour stocker les chaînes traduites et sur le générateur de code flutter_gen pour produire des accesseurs Dart typés. Au moment de l'exécution, Flutter sélectionne le fichier ARB correct en fonction de la locale de l'appareil - aucun redémarrage n'est nécessaire lors du changement de locale par programmation.

Configuration du projet

Le pipeline de localisation de Flutter est piloté par deux fichiers de configuration : pubspec.yaml et l10n.yaml. Activez la génération de code dans pubspec.yaml et indiquez à Flutter votre répertoire ARB.

1. Mettre à jour pubspec.yaml

Ajoutez flutter_localizations et intl en tant que dépendances, puis activez l'indicateur generate pour que Flutter génère automatiquement les classes de localisation Dart à partir de vos fichiers ARB.

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

flutter:
  generate: true

2. Créer l10n.yaml

Placez un fichier l10n.yaml à la racine de votre projet pour configurer le répertoire ARB, le fichier modèle et le nom du fichier de sortie généré.

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

Le format de fichier ARB

ARB (Application Resource Bundle) est un format basé sur JSON conçu spécifiquement pour l'internationalisation de Flutter. Chaque clé correspond à une chaîne traduisible, et les clés de métadonnées optionnelles (préfixées par @) contiennent des descriptions, des définitions d'espaces réservés et du contexte pour les traducteurs.

• @@locale : Déclare la locale du fichier (par ex. "en", "fr", "zh_CN"). l10n.dev met automatiquement à jour ceci avec le code de la langue cible.
• @@last_modified : Horodatage de la dernière modification. l10n.dev définit automatiquement ceci sur l'horodatage UTC actuel lors de la génération des fichiers traduits.
• @key metadata : Les entrées de métadonnées telles que description, example et placeholders ne sont PAS traduites par défaut - elles restent inchangées pour préserver le contexte pour les traducteurs. Activez le paramètre translateMetadata si vous souhaitez qu'elles soient traduites.
• Espaces réservés et messages ICU : Les chaînes peuvent contenir des espaces réservés nommés ({name}) et la syntaxe de message ICU pour la pluralisation et la sélection - le tout étant correctement préservé lors de la traduction.

Fichier ARB source (anglais)

{
  "@@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"
      }
    }
  }
}

Fichier ARB traduit (français)

Après la traduction, les chaînes de l'interface utilisateur sont localisées tandis que la structure des métadonnées reste intacte. l10n.dev met à jour @@locale et @@last_modified automatiquement.

{
  "@@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"
      }
    }
  }
}

Conventions de nommage des fichiers

Les fichiers ARB suivent un modèle de nommage simple : un préfixe (par défaut app_) suivi du code de la locale et de l'extension .arb. Flutter et l10n.dev utilisent des traits de soulignement pour séparer les codes de langue et de région.

# 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

Structure du projet

Organisez tous vos fichiers ARB dans un dossier l10n dédié au sein de lib/. Le générateur de code de Flutter les récupère automatiquement en fonction du paramètre arb-dir dans l10n.yaml et génère des classes Dart prêtes à l'emploi.

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

Initialisation

Connectez la classe de localisation Dart générée avec MaterialApp en fournissant les localizationsDelegates et supportedLocales. Flutter résoudra alors les données ARB correctes pour la locale de l'appareil.

Configuration de MaterialApp

Passez les quatre délégués requis - votre AppLocalizations.delegate généré plus les trois délégués du SDK Flutter - et listez chaque locale supportée par votre application. Utilisez AppLocalizations.of(context)! n'importe où dans l'arborescence des widgets pour accéder aux chaînes traduites.

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'))),
    );
  }
}

Changement de langue à l'exécution

Flutter vous permet de changer la locale de l'application à l'exécution en mettant à jour la propriété locale sur MaterialApp. Un modèle courant consiste à conserver une Locale dans un StatefulWidget ou une solution de gestion d'état et d'exposer un rappel pour la modifier. L'arborescence des widgets se reconstruit automatiquement avec la nouvelle locale.

// 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);
      },
    );
  }
}

Pluralisation

Flutter utilise la syntaxe de message ICU pour la pluralisation à l'intérieur des fichiers ARB. Le package intl gère toutes les catégories de pluriel CLDR, appliquant automatiquement la forme correcte en fonction des règles de la langue cible.

• Utilisez la syntaxe {count, plural, =0{...} =1{...} other{...}} à l'intérieur des valeurs de chaîne ARB.
• Déclarez l'espace réservé count avec le type int dans les métadonnées @key.
• l10n.dev génère toutes les formes plurielles requises pour chaque langue cible - y compris les langues complexes telles que l'arabe, le russe et le polonais - sans intervention manuelle.

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

Support complet des ARB dans l10n.dev

l10n.dev est conçu pour fonctionner de manière transparente avec le flux de travail ARB de Flutter. Téléchargez votre fichier ARB source et recevez des traductions précises et correctement structurées :

• Mises à jour automatiques des métadonnées : @@locale est mis à jour avec le code de la langue cible et @@last_modified est automatiquement défini sur l'horodatage UTC actuel.
• Contrôle de la traduction des métadonnées : Par défaut, les entrées de métadonnées @key (description, example, context) ne sont PAS traduites et restent inchangées, gardant les notes du traducteur intactes. Activez le paramètre translateMetadata pour les traduire en même temps que les chaînes de l'interface utilisateur.
• Préfixes de fichiers personnalisés : Tout modèle de nommage est supporté - app_en.arb, my_app_en_US.arb, strings_fr.arb, et plus encore.
• Format de locale avec trait de soulignement : Les codes de locale ARB utilisent des traits de soulignement (en_US, zh_CN) au lieu de traits d'union - l10n.dev gère cela correctement afin que les fichiers générés s'intègrent directement dans votre projet Flutter.
• Conscience de la pluralisation : Les formes plurielles ICU sont générées pour chaque langue cible selon les règles CLDR, donc aucune édition manuelle du pluriel n'est nécessaire après la traduction.

Automatisez les traductions avec npm

Utilisez le package npm ai-l10n pour traduire votre fichier ARB source depuis la ligne de commande ou dans le cadre d'un pipeline CI/CD. Installez une fois, puis traduisez dans n'importe quel nombre de langues en une seule commande.

# 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

Intégration dans une build Flutter

Vous pouvez intégrer ai-l10n directement dans votre processus de build Flutter afin que les traductions soient toujours à jour avant la compilation de l'application. Deux approches courantes sont un script package.json ou un Makefile.

Via des scripts package.json

Ajoutez un script de traduction et utilisez le hook de cycle de vie prebuild de npm pour l'exécuter automatiquement avant chaque build. Exécutez npm run build:android (ou build:ios / build:web) et ai-l10n traduira d'abord, puis passera le relais à 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"
  }
}

Via Makefile

Si votre équipe utilise Make, déclarez une cible de traduction et faites en sorte que chaque cible de build en dépende. L'exécution de make build-android (ou build-ios / build-all) traduira toutes les langues cibles avant d'invoquer flutter build.

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

Pour l'intégration CI/CD, les mises à jour incrémentielles, la traduction par lots sur plusieurs fichiers et des exemples de flux de travail GitHub Actions, consultez le Guide d'automatisation de la localisation.

Extension VS Code

L'extension VS Code l10n.dev apporte la traduction ARB Flutter directement dans votre éditeur. Faites un clic droit sur n'importe quel fichier ARB et traduisez-le dans vos langues cibles sans quitter VS Code.

Comment ça fonctionne dans VS Code :

1. Ouvrez votre fichier ARB source (par ex. app_en.arb) dans l'éditeur.
2. Faites un clic droit dans l'éditeur et sélectionnez "Translate JSON".
3. Choisissez une ou plusieurs langues cibles (par ex. français, japonais, allemand).
4. L'extension crée des fichiers ARB localisés à côté de votre source, avec @@locale et @@last_modified mis à jour automatiquement.

Voyez-le en action

Voici un exemple en direct de la traduction d'un fichier ARB Flutter en ouzbek dans VS Code :

Commencez à localiser votre application Flutter

Prêt à atteindre des utilisateurs mondiaux ? Vous pouvez traduire les fichiers ARB directement dans l'espace de travail l10n.dev, automatiser avec l'interface de ligne de commande npm, ou traduire directement dans VS Code :