Internationalisation des applications Flutter

Sommaire

• Concepts fondamentaux
• Flux de configuration
• Flux d'implémentation
• Formatage avancé
• Exemples

Concepts fondamentaux

Flutter gère l'internationalisation (i18n) et la localisation (l10n) via les paquets flutter_localizations et intl. L'approche standard utilise des fichiers App Resource Bundle (.arb) pour définir les chaînes localisées, qui sont ensuite compilées dans une classe AppLocalizations générée pour un accès type-safe au sein de l'arborescence des widgets.

Flux de configuration

Copiez et suivez cette liste de contrôle lors de l'initialisation de l'internationalisation dans un projet Flutter :

• [ ] Progression des tâches
  • [ ] 1. Ajouter les dépendances à pubspec.yaml.
  • [ ] 2. Activer le flag generate.
  • [ ] 3. Créer le fichier de configuration l10n.yaml.
  • [ ] 4. Configurer MaterialApp ou CupertinoApp.

1. Ajouter les dépendances

Ajoutez les paquets de localisation requis au projet. Exécutez les commandes suivantes dans le terminal :

flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any

Vérifiez que votre pubspec.yaml inclut les éléments suivants sous dependencies :

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

2. Activer la génération de code

Ouvrez pubspec.yaml et activez le flag generate dans la section flutter pour automatiser les tâches de localisation :

flutter:
  generate: true

3. Créer le fichier de configuration

Créez un nouveau fichier nommé l10n.yaml dans le répertoire racine du projet Flutter. Définissez le répertoire d'entrée, le fichier modèle et le fichier de sortie :

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

4. Configurer le point d'entrée de l'application

Importez les localisations générées et la bibliothèque flutter_localizations dans votre main.dart. Injectez les délégués et les locales supportées dans votre MaterialApp ou CupertinoApp.

import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Ajustez le chemin si synthetic-package est false

// ... à l'intérieur de la méthode build
return MaterialApp(
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'), // Anglais
    Locale('es'), // Espagnol
  ],
  home: const MyHomePage(),
);

Flux d'implémentation

Suivez ce flux lors de l'ajout ou de la modification de contenu localisé.

1. Définir les fichiers ARB

• Si vous créez du NOUVEAU contenu : Ajoutez la chaîne de base au fichier modèle (lib/l10n/app_en.arb). Incluez une description pour le contexte.
• Si vous MODIFIEZ du contenu existant : Localisez la clé dans tous les fichiers .arb supportés et mettez à jour les valeurs.

{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "The conventional newborn programmer greeting"
  }
}

Créez les fichiers correspondants pour les autres locales (par exemple, app_es.arb) :

{
  "helloWorld": "¡Hola Mundo!"
}

2. Générer les classes de localisation

Exécutez la commande suivante pour déclencher la génération de code :

flutter pub get

Boucle de rétroaction : Exécutez le validateur -> examinez la sortie du terminal pour les erreurs de syntaxe ARB -> corrigez les virgules manquantes ou les espaces réservés mal appariés -> réexécutez flutter pub get.

3. Consommer les chaînes localisées

Accédez aux chaînes localisées dans votre arborescence de widgets à l'aide de AppLocalizations.of(context). Assurez-vous que le widget qui appelle cette méthode est un descendant de MaterialApp.

Text(AppLocalizations.of(context)!.helloWorld)

Formatage avancé

Utilisez des espaces réservés pour les données dynamiques, les pluriels et les sélections conditionnelles.

Espaces réservés

Définissez les paramètres entre accolades et spécifiez leur type dans l'objet de métadonnées.

"hello": "Hello {userName}",
"@hello": {
  "description": "A message with a single parameter",
  "placeholders": {
    "userName": {
      "type": "String",
      "example": "Bob"
    }
  }
}

Pluriels

Utilisez la syntaxe plural pour gérer les variations de chaînes basées sur la quantité. Le cas other est obligatoire.

"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
"@nWombats": {
  "description": "A plural message",
  "placeholders": {
    "count": {
      "type": "num",
      "format": "compact"
    }
  }
}

Sélections

Utilisez la syntaxe select pour les chaînes conditionnelles, telles que le texte avec distinction de genre.

"pronoun": "{gender, select, male{he} female{she} other{they}}",
"@pronoun": {
  "description": "A gendered message",
  "placeholders": {
    "gender": {
      "type": "String"
    }
  }
}

Exemples

l10n.yaml complet

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
use-escaping: true

Implémentation complète du widget

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

class GreetingWidget extends StatelessWidget {
  final String userName;
  final int notificationCount;

  const GreetingWidget({
    super.key, 
    required this.userName, 
    required this.notificationCount,
  });

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

    return Column(
      children: [
        Text(l10n.hello(userName)),
        Text(l10n.nWombats(notificationCount)),
      ],
    );
  }
}