A Guide to Flutter Localization

Flutter has come a long way since we last published How to Internationalize a Flutter App Using intl and intl_translation in late 2018. Since then, the cross-platform framework has taken the mobile app development world by storm. With 150,000 apps and half a million developers in its portfolio, it seems that Flutter—and its delightful development experience—have become a go-to for many developing iOS and Android apps (not to mention web apps). And with the recent Flutter 2 release, the promise of one codebase that works on multiple platforms goes even further: at the time of writing, Flutter 2 supports desktop (Linux, macOS, and Windows) at a near-stable level.

A bit of an unsung hero, the Flutter internationalization (i18n) team has made strides to streamline the first-party localization (l10n) experience over the last couple of years. When we wrote our first Flutter i18n guide, there was an annoying amount of boilerplate, and constant running of CLI tools to set up and add localization to a Flutter app. Well, no more! Automatic code generation has done away with most of these headaches.

In this article, we’ll show you how to use Flutter’s native localization package to localize your mobile apps for Android and iOS. We won’t cover web or desktop here, although it seems they should work in largely the same way.

📖 Go deeper » Flutter’s native localization package is is built on the first-party Dart intl package.

🗒 Note » If you want us to write about Flutter Web and/or Desktop i18n, let us know in the comments below.

Demo App

To keep things grounded and fun, we’ll build a small demo app and localize it: Heroes of Computer Science presents a selection of notable figures in the relatively short history of computing.

In English; soon in other languages

Versions Used

We’re using the following language, framework, and package versions in this article:

• Dart 2.12.3
• Flutter 2.0.5
• flutter_localizations (version seems tied to Flutter) — provides localizations to common widgets, like Material or Cupertino widgets.
• intl 0.17.0 — the backbone of the localization system; allows us to create and use our own localizations; used for formatting dates and numbers.

Now let’s look at the code for our starter app, which is pretty straightforward.

import 'package:flutter/material.dart';
import 'screens/hero_list.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Heroes of Computer Science',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: HeroList(title: 'Heroes of Computer Science'),
    );
  }
}

Our root widget is a bread-and-butter MaterialApp, with a HeroList at its home route.

import 'package:flutter/material.dart';
import 'package:flutter_i18n_2021/screens/settings.dart';
import 'package:flutter_i18n_2021/widgets/hero_card.dart';

class HeroList extends StatelessWidget {
  final String title;

