Localizely SDK

This package provides Over-the-Air translation updates and In-Context Editing from the Localizely platform.

Platform Support

Android	iOS	Web	MacOS	Linux	Windows
✔	✔	✔	✔	✔	✔

Over-the-Air translation updates

Update translations for your Flutter applications over the air. Learn more

Works with projects that use Flutter's gen_l10n approach for internationalization, and with projects that use Flutter Intl IDE plugin / intl_utils.

Setup for gen_l10n

1. Update pubspec.yaml file

dependencies:
  ...
  localizely_sdk: ^2.5.7

2. Generate localization files

dart run localizely_sdk:generate

3. Update 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,
      ...
    );
  }
}

4. Initialize Localizely SDK

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.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';

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();

    Localizely.updateTranslations().then( // Call 'updateTranslations' after localization delegates initialization
        (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)])));
  }
}

Setup for Flutter Intl

1. Update pubspec.yaml file

dependencies:
  ...
  localizely_sdk: ^2.5.7

flutter_intl:
  ...
  localizely:
    ota_enabled: true # Required for Over-the-Air translation updates

2. Trigger localization files generation by Flutter Intl IDE plugin or by intl_utils library

3. Initialize Localizely SDK

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:localizely_sdk/localizely_sdk.dart';
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();

    Localizely.updateTranslations().then( // Call 'updateTranslations' after localization delegates initialization
        (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)])));
  }
}

In-Context Editing

Instantly see how your translations fit on a real device without unnecessary app builds. Learn more.

Works with projects that use Flutter's gen_l10n approach for internationalization, and with projects that use Flutter Intl IDE plugin / intl_utils.

Setup for gen_l10n

1. Update pubspec.yaml file

dependencies:
  ...
  localizely_sdk: ^2.5.7

2. Generate localization files

dart run localizely_sdk:generate

3. Update 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,
      ...
    );
  }
}

4. Wrap the root of the app

import 'package:localizely_sdk/localizely_sdk.dart';

void main() {
  runApp(
    LocalizelyInContextEditing(
      enabled: true, // set to false to disable In-Context Editing for production app builds
      child: MyApp(),
    ),
  );
}

5. Connect to Localizely

Run Flutter app on a real device and connect with Localizely.

Setup for Flutter Intl

1. Update pubspec.yaml file

dependencies:
  ...
  localizely_sdk: ^2.5.7

flutter_intl:
  ...
  localizely:
    ota_enabled: true # Required for In-Context Editing

2. Trigger localization files generation by Flutter Intl IDE plugin or by intl_utils library

3. Wrap the root of the app

import 'package:localizely_sdk/localizely_sdk.dart';

void main() {
  runApp(
    LocalizelyInContextEditing(
      enabled: true, // set to false to disable In-Context Editing for production app builds
      child: MyApp(),
    ),
  );
}

4. Connect to Localizely

Run Flutter app on a real device and connect with Localizely.

Notes

• Flutter 3.22.0 may produce analyzer errors after executing the dart run localizely_sdk:generate command. This issue has been resolved in the Flutter master channel, but it is still unaddressed in the stable and beta channels. To rectify these analyzer errors, run flutter pub get once more.

• The localizely_sdk >=2.4.0 <2.5.0 requires an update of min platform versions:

  • Android: Require Android SDK 21 or newer

  • iOS: Require iOS 11 or newer

  As of version 2.5.0, these updates are no longer required due to changes in implementation.

Want to learn more?

• Complete Over-the-Air documentation

• Sample app with Over-the-Air translation updates

• Complete In-Context Editing documentation

• Sample app with In-Context Editing