Using the intl Package for Internationalization in Flutter

In today’s globalized world, creating applications that support multiple languages and regional formats is crucial. Flutter simplifies this process with its powerful internationalization (i18n) support. The intl package is a cornerstone of Flutter’s i18n implementation, providing tools for handling translations, date/time formatting, number formatting, and more. This comprehensive guide covers how to effectively use the intl package in Flutter to internationalize your app.

What is Internationalization (i18n)?

Internationalization is the design and development of applications to ensure they can be adapted to various languages and regions without engineering changes. Localization (l10n) is the process of adapting an internationalized application for a specific region or language by adding locale-specific components and translating text.

Why is Internationalization Important?

• Global Reach: Increases the potential user base of your app.
• User Experience: Provides a better user experience by displaying content in the user’s preferred language and format.
• Accessibility: Makes your app accessible to a wider audience, including those who may not be fluent in your app’s default language.

Setting Up the intl Package in Flutter

To begin, add the intl and flutter_localizations packages to your pubspec.yaml file.

Step 1: Add Dependencies

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.18.0

Run flutter pub get to install the dependencies.

Step 2: Configure l10n.yaml

Create an l10n.yaml file in the root of your Flutter project. This file configures the localization process.

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

Here’s what each property means:

• arb-dir: The directory where your ARB (Application Resource Bundle) files are stored.
• template-arb-file: The ARB file used as a template. This is typically the English version of your translations.
• output-localization-file: The Dart file that will be generated, containing the localization classes.

Step 3: Create ARB Files

Create ARB files in the lib/l10n directory. An ARB file is a JSON file that contains key-value pairs for each translated string. Create app_en.arb for English (the default language) and app_es.arb for Spanish, for example.

lib/l10n/app_en.arb

{
  "helloWorld": "Hello, World!",
  "welcomeMessage": "Welcome to our app!",
  "@welcomeMessage": {
    "description": "The welcome message displayed on the home screen."
  }
}

lib/l10n/app_es.arb

{
  "helloWorld": "¡Hola, Mundo!",
  "welcomeMessage": "¡Bienvenido a nuestra aplicación!",
  "@welcomeMessage": {
    "description": "El mensaje de bienvenida que se muestra en la pantalla de inicio."
  }
}

Note the @welcomeMessage entry. It provides metadata for the welcomeMessage, which can be used for description and other purposes.

Step 4: Generate the Localization Class

Run the following command in the terminal to generate the app_localizations.dart file:

flutter gen-l10n

This command uses the l10n.yaml file to generate the localization classes based on your ARB files.

Step 5: Configure MaterialApp

In your main.dart file, configure the MaterialApp to use the generated localizations.

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

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: [
        Locale('en'), // English
        Locale('es'), // Spanish
      ],
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(AppLocalizations.of(context)!.helloWorld),
      ),
      body: Center(
        child: Text(AppLocalizations.of(context)!.welcomeMessage),
      ),
    );
  }
}

Explanation:

• localizationsDelegates: Specifies the delegates responsible for providing localized values.
• supportedLocales: Defines the locales that your app supports.
• Use AppLocalizations.of(context)!.helloWorld to access the translated string in your widgets.

Handling Pluralization

Pluralization is essential when your app needs to display different text based on a count (e.g., “1 message” vs. “5 messages”). The intl package provides the PluralFormat class for handling this.

Step 1: Add Plural Forms in ARB Files

lib/l10n/app_en.arb

{
  "messageCount": "{count,plural, =0{No messages} =1{One message} other{{count} messages}}",
  "@messageCount": {
    "description": "Displays the number of messages."
  }
}

lib/l10n/app_es.arb

{
  "messageCount": "{count,plural, =0{Sin mensajes} =1{Un mensaje} other{{count} mensajes}}",
  "@messageCount": {
    "description": "Muestra el número de mensajes."
  }
}

Step 2: Use PluralFormat in Your Code

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

class MyHomePage extends StatelessWidget {
  final int messageCount = 5;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(AppLocalizations.of(context)!.helloWorld),
      ),
      body: Center(
        child: Text(AppLocalizations.of(context)!.messageCount(messageCount)),
      ),
    );
  }
}

Make sure your app_localizations.dart file is regenerated after modifying ARB files.

Handling Date and Time Formatting

The intl package provides classes for formatting dates and times according to the user’s locale.

