Flutter Over-the-Air translation updates

The gen_l10n tool represents a relatively new approach for localizing Flutter applications. This tool is part of the Flutter SDK and does not require any additional installations. We have already covered the steps for setting up and localizing apps using the gen_l10n tool. Therefore, in the following sections, we will expand on this topic and demonstrate how to enable Over-the-Air updates in such projects.

The sample Flutter app with Over-the-Air integration is available on the GitHub repository.

Step 1: Generate SDK Token

To begin, generate an SDK token on the Localizely platform by navigating to the Over-the-Air page for your project. This token will be required later for configuring the Localizely SDK in your Flutter project.

Step 2: Create Distribution

Create distribution on the same Over-the-Air page for your project. Although you can create multiple distributions, typically, only one distribution per project is needed. The generated Distribution ID will also be required later for configuring the Localizely SDK.

Step 3: Create Release

To update translations in your app, 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 the following:

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

Step 4: Add Localizely SDK to Your Project

To integrate localizely_sdk into your Flutter project, run the following command in your terminal:

flutter pub add localizely_sdk

This command will add a line like the following to your project's pubspec.yaml file:

dependencies:
    localizely_sdk: ^2.6.4

After adding the localizely_sdk to your project, you need to generate the necessary localization file. To do this, run the following command:

dart run localizely_sdk:generate

To automate the code generation process whenever your .arb files change, you should add the build_runner package to your dev_dependencies and run the watch command:

flutter pub add build_runner -d
flutter pub run build_runner watch

Once the required localization file is generated, update the localizationsDelegates and supportedLocales props of the MaterialApp widget in your Flutter application.

...
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)])));
  }
}

Please note that tracking sensitive information, such as credentials, tokens, and similar data, in Version Control Systems (VCS) like GitHub, GitLab, and others is generally considered unsafe. For real-world projects, it is recommended to extract sensitive information, such as SDK tokens and Distribution IDs, into environment variables. You can use the flutter_dotenv package or a similar one to manage this securely.

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.

The Flutter Intl is an IDE plugin that automates the generation of boilerplate code for the intl package. We have already covered the steps for setting up and localizing apps using the Flutter Intl plugin. Therefore, in the following sections, we will expand on this topic and demonstrate how to enable Over-the-Air updates in such projects.

The sample Flutter app with Over-the-Air integration is available on the GitHub repository.

Step 1: Generate SDK Token

To begin, generate an SDK token on the Localizely platform by navigating to the Over-the-Air page for your project. This token will be required later for configuring the Localizely SDK in your Flutter project.

Step 2: Create Distribution

Create distribution on the same Over-the-Air page for your project. Although you can create multiple distributions, typically, only one distribution per project is needed. The generated Distribution ID will also be required later for configuring the Localizely SDK.

Step 3: Create Release

To update translations in your app, 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 the following:

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

Step 4: Add Localizely SDK to Your Project

To integrate localizely_sdk into your Flutter project, run the following command in your terminal:

flutter pub add localizely_sdk

This command will add a line like the following to your project's pubspec.yaml file:

dependencies:
    localizely_sdk: ^2.6.4

After adding the localizely_sdk to your project, you need to update your flutter_intl section within the pubspec.yaml file and regenerate the necessary localization code.

To do this, update your pubspec.yaml file:

...

flutter_intl:
    enabled: true
    localizely:
        ota_enabled: true

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)])));
  }
}

Please note that tracking sensitive information, such as credentials, tokens, and similar data, in Version Control Systems (VCS) like GitHub, GitLab, and others is generally considered unsafe. For real-world projects, it is recommended to extract sensitive information, such as SDK tokens and Distribution IDs, into environment variables. You can use the flutter_dotenv package or a similar one to manage this securely.

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'));
});