Zoran Luledzija
Zoran Luledzija
March 29, 2022
17 min read
March 29, 2022
17 min read

Flutter localization: step-by-step

Having one codebase for Android and iOS app sounds attractive. In the past, we didn’t have a great experience doing that. But lately, Flutter is attacking that problem in its own way. However, if you build an app for different markets, you will most likely need to support multiple languages for your end-users. Currently, there are several ways to achieve that. Below, you will find some of the most commonly used approaches regarding Flutter localization.

Part 1: Setting up your Flutter app

To support multiple languages in your Flutter application, you need to set it up first. Through this section, you will find out how to do that with the Flutter Intl plugin. This plugin will automatically generate localization code for you, make easy addition of new languages, extraction of text for translation, and similar.

All code samples used in this guide are available on the GitHub repo.

Step 1: Install IDE plugin

Install Flutter Intl plugin for IDE you’re using (Visual Studio Code or Android Studio).
In this guide we will explain how to do it in Android Studio. It should be fairly similar in VS Code, just follow the steps in the extension documentation.

There is also a CLI tool intl_utils in case you need similar operations for Continuous Integration.

Step 2: Initialize plugin for your project

Go to Tools | Flutter Intl and run Initialize for the Project.

By default en locale is added by auto-creating a file lib/l10n/intl_en.arb.

Note: The plugin generates and maintains files inside lib/generated/ folder which you should not edit manually. But you should keep these files in your project repository.

Step 3: Set up your app

Add dependency needed for localization to pubspec.yaml file:

dependencies:
    # Other dependencies... 
    flutter_localizations: 
        sdk: flutter

Set up your localizationsDelegates and your supportedLocales which will allow accessing the strings, localize Material's and Cupertino's widgets into ~78 languages (e.g. Material's date picker), and set up text directions within the app.

import 'package:flutter_localizations/flutter_localizations.dart';
import 'generated/l10n.dart';

class MyApp extends StatelessWidget {
    @override
    Widget build(BuildContext context) {
        return new MaterialApp(
            localizationsDelegates: [
                S.delegate,
                GlobalMaterialLocalizations.delegate,
                GlobalWidgetsLocalizations.delegate,
                GlobalCupertinoLocalizations.delegate,
            ],
            supportedLocales: S.delegate.supportedLocales,
            title: 'Flutter Demo',
            home: new MyHomePage(title: 'Flutter Demo Home Page'),
        );
    }
}

Step 4: Add other locales

You probably want to localize your Flutter app into more than one locale.

You can add more locales by going to Tools | Flutter Intl and running Add locale command.

Step 5: Add string keys to main ARB file

Your main ARB file by default is lib/l10n/intl_en.arb. When you add new key-value pairs in it and save the file, those keys will be automatically available for auto-complete in your Dart code.

File content example:

{
  "title": "Hello world!"
}

In essence, ARB file is a JSON file with some conventions.

Step 6: Reference the keys in Dart code

The ARB file’s keys now correspond to methods from the S class. For example:

Widget build(BuildContext context) {
  return Text(
      S.of(context).title
  );
}

As an alternative way, you can just add a translation string in Dart code, and extract it to ARB files via intention action in Android Studio or via code actions in VS Code. That way you can add the same key to all ARB files.


Part 2: Managing your translations

As your app grows with the number of string keys and the number of different languages for end-users, it gets more complicated to maintain translations.
Here is how to streamline the localization workflow:

Step 1: Create a project in Localizely

Once you sign up to Localizely, just go to My projects page and tap “+” button (or explore the Sample Project if you wish to get more familiar with Localizely features first). Give your project a name and set your main and other languages. You can change the main language later if needed.

Flutter localization create project

Each project gets a unique ID (you can find it in My projects page), that is needed for the next step.

Step 2: Connect your IDE with Localizely

In your IDE go to Tools | Flutter Intl | Integrate with Localizely and run Connect command.

You will be asked for your personal API token which you can get from My Profile page, and project ID we mentioned in the previous step.

Flutter Intl connect with Localizely

Enter the data and click connect.

Once connected, your personal API token will be stored inside the file <USER_HOME>/.localizely/credentials, and project ID will be added to pubspec.yaml file inside your project.
Check out plugin documentation for additional but optional config parameters inside pubspec.yaml file.

Step 3: Upload main ARB file

During the development of the app, we constantly add new string keys that need to be translated later. A common practice is to add those new string keys only to the main locale during development.

Once planned features are implemented, you want to upload the main ARB file to Localizely, for your team to translate it.

In your IDE go to Tools | Flutter Intl | Integrate with Localizely and run Upload main ARB file command.

Note: Alternatively you can always add new string keys in Localizely platform first, and then download them for development. It depends on what fits into your workflow better.

Step 4: Translate

Localizely has an editor on Translations page that reminds of Excel tables commonly used for translations management. Feel free to explore the Sample project or just take a look at Getting started guide to grasp the basic concept and options.

Flutter localization translate

If you have previously invited your teammates to the Localizely project, you can assign them a task to translate newly added string keys.

Step 5: Download translated ARB files

The translation part is done.
In your IDE go to Tools | Flutter Intl | Integrate with Localizely and run Download ARB files command.
ARB files will be downloaded from Localizely platform and put in the proper place in your Flutter project.

Step 6: Publish your app

Your Flutter app now has ready translations for the next release.
You are ready to do QA check and publish the app!

In case you are interested in instant updates of translations without the need for new releases, check out the Flutter Over-the-Air translation updates feature. It will let you correct typos, optimize text, and update translations on the fly.

Like this article? Share it!


Zoran Luledzija
Zoran Luledzija

Zoran is a Software Engineer at Localizely. His primary interest is web development, but he also has a solid background in other technologies. For the last few years, he has been involved in the development of software localization tools.

Enjoying the read?

Subscribe to the Localizely blog newsletter for quality product content in your inbox.

Copyrights 2023 © Localizely