Flutter Over-the-Air translation updates

The gen_l10n tool is the standard way of localizing Flutter applications. It ships with the Flutter SDK, so there is nothing extra to install. This guide assumes your app is already localized with it. If not, start with our guide to setting up and localizing apps using the gen_l10n tool, then come back here to enable Over-the-Air updates.

A complete sample app with Over-the-Air integration is available on GitHub.

Step 1: Generate an SDK token

Open the Over-the-Air page of your project in Localizely and generate an SDK token. You will need it when you configure the SDK in your Flutter project.

Step 2: Create a distribution

On the same page, create a distribution. A project can have several distributions, but one is enough for most apps. Note the generated Distribution ID, which you will also need for the SDK configuration.

Step 3: Create a release

A release is a snapshot of your project's translations, made available to the apps connected to the distribution. Whenever you want to push updated translations, create a new release. Each release can carry the following settings:

New releases are visible only to app builds that initialized the SDK with the prerelease flag set to true. This lets your team verify translation changes internally before you publish the release to all users.

Step 4: Add the Localizely SDK to your project

Add localizely_sdk to your Flutter project by running the following command:

flutter pub add localizely_sdk

This adds a dependency like the following to your pubspec.yaml file:

dependencies:
    localizely_sdk: ^2.7.7

Recent Flutter versions no longer generate localization code as a synthetic package, so make sure your l10n.yaml file writes the generated code into your lib directory. The sample app uses the following configuration:

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

Next, generate the localization file the SDK needs by running:

dart run localizely_sdk:generate

To regenerate the code automatically whenever your .arb files change, add build_runner to your dev_dependencies and run it in watch mode:

flutter pub add build_runner -d
dart run build_runner watch

Once the localization file is generated, point the localizationsDelegates and supportedLocales properties of your MaterialApp widget at it.

...
import 'l10n/generated/localizely_localizations.dart';

class MyApp extends StatelessWidget {
  ...

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

Step 5: Initialize the SDK

You will need the SDK token from Step 1 and the Distribution ID from Step 2. In your main.dart file, initialize the SDK before running the app and call updateTranslations once the localization delegates are in place:

import 'package:flutter/material.dart';
import 'l10n/generated/app_localizations.dart';
import 'l10n/generated/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)])));
  }
}

Avoid committing secrets such as the SDK token and Distribution ID to version control. In real-world projects, keep them in environment variables and load them at runtime with a package like flutter_dotenv.

Usage

Using string keys in code

Nothing changes in the rest of your code. Refer to your string keys exactly as before:

AppLocalizations.of(context)!.title

Changing the locale

Switching locales works exactly as it did before you added the SDK.

The Flutter Intl is an IDE plugin that generates the boilerplate code for the intl package. This guide assumes your app is already localized with it. If not, start with our guide to setting up and localizing apps using the Flutter Intl plugin, then come back here to enable Over-the-Air updates.

A complete sample app with Over-the-Air integration is available on GitHub.

Step 1: Generate an SDK token

Open the Over-the-Air page of your project in Localizely and generate an SDK token. You will need it when you configure the SDK in your Flutter project.

Step 2: Create a distribution

On the same page, create a distribution. A project can have several distributions, but one is enough for most apps. Note the generated Distribution ID, which you will also need for the SDK configuration.

Step 3: Create a release

A release is a snapshot of your project's translations, made available to the apps connected to the distribution. Whenever you want to push updated translations, create a new release. Each release can carry the following settings:

New releases are visible only to app builds that initialized the SDK with the prerelease flag set to true. This lets your team verify translation changes internally before you publish the release to all users.

Step 4: Add the Localizely SDK to your project

Add localizely_sdk to your Flutter project by running the following command:

flutter pub add localizely_sdk

This adds a dependency like the following to your pubspec.yaml file:

dependencies:
    localizely_sdk: ^2.7.7

Next, enable Over-the-Air support in the flutter_intl section of your pubspec.yaml file and regenerate the localization code:

...

flutter_intl:
    enabled: true
    localizely:
        ota_enabled: true

Step 5: Initialize the SDK

You will need the SDK token from Step 1 and the Distribution ID from Step 2. In your main.dart file, initialize the SDK before running the app and call updateTranslations once the localization delegates are in place:

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

Avoid committing secrets such as the SDK token and Distribution ID to version control. In real-world projects, keep them in environment variables and load them at runtime with a package like flutter_dotenv.

Usage

Using string keys in code

Nothing changes in the rest of your code. Refer to your string keys exactly as before:

S.of(context).title

Changing the locale

Switching locales works exactly as it did before you added the SDK:

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