  HeroList({this.title = ''});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(title),
        actions: <Widget>[
          IconButton(
            icon: Icon(Icons.settings),
            tooltip: 'Open settings',
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(builder: (context) => Settings()),
              );
            },
          )
        ],
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            Padding(
              padding: const EdgeInsets.only(bottom: 8.0),
              child: Text('6 Hereos'),
            ),
            Expanded(
              child: ListView(
                children: <Widget>[
                  HeroCard(
                    name: 'Grace Hopper',
                    born: '9 December 1906',
                    bio: 'Devised theory of machine-independent '
                         'programming languages.',
                    imagePath: 'assets/images/grace_hopper.jpg',
                  ),
                  HeroCard(
                    name: 'Alan Turing',
                    born: '23 June 1912',
                    bio: 'Father of theoretical computer science & '
                        'artificial intelligence.',
                    imagePath: 'assets/images/alan_turing.jpg',
                  ),
              
             	  // ...
                  
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}

HeroList mainly houses a ListView of parameterized HeroCards.

🗒 Note » You may have noticed that our HeroList‘s Scaffold.appBar has an icon that links to a Settings screen. We wanted to add this screen with a manual language-switcher, but we decided to drop that since this article was getting kind of long. Manual language switching is not super common in mobile apps, but if you want us to cover a Flutter language switcher please let us know in the comments below!

import 'package:flutter/material.dart';

class HeroCard extends StatelessWidget {
  final String name;
  final String born;
  final String bio;
  final String imagePath;

  final String placeholderImagePath = 'assets/images/placeholder.jpg';

  const HeroCard({
    Key key,
    this.name = '',
    this.born = '',
    this.bio = '',
    this.imagePath,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    var theme = Theme.of(context);

    return Card(
      child: Padding(
        padding: const EdgeInsets.all(4.0),
        child: Row(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: <Widget>[
            Padding(
              padding: const EdgeInsets.only(right: 8.0),
              child: ClipRRect(
                borderRadius: BorderRadius.circular(2),
                child: Image.asset(
                  imagePath ?? placeholderImagePath,
                  width: 100,
                  height: 100,
                ),
              ),
            ),
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: <Widget>[
                  Padding(
                    padding: const EdgeInsets.only(top: 4),
                    child: Text(
                      name,
                      style: theme.textTheme.headline6,
                    ),
                  ),
                  Padding(
                    padding: const EdgeInsets.only(top: 2, bottom: 4),
                    child: Text(
                      born.isEmpty ? '' : 'Born $born',
                      style: TextStyle(
                               fontSize: 12,
                               fontWeight: FontWeight.w300),
                    ),
                  ),
                  Text(
                    bio,
                    style: TextStyle(fontSize: 14),
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}

HeroCard displays the given image and string params in a nice Material Card widget and pretties everything up. Alright, let’s get to localizing this puppy!

🔗 Resource » You can get the code of the app up to this point from the start branch of our GitHub repo. The main branch has the fully localized app.

Installation & Setup

We can install our packages by adding a few lines to pubspec.yaml.

version: 1.0.0+1
 
 environment:
   sdk: ">=2.7.0 <3.0.0"
 
 dependencies:
   flutter:
     sdk: flutter
   flutter_localizations:
      sdk: flutter
   intl: ^0.17.0
 
 # ... 
 
 # The following section is specific to Flutter.
 flutter:
   generate: true
   uses-material-design: true

  # ...

After adding the highlighted lines above we can run flutter pub get from the command line to pull in our packages. The generate: true line is necessary for the automatic code generation the localization packages provide for us. We’ll go more into code generation business shortly. For now, do include the line; it really saves time.

Localization Configuration

With our packages installed, let’s add a l10n.yaml file to the root of our project. This file configures where our translation files will sit and the names of auto-generated dart files.

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

🔗 Resource » The official Internationalization User Guide covers many more options that can go in l10n.yaml to control the Flutter i18n code generator.

Adding Translation Files

Flutter localization uses ARB (Application Resource Bundle) files to house its translations by default. These are simple files written in JSON syntax. At the very least, we need a template file that corresponds to our default locale (English in our case). We specified that our template file will be lib/l10n/app_en.arb in our above configuration. So let’s create this housing directory and add our template translations file to it.

{
  "appTitle": "Heroes of Computer Science"
}

Of course, all these shenanigans wouldn’t make much sense if we couldn’t provide translations for other locales. We’ll add an Arabic translations file here. Feel free to add any language you like. We’ll touch on right-to-left (RTL) layouts a bit later, so if you’re interested in that you might want to stick to Arabic or another RTL language.

{
  "appTitle": "أبطال علوم الكمبيوتر"
}

We can add as many locale translations as we want. We just need to make sure that our files conform to our configured naming convention: lib/l10n/app_<locale>.arb

Configuring Our App

Let’s start telling our app about our anxious interest in i18n. We need to configure our main.dart file to use the Flutter localization packages.

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'screens/hero_list.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Heroes of Computer Science',
      localizationsDelegates: [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: [
        // 'en' is the language code. We could optionally provide a 
        // a country code as the second param, e.g. 
        // Locale('en', 'US'). If we do that, we may want to
        // provide an additional app_en_US.arb file for
        // region-specific translations.
        const Locale('en', ''),
        const Locale('ar', ''),
      ],
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: HeroList(title: 'Heroes of Computer Science'),
    );
  }
}

After importing flutter_localizations.dart, we add the localizationsDelegates and supportedLocales props to the MaterialApp constructor. localizationsDelegates provide localizations to our app. The ones included above provide localizations for Flutter widgets, Material, and Cupertino, which have already been localized by the Flutter team.

For example, suppose we had a MaterialApp and called the showDatePicker() function somewhere within it. Supposing also that our operating system language is set to Arabic, we would see something like the following.

Note that we didn’t have to translate anything ourselves to get this. The date picker widget has already been localized by the Flutter team. We just need to wire up the correct delegates in our app constructor, as we did above. Big hats off to the Flutter team for this: what a time-saver!

🗒 Note » At the time of writing, flutter_localizations supports 78 languages.

🔗 Resource » The official Flutter documentation does a good job of explaining how the different parts, like delegates and the Localizations class, work together for their i18n/l10n.

The supportedLocales prop we provided to the MaterialApp constructor lists the languages our app supports. Flutter will only rebuild widgets in response to a locale change if the locale is in the supportedLocales list. We’ll get back to supportedLocales in a moment when we discuss locale resolution. Right now, let’s generate some code!

Automatic Code Generation

In order to use the translations in the ARB files in our Flutter app, we need to generate some Dart files that we import whenever we need the translations. To generate these files, just make sure you’ve followed the installation and setup steps up to this point and run the app. That’s right, just run the app. The code will automatically get generated, and if all went well, you should see the following files in your project directory:

• .dart_tool/flutter_gen/gen_l10n/app_localizations.dart
• .dart_tool/flutter_gen/gen_l10n/app_localizations_en.dart
• .dart_tool/flutter_gen/gen_l10n/app_localizations_ar.dart

🗒 Note » If these files weren’t generated, make sure your Flutter app has no compilation errors and check your debug console when you run the app.

Using Our AppLocalizations

Let’s make use of the newly generated code files to localize our app title.

import 'package:flutter/material.dart';
import 'package:flutter_i18n_2021/screens/settings.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'screens/hero_list.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      onGenerateTitle: (context) { 
        return AppLocalizations.of(context).appTitle;
      },
      localizationsDelegates: [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: [
        const Locale('en', ''),
        const Locale('ar', ''),
      ],
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),

      // remove home: HeroList(...)
      initialRoute: '/',
      routes: {
        '/': (context) {
          return HeroList(title: AppLocalizations.of(context).appTitle);
        },
        '/settings': (context) => Settings(),
      },
    );
  }
}

We import app_localizations.dart and add the auto-generated AppLocalizations.delegate to our delegate list. This provides us with the AppLocalizations widget, which we use to translate the app title and the HeroList title. The auto-generated appTitle property will contain the translation that matches the active locale, pulled from our app_<locale>.arb file.

✋🏽 Heads up » Due to loading order, our translations won’t be ready when we’re constructing our MaterialApp. So we use the onGenerateTitle and routes props, and their builder (context) {} functions to make sure that our translations are ready when we set our title strings.

Now, if we set our operating system language to Arabic and run our app, lo and behold!

Our title is now in Arabic. Moreover, notice how Flutter has laid out many of its widgets in a right-to-left direction automatically for us. Since Arabic is a right-to-left language, this saves us a ton of time! We’ll have to fix that padding to the left of the image in the HeroCards, and we’ll do that when we tackle directionality a bit later.

📖 Go deeper » The eagle-eyed reader may have noticed that AppLocalizations.of(context) looks a lot like calling an InheritedWidget. That’s because localization objects work a lot like InheritedWidgets. We cover this in more detail in our article, How to Internationalize a Flutter App Using intl and intl_translation.

That’s it for setup. We have the foundation for localizing our app now. One question that you might have at this point is, “how does Flutter decide what locale to use?” Let’s talk about that.

Locale Resolution

The locales we provided to MaterialApp(supportedLocales: [...]) are the only ones Flutter will use to determine the active locale when the app runs. To do this, Flutter uses three properties of a locale:

• The language code, e.g. 'en'for English
• The country code (optional), e.g. the US part in en_US
• The script code (optional) —the letter set used, e.g. traditional (Hant) or simplified Chinese (Hans)

By default, Flutter will read the user’s preferred system locales and:

1. Try to match the languageCode, scriptCode, and countryCode with one in supportedLocales. If that fails,
2. Try to match the languageCode and scriptCode with one in supportedLocales. If that fails,
3. Try to match the languageCode and countryCode with one in supportedLocales. If that fails,
4. Try to match the languageCode with one in supportedLocales. If that fails,
5. Try to match the countryCode with one in supportedLocales only when all preferred locales fail to match. If that fails,
6. Return the first element of supportedLocales as a fallback.

So in our app, if the user’s iOS language is set to ar_SA, they would see our ar localizations (4. above) . If the user’s iOS language is set to fr (French), they would see our en localizations (6. above). On Android, a user can have a list of preferred locales, not just one. This is covered by Flutter in the above resolution algorithm.

🔗 Resource » The above algorithm is a paraphrasing of the official documentation of the supportedLocales property.

✋🏽 Heads up » If your app supports a locale with a country code, like fr_CA (Canadian French), you should provide a fallback without the country code, like fr.

Updating the iOS Project

The official Flutter documentation mentions the need to update the Info.plist directly in the iOS app bundle, adding our supported locales to it. If Info.plist isn’t updated our iOS app might not work as expected. To make the update we just need to open ios/Runner/Info.plist in any text editor and make sure the following entries are in there.

<key>CFBundleLocalizations</key>
<array>
	<string>en</string>
	<string>ar</string>
</array>

Getting the Active Locale

We sometimes need to know what the runtime locale is in our code. We can do this with the following snippet.

Locale activeLocale = Localizations.localeOf(context);

// If our active locale is fr_CA
debugPrint(activeLocale.languageCode); // => fr
debugPrint(activeLocale.countryCode);  // => CA

✋🏽 Heads up » Notice that we’re using Localizations , a widget built into Flutter, and not the auto-generated AppLocalizations.

Basic Translation Messages

We already covered basic translation messages when we added our appTitle message. However, let’s quickly go over the workflow for adding messages. We’ll translate the tooltip of our HeroList‘s app bar icon button next. Might as well make some use of it since we’re not really building a settings screen 😅.

// ...

class HeroList extends StatelessWidget {
  final String title;

  HeroList({this.title = ''});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(title),
        actions: <Widget>[
          IconButton(
            icon: Icon(Icons.settings),
            tooltip: 'Open settings',
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(builder: (context) => Settings()),
              );
            },
          )
        ],
      ),
      body: ...
  );
}

Let’s get that tooltip localized, shall we? First, we’ll add the relevant entries to our ARB files.

{
  "appTitle": "Heroes of Computer Science",
  "openSettings": "Open Settings"
}

{
  "appTitle": "أبطال علوم الكمبيوتر",
  "openSettings": "إفتح الإعدادات"
}

Next, let’s reload our app to regenerate our code files. This step is really important and forgetting it can lead to undue frustration. Note that this is a full app restart (), not a hot reload.

Now we can update our code to use our new localized message.

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

class HeroList extends StatelessWidget {
  final String title;

  HeroList({this.title = ''});

  @override
  Widget build(BuildContext context) {
    var t = AppLocalizations.of(context);

    return Scaffold(
      appBar: AppBar(
        title: Text(title),
        actions: <Widget>[
          IconButton(
            icon: Icon(Icons.settings),
            tooltip: t.openSettings,
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(builder: (context) => Settings()),
              );
            },
          )
        ],
      ),
      body: ...
  );
}