Step 1: Use DateFormat

import 'package:intl/intl.dart';

void main() {
  DateTime now = DateTime.now();
  
  // Format date and time according to the user's locale
  String formattedDate = DateFormat.yMMMEd().format(now);
  print(formattedDate); // Example: Jun 10, 2024
  
  String formattedTime = DateFormat.Hms().format(now);
  print(formattedTime); // Example: 14:30:45
}

The DateFormat class offers various predefined formats (e.g., yMMMEd, jms) and the ability to define custom formats.

Handling Number Formatting

Formatting numbers correctly is crucial for displaying prices, quantities, and other numeric data. The NumberFormat class in the intl package is used for this purpose.

Step 1: Use NumberFormat

import 'package:intl/intl.dart';

void main() {
  double price = 1234.56;

  // Format as currency according to the user's locale
  String formattedPrice = NumberFormat.currency(locale: 'en_US', symbol: '$').format(price);
  print(formattedPrice); // Output: $1,234.56

  String formattedPriceES = NumberFormat.currency(locale: 'es_ES', symbol: '€').format(price);
  print(formattedPriceES);

  // Format as a decimal number
  String formattedNumber = NumberFormat.decimalPattern().format(1234567.89);
  print(formattedNumber); // Output: 1,234,567.89
}

Switching Languages at Runtime

Allowing users to change the app’s language at runtime enhances user experience. Here’s how to implement it:

Step 1: Create a Language Provider

Use a ChangeNotifier to manage the app’s locale.

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';

class LanguageProvider with ChangeNotifier {
  Locale _currentLocale = Locale('en');

  Locale get currentLocale => _currentLocale;

  Future setLocale(Locale newLocale) async {
    _currentLocale = newLocale;
    notifyListeners();

    // Save the locale to SharedPreferences
    final prefs = await SharedPreferences.getInstance();
    prefs.setString('languageCode', newLocale.languageCode);
  }

  // Load the locale from SharedPreferences
  Future loadLocale() async {
    final prefs = await SharedPreferences.getInstance();
    final languageCode = prefs.getString('languageCode');
    if (languageCode != null) {
      _currentLocale = Locale(languageCode);
      notifyListeners();
    }
  }
}

Step 2: Integrate with MaterialApp

Wrap your MaterialApp with a ChangeNotifierProvider and update the locale property dynamically.

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:provider/provider.dart';
import 'language_provider.dart'; // Import the LanguageProvider

void main() async {
  WidgetsFlutterBinding.ensureInitialized(); // Ensure Flutter is initialized
  final languageProvider = LanguageProvider();
  await languageProvider.loadLocale(); // Load saved locale

  runApp(
    ChangeNotifierProvider(
      create: (context) => languageProvider,
      child: MyApp(),
    ),
  );
}


class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final languageProvider = Provider.of(context);

    return MaterialApp(
      locale: languageProvider.currentLocale,
      localizationsDelegates: [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: [
        Locale('en'), // English
        Locale('es'), // Spanish
      ],
      home: MyHomePage(),
    );
  }
}

Step 3: Create a Language Switcher

Add a widget that allows users to change the language.

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'language_provider.dart'; // Import the LanguageProvider

class LanguageSwitcher extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final languageProvider = Provider.of(context);

    return DropdownButton(
      value: languageProvider.currentLocale,
      onChanged: (Locale? newLocale) {
        if (newLocale != null) {
          languageProvider.setLocale(newLocale);
        }
      },
      items: [
        DropdownMenuItem(
          value: Locale('en'),
          child: Text('English'),
        ),
        DropdownMenuItem(
          value: Locale('es'),
          child: Text('Spanish'),
        ),
      ],
    );
  }
}

Best Practices for Internationalization

• Externalize Strings: Keep all translatable strings in ARB files, separate from your code.
• Use Meaningful Keys: Use descriptive keys for your strings in ARB files (e.g., welcomeMessage instead of str1).
• Provide Context: Add descriptions to your ARB entries to provide context for translators.
• Test Thoroughly: Test your app with different locales to ensure that all translations are correct and that the UI adapts properly.

Conclusion

Internationalizing your Flutter application using the intl package is essential for reaching a global audience. By following these guidelines and best practices, you can create apps that provide a localized experience for users around the world. Effective use of the intl package ensures your app is both accessible and user-friendly, enhancing its overall quality and reach.