Flutter Over the air translation updates

Over-the-air localization SDK for Flutter apps. No more unnecessary app updates.

Introduction

Localizely lets you update translations for your Flutter applications over the air. No need to release a new version to the App Store or Google Play. Localizely lets you push updates for text translations in your mobile apps instantly.

Most common use cases: correcting typos, optimizing texts, or updating translations on the fly.

Flutter app example with Over-the-air translation updates, available on GitHub: https://t.co/EFUIKP1WjN #flutterdev #flutter #translation
— Localizely (@localizely) October 7, 2020

Getting started

The most commonly used approach to localize Flutter apps is with the intl package and tools around it. Thus, in the following sections, we will explain how to integrate Over-the-Air translation updates into such Flutter projects.

The Flutter Intl is an IDE plugin that generates the necessary boilerplate code for the intl package. We have already explained how to configure localization with the Flutter Intl plugin. Therefore, in the following sections, we will take it further and show you how to enable Over-the-Air in such projects.

The sample Flutter app with Over-the-air integration can be found on the GitHub repo.

Step 1: Generate SDK token

Get started by creating an SDK token inside the Over the Air page for your project. You will need the token for configuring Flutter SDK later.

Step 2: Create Distribution

Create your first distribution inside the same Over the Air section for your project. You can have multiple distributions but typically you will have one distribution per project. You will need Distribution ID for configuring your Flutter SDK later.

Step 3: Create Release

To update translations inside your apps, simply create a new release within the distribution. This will export the current state of your project and make it available to the connected Flutter apps. For each release you can specify:

Description: Optional info about the release
Min version: Optional. Define the minimal semantic version of your app that should receive the update
Max version: Optional. Define the maximal semantic version of your app that should receive the update

By default, each release will be visible only for your app builds that initialized Localizely SDK with the prerelease flag set to true. Using such app builds only inside your team allows you to test translation changes before you publish them to your end-users.

Step 4: Include Localizely in your project

First, you need to include localizely_sdk library in your pubspec.yaml file and update flutter_intl.localizely config:

dependencies:
    localizely_sdk: ^2.5.0 # Or ^1.3.0 if you use Flutter <2.0
...

flutter_intl:
    enabled: true
    localizely:
        ota_enabled: true

Note: It is required to use Flutter Intl plugin for Android Studio / VS Code or intl_utils (1.5.0 or newer) in order to generate relevant localization dart code.

Step 5: Initialize SDK

For this step you will need your SDK token (generated in step 1) and the Distribution ID (created in step 2). In your main.dart file include the following code:

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:localizely_sdk/localizely_sdk.dart'; // Import sdk package
import 'generated/l10n.dart';

void main() {
  Localizely.init('<SDK_TOKEN>', '<DISTRIBUTION_ID>'); // Init sdk 
  Localizely.setPreRelease(true); // Add this only if you want to use prereleases
  Localizely.setAppVersion('<APP_VERSION>'); // Add this only if you want to explicitly set the application version, or in cases when automatic detection is not possible (e.g. Flutter web apps)
  
  runApp(MaterialApp(
      onGenerateTitle: (context) => S.of(context).appTitle,
      localizationsDelegates: [
        S.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: S.delegate.supportedLocales,
      home: HomePage()));
}

class HomePage extends StatefulWidget {
  @override
  State<StatefulWidget> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();

    // Call 'updateTranslations' after localization delegates initialization
    Localizely.updateTranslations().then(
        (response) => setState(() {
              _isLoading = false;
            }),
        onError: (error) => setState(() {
              _isLoading = false;
            }));
  }

  @override,
  Widget build(BuildContext context) {
    return Scaffold(
        appBar: AppBar(title: Text(S.of(context).pageHomeTitle)),
        body: Center(
            child: _isLoading ? CircularProgressIndicator() : Column(children: <Widget>[Text(S.of(context).welcome)])));
  }
}

Note: Ensure you have added INTERNET permission for Android devices.

Note: Localizely.updateTranslations() should be called just once on app start, as shown in the given example. Please do not call it frequently after the app starts.

Note: The localizely_sdk >=2.4.0 <2.5.0 requires an update of min platform versions:
- Android: Required Android SDK 21 or newer (update minSdkVersion to 21 in the android/app/build.gradle file).
- iOS: Required iOS 11 or newer.
As of version 2.5.0, these updates are no longer required due to changes in implementation.

Usage

String keys usage in code

There is no need to update your code, refer to the keys as usual:

S.of(context).title

Changing locale

There is no need to update your code, change locale as usual:

setState(() {
  S.load(Locale('en', 'US'));
});

Hint: In case you can't see updated translations in the app after successful OTA retrieval, please check if you have missed some of the steps.
Some tips that can help you: check if you have created a new release with the latest changes on Localizely, check if you are working with enabled or disabled prereleases, check if you are using the same languages on the Localizely and within the app, and check if you need to rebuild widgets tree after OTA update.

The gen_l10n tool is a new way of localization in Flutter. We have already explained how to configure localization with the gen_l10n tool. Therefore, in the following sections, we will take it further and show you how to enable Over-the-Air in such projects.

The sample Flutter app with Over-the-air integration can be found on the GitHub repo.