With this code in place, when we reload our app we should see the localized value of our tooltip in the Widget Inspector.

✋🏽 Heads up » You may often get error highlighting in your IDE after you add new translation messages. If you’ve reloaded your app, the error may be incorrect (you might be just fine). If you get a message saying that there are build errors, you can try to run the app anyway. As long as the app builds and runs, and you see your new translations, then all is probably well. To make the error go away in the IDE, trying shutting your app down entirely and starting it up again.

Interpolation in Messages

We’re on our way to translating our app. But what about interpolating dynamic runtime values in our translation messages? For example, Steve Wozniak’s bio contains the product names Apple I and Apple II.

// ...

class HeroList extends StatelessWidget {

  // ...

  @override
  Widget build(BuildContext context) {
    return Scaffold(

      // ...

                  HeroCard(
                    name: 'Steve Wozniak',
                    born: '11 August 1950',
                    bio: 'Designed & developed the Apple I & '
                         'Apple II microcomputers.',
                    imagePath: 'assets/images/steve_wozniak.jpg',
                  ),

                  // ...
         

When we localize this message, we might want to keep Apple I and Apple II in their original English regardless of the active locale. We can use placeholders in our translation files to accomplish this.

{

  // ...

  "wozniakBio": "Developed the {appleOne} & {appleTwo} microcomputers.",
  "@wozniakBio": {
    "placeholders": {
      "appleOne": {},
      "appleTwo": {}
    }
  },
  
  // ...
}

{

  // ...

  "wozniakBio": "طور جهازي كمبيوتر {appleOne} و {appleTwo}",

  // ...
}

We use the {placeholderName} syntax to set the placeholders for our dynamic values, and we can have as many placeholders as we want in a message.

You’ve probably also noticed the @wozniakBio key in our English translations above. This entry is a companion to the wozniakBio message in the same file. Companion entries are optional for basic messages but required for messages with placeholders. In fact, we use companion entries to define message placeholders (among other things).

🗒 Note » The companion entry for a message with key foo must have a key of @foo. We only need companion entries in our default/template translation file (English in our case).

"@wozniakBio": {
    "placeholders": {
      "appleOne": {},
      "appleTwo": {}
    }
  }

✋🏽 Heads up » Placeholder names must be valid Dart method parameter names.

We could use the placeholders object to specify the type of each value, and even provide examples as documentation if we want. We can also leave the definition as an empty {}.

"@wozniakBio": {
    "placeholders": {
      "appleOne": {
        // Explicit type
        "type": "String",
        // A little doc
        "example": "Apple I"
      },
      // It's perfectly ok to just specifiy the name
      "appleTwo": {}
    }
  }

The type is used in the method Flutter will generate on AppLocalizations for our wozniakBio message.

// ...

abstract class AppLocalizations {
  // ...

  // This method is implemented in app_localizations_en.dart
  // and app_localizations_ar.dart.
  //
  // Explicit type for appleOne parameter. Implicit appleTwo 
  // parameter.
  String wozniakBio(String appleOne, Object appleTwo);

  // ...
}

🗒 Note » It’s perfectly OK for most cases to use empty {} for placeholder definitions. An empty definition will cause the parameter to be of type Object. Under the hood Flutter will just use the theParameter.toString() value of the given parameter, so an Object param will work just fine. An implicit Object placeholder also keeps our messages flexible to take any type, since all Dart types derive from Object and have a toString().

OK, after rerunning the app to update AppLocalizations, we can localize the Woz’s bio message with the new method.

// ...

class HeroList extends StatelessWidget {

  // ...

  @override
  Widget build(BuildContext context) {

   var t = AppLocalizations.of(context);

    return Scaffold(

      // ...
                  HeroCard(
                    name: 'Steve Wozniak',
                    born: '11 August 1950',
                    bio: t.wozniakBio('Apple I', 'Apple II'),
                    imagePath: 'assets/images/steve_wozniak.jpg',
                  ),

                  // ...

With that in place, we know we can never be sued by any fruit-flavored companies for misrepresenting their products in any language.

Interpolated values in Arabic and English

Plurals

We often need to handle dynamic plurals in our localization. “You have received one message” or “You have received 3 messages”, for example.

It’s important to note that different languages handle plurals differently. For example, English has two plural forms: one and other (other == zero and >1). Arabic has six plural forms. This can be a bit of a headache when localizing using libraries that don’t support complex plural rules. Luckily, Flutter’s first-party i18n solution handles complex plurals out of the box, so it has us covered. Let’s use it to localize the hero counter in our app.

// ...

class HeroList extends StatelessWidget {
  
  // ...

  @override
  Widget build(BuildContext context) {
    return Scaffold(

      //...

      body: Padding(
        // ...
        child: Column(
          children: [
            Padding(
              padding: const EdgeInsets.only(bottom: 8.0),

              // Let's localize this dude
              child: Text('6 Hereos'),
            ),
          
       // ...

First, let’s add the message to our template English ARB file.

{
  // ...

  "heroCount": "{count,plural, =0{No heroes yet} =1{1 hero} other{{count} heroes}}",
  "@heroCount": {
    "placeholders": {
      "count": {}
    }
  },

  // ...
}

We specify a count placeholder in our message, and use it with the special {count,plural,...} syntax to define the different plural forms.

✋🏽 Heads up » The count param will always be an int type. If you specify another type for count, Flutter will ignore it and use int anyway.

🗒 Note » You can add placeholders other than count to a plural message; they’re specified as usual (see Interpolation above).

Flutter supports the following plural forms.

• zero ➞ =0{No heroes}
• one ➞ =1{One hero}
• two ➞ =2(Two heroes}
• few ➞ few{The {count} heroes}
• many ➞ many{{count} heroes}
• other ➞ other{{count} heroes}

few, many, and other have different meanings depending on the active language. The only required form in any language is the other form.

🗒 Note » We didn’t need to use the zero =0 form in our English message above. If we had omitted it, Flutter would have used our other form instead.

Alright, let’s add our Arabic message. As we mentioned earlier, Arabic has six plural forms.

{
  // ...

  "heroCount": "{count,plural, =0{لا توجد أبطال بعد} =1{بطل {count}} =2{بطلان} few{{count} أبطال} many{{count} بطل} other{{count} بطل}",
 
  // ...
}

Now let’s wire it all up and use our new message in our HeroList widget.

// ...

class HeroList extends StatelessWidget {
  
  // ...

  @override
  Widget build(BuildContext context) {

    var t = AppLocalizations.of(context);
    
    return Scaffold(

      //...

      body: Padding(
        // ...
        child: Column(
          children: [
            Padding(
              padding: const EdgeInsets.only(bottom: 8.0),

              child: Text(t.heroCount(6)),
            ),
          
       // ...

Of course, in a production app the count parameter passed to t.heroCount() would be dynamic. Flutter chooses the correct plural form from our message depending on the active locale.

English plural forms in our app

Arabic plural forms in our app

Number Formatting

We can format numbers in our localized messages using our friend the placeholders object in the companion entries of our template ARB file (English in our case). There’s no great place to put number formatting in our little demo app, so we’ll just pretend we have an e-commerce app to demonstrate.

// app_en.arb in example app that has a shopping cart
{
  "itemTotal": "Your total is: {value}",
  "@itemTotal": {
    "placeholders": {
      "value": {
        "type": "double",
        "format": "currency"
      }
    }
  }
}

Notice that we specified an explicit type and format to control how the number will be displayed. As per usual, we can translate our message in our other locale files.

// app_ar.arb in example app that has a shopping cart
{
  "itemTotal": "إجمالي: {value}"
}

After we reload our app, we can use our message as usual.

// In a Widget 
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

// In some widget builder with a context
var t = AppLocalizations.of(context);

var message = t.itemTotal(56.12);
// => "Your total is USD56.12" when current locale is English
// => "إجمالي: EGP56.12" when current locale is Arabic

✋🏽 Heads up » You can’t override number formats per locale. The format you specify in your template locale (English in our case) will be used across locales regardless of any format override you specify in your other locale files.

Remember that underneath the hood Flutter is using the Dart intl library for most of its i18n work. The currency format we used above is one of several formats built into the intl number formatter. Other formats include decimals, percentages, and more.

🔗 Resource » Check out the official user guide for all the available formats.

However, we don’t have to rely on Flutter to pass our numbers to intl. We can use intl directly to gain more control over our number formatting.

import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:intl/intl.dart';

// In some Widget builder with a context
var currentLocale = AppLocalizations.of(context).localeName;

var compact = 
  NumberFormat.compact(locale: currentLocale).format(6000000));
// => "6M" when current locale is US English
// => "٦ مليون" when curent locale is Egptian Arabic 

var simpleCurrency = 
  NumberFormat.simpleCurrency(locale: currentLocale).format(14.24);
// => "$14.24" when current locale is US English
// => "£E ١٤،٢٤" when current locale is Egyptian Arabic

🔗 Resource » You don’t need to use the predefined formats like compact and simpleCurrency. The intl NumberFormat constructor gives you granular control over your number formats. Read all about it on the official documentation.

✋🏽 Heads up » The only way I could get Eastern Arabic numerals (١،٢،٣…) rendering for Arabic is by setting the locale param to "ar_EG" (Egyptian Arabic). Neither "ar" or any "ar_XX" variant other than Egyptian worked for me.

✋🏽 Heads up » Formats didn’t work with the plural count variable for me. It seems that Flutter is overriding the format when it processes plurals. If you are able get formats in your plurals, please let us know how you did it in the comments below.

Date Formatting

Our heroes currently have hard-coded birth dates that aren’t localized, which isn’t too cool.

We want this date localized to Arabic

Recall that we’re rendering each of our heroes with a HeroCard widget.

import 'package:flutter/material.dart';

class HeroCard extends StatelessWidget {
  final String name;
  final String born;
  final String bio;
  final String imagePath;

  // ...

  const HeroCard({
    Key key,
    this.name = '',
    this.born = '',
    this.bio = '',
    this.imagePath,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // ...
    return Card(
      child: Padding(
        // ...
                  Padding(
                    padding: const EdgeInsets.only(top: 2, bottom: 4),
                    child: Text(
                      born.isEmpty ? '' : 'Born $born',
                      // ...

To format the born date for each locale our app supports, we first add some new localized messages with interpolated date values.

{
  // ...

  "heroBorn": "Born {date}",
  "@heroBorn": {
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMMMd"
      }
    }
  },

  // ...
}

{
  // ...

  "heroBorn": "تاريخ الميلاد {date}",

  // ...
}

When we define our date placeholder in our template localization file, we need to give it the DateTime type. We can then use a format to specify how we want to display the date. The format yMMMd we defined above stands for “year, abbreviated month, day”, which in US English would render to something like “Dec 9, 1906”.

🔗 Resource » In fact, underneath the hood Flutter is just using intl’s DateFormat class, generating code like DateFormat.yMMMd(localeName).format(date). The yMMMd named constructor is a handy shortcut called a “skeleton”, and there are quite a few we can use. Check them out in the official DateFormat documentation.

🗒 Note » We didn’t have to call our placeholder variable date. We could have given it any name, as long as it was a valid Dart function parameter name.

Alright, let’s wire this up in our widget to get our new messages displayed.

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

class HeroCard extends StatelessWidget {
  final String name;
  final String born;
  final String bio;
  final String imagePath;

  // ...

  final DateTime bornDateTime;

  HeroCard({
    Key key,
    this.name = '',
    this.born = '',
    this.bio = '',
    this.imagePath,
  }) : bornDateTime = new DateFormat('d MMMM yyyy').parse(born),
        super(key: key);

  @override
  Widget build(BuildContext context) {
    // ...
    var t = AppLocalizations.of(context);

    return Card(
      child: Padding(
        // ...
                  Padding(
                    padding: const EdgeInsets.only(top: 2, bottom: 4),
                    child: Text(
                      born.isEmpty ? '' : t.heroBorn(bornDateTime),
                      // ...

We’re handed a hero’s birthdates as a String, so we need to parse it to a DateTime first. We use intl’s DateFormat class to do this in our widget constructor.

In the build method, we simply pass the parsed DateTime to our t.heroBorn() localized message. This gives us nicely localized dates.

What if we don’t want to use any of the predefined skeletons, and to fully customize our date formats? Well, much like number formatting (see above), we would need to use the intl.DateFormat class directly. Suppose we wanted to display our hero birthdates in a format like “1912-06-23”. We would do something like the following.

import 'package:intl/intl.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

// In widget builder with context
var t = AppLocalizations.of(context);

var bornDateTime = new DateTime(1912, 6, 23);
var formattedBorn =
    new DateFormat('yyyy-MM-dd', t.localeName).format(bornDateTime);

var message = t.heroBorn(formattedBorn);
// => "1912-06-23" in US English
// => "١٩١٢-٠٦-٢٣" in Egyptian Arabic

Our localized heroBorn messages in our ARB files would then just take regular Object or String params, since we’ve already done the formatting for them.

Directionality: Left-to-Right and Right-to-Left

While English is a left-to-right (LTR) language, Arabic goes the other way and is laid out right-to-left (RTL). This is currently causing a problem for us when our app is used on a device with Arabic as the system language.

Notice the lack of padding between images and text

The image and the text in each card are flush because we’re using EdgeInsets.only(right) to define the padding around our image.

//...

class HeroCard extends StatelessWidget {

  // ...

  @override
  Widget build(BuildContext context) {
    // ...

    return Card(
      child: Padding(
        padding: const EdgeInsets.all(4.0),
        child: Row(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: <Widget>[
            Padding(
              padding: const EdgeInsets.only(right: 8.0),
              child: ClipRRect(
                  // Portrait image ...
                ),
              ),
            ),
            Expanded(
              // Text widgets...

This works in LTR languages, where we want a right margin between the image and the text. In RTL languages, however, we want the margin on the left.

An easy remedy here is to use EdgeInsetsDirectional instead of EdgeInsets.

//...

class HeroCard extends StatelessWidget {

  // ...

  @override
  Widget build(BuildContext context) {
    // ...

    return Card(
      child: Padding(
        padding: const EdgeInsets.all(4.0),
        child: Row(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: <Widget>[
            Padding(
              padding: const EdgeInsetsDirectional.only(end: 8.0),
              child: ClipRRect(
                  // Portrait image...
                ),
              ),
            ),
            Expanded(
              // Text widgets...

Notice that we use end instead of right to set the padding between the image and the text. EdgeInsetsDirectional is one of a few layout Flutter widgets that are locale-direction-aware. These widgets take start and end parameters instead of left and right. And the cool thing is that these directional widgets will do the correct thing automatically for the active locale:

• start == left for LTR languages
• start == right for RTL languages
• end == right for LTR languages
• end == left for RTL languages

With this small tweak to the code, our layout issue is resolved.

The layout now adapts to the active locale’s direction

🔗 Resource » At the time of writing, the official Flutter documentation lists the following directional widgets:

• EdgeInsetsDirectional
• AlignmentDirectional
• BorderDirectional
• BorderRadiusDirectional
• PositionedDirectional
• AnimatedPositionedDirectional

And with all that in place, our final app looks all globalized-like.

🔗 Resource » Get the complete for our demo app from our GitHub repo.

Up, Up and Away

We hope you enjoyed our guide to Flutter localization, and that you learned a thing or two. And if you’re looking to take your i18n game to the next level, check out Phrase. A professional localization platform with built-in ARB support for your Flutter apps, Phrase features a flexible API and CLI, and a beautiful web platform for your translators. With GitHub, GitLab, and Bitbucket sync, and over-the-air translations for mobile, Phrase does the heavy lifting in your localization pipeline to keep you focused on the code you love. Check out all of Phrase’s features and try it for 14 days for free.