Step 1: Generate SDK token

Get started by creating an SDK token inside the Over the Air page for your project. You will need the token for configuring Flutter SDK later.

Step 2: Create Distribution

Step 3: Create Release

Description: Optional info about the release
Min version: Optional. Define the minimal semantic version of your app that should receive the update
Max version: Optional. Define the maximal semantic version of your app that should receive the update

Step 4: Include Localizely in your project

First, you need to include localizely_sdk library in your pubspec.yaml file:

dependencies:
    localizely_sdk: ^2.5.0

The next thing you need to do is to generate the necessary localization files with the localizely_sdk. To do that, run the command shown below.

dart run localizely_sdk:generate

Note: In Flutter 3.22.0, running the command dart run localizely_sdk:generate may produce false analyzer errors. This issue has been resolved in Flutter 3.22.1. If you need to use 3.22.0 and encounter these errors, running flutter pub get again should fix the problem.

To automatically run code generation each time your arb files change, you should add build_runner package to dev_dependencies and run watch command.

flutter pub add build_runner -d
flutter pub run build_runner watch

Once you've generated the required localization files, you need to update the localizationsDelegates and supportedLocales props of the MaterialApp widget.

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

class MyApp extends StatelessWidget {
  ...

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      ...
      localizationsDelegates: LocalizelyLocalizations.localizationsDelegates,
      supportedLocales: LocalizelyLocalizations.supportedLocales,
      ...
    );
  }
}

Step 5: Initialize SDK

For this step you will need your SDK token (generated in step 1) and the Distribution ID (created in step 2). In your main.dart file include the following code:

import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:flutter_gen/gen_l10n/localizely_localizations.dart';
import 'package:localizely_sdk/localizely_sdk.dart'; // Import sdk package

void main() {
  Localizely.init('<SDK_TOKEN>', '<DISTRIBUTION_ID>'); // Init sdk 
  Localizely.setPreRelease(true); // Add this only if you want to use prereleases
  Localizely.setAppVersion('<APP_VERSION>'); // Add this only if you want to explicitly set the application version, or in cases when automatic detection is not possible (e.g. Flutter web apps)
  
  runApp(MaterialApp(
      onGenerateTitle: (context) => AppLocalizations.of(context)!.appTitle,
      localizationsDelegates: LocalizelyLocalizations.localizationsDelegates,
      supportedLocales: LocalizelyLocalizations.supportedLocales,
      home: HomePage()));
}

class HomePage extends StatefulWidget {
  @override
  State<StatefulWidget> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();

    // Call 'updateTranslations' after localization delegates initialization
    Localizely.updateTranslations().then(
        (response) => setState(() {
              _isLoading = false;
            }),
        onError: (error) => setState(() {
              _isLoading = false;
            }));
  }

  @override,
  Widget build(BuildContext context) {
    return Scaffold(
        appBar: AppBar(title: Text(AppLocalizations.of(context)!.pageHomeTitle)),
        body: Center(
            child: _isLoading ? CircularProgressIndicator() : Column(children: <Widget>[Text(AppLocalizations.of(context)!.welcome)])));
  }
}

Note: Ensure you have added INTERNET permission for Android devices.

Note: Localizely.updateTranslations() should be called just once on app start, as shown in the given example. Please do not call it frequently after the app starts.

Note: The Over-the-Air support for Flutter apps that use gen_l10n tool for localization is added in the localizely_sdk 2.5.0.

Usage

String keys usage in code

There is no need to update your code, refer to the keys as usual:

AppLocalizations.of(context)!.title

Changing locale

There is no need to update your code, change locale as usual.

Frequently Asked Questions (FAQ)

What constitutes a Monthly Active User (MAU)?

When a user starts an application that uses Localizely SDK for the first time on a device, it generates a unique, random Device Identifier. This identifier’s sole purpose is the tracking of active users over a given period of time. It is not used for any other form or means of tracking and does not contain any user or device information.

What happens when I exceed Monthly Active User (MAU) quota?

We will not automatically lock your OTA functionality when you exceed your MAU quota. Instead, you will be informed and you will have enough time to upgrade your OTA Add-on according to your needs.

What happens when the app does not have internet access?

The app will fallback to previously fetched translations from Localizely, or to embedded translations during the build time, in that order. Once the app has internet access again, it can fetch the latest translations.

Previous: Translation editor

Tired of manually editing translation files?

Our platform streamlines software localization for you.

Try now for Free

Flutter Over the air translation updates

Documentation

Introduction

Getting started

Step 1: Generate SDK token

Step 2: Create Distribution

Step 3: Create Release

Step 4: Include Localizely in your project

Step 5: Initialize SDK

Usage

String keys usage in code

Changing locale

Step 1: Generate SDK token

Step 2: Create Distribution

Step 3: Create Release

Step 4: Include Localizely in your project

Step 5: Initialize SDK

Usage

String keys usage in code

Changing locale

Frequently Asked Questions (FAQ)

What constitutes a Monthly Active User (MAU)?

What happens when I exceed Monthly Active User (MAU) quota?

What happens when the app does not have internet access?

Documentation

About

Resources

Free tools

Boring stuff

Newsletter