lokalise_flutter_sdk 0.4.0

Lokalise Flutter SDK over-the-air translations updates. This package provides new translations from lokalise.com without a new app release.

Lokalise Flutter SDK

This package provides over-the-air translation updates from lokalise.com.

These instructions can also be found in our Developer Hub.

Getting started

You need to have a working Flutter project for this. To get started with Flutter Internalization check the official documentation.

1. Update the pubspec.yaml

Add the intl and lokalise_flutter_sdk packages to the pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:        # Add this line
    sdk: flutter                # Add this line   
  intl: ^0.17.0                 # Add this line 
  lokalise_flutter_sdk: ^0.4.0  # Add this line

2. Add .arb files with to lib/l10n/ directory

Add intl_en.arb file. For example:

{
    "@@locale": "en",
    "helloWorld": "Hello World!",
    "@helloWorld": {
      "description": "The conventional newborn programmer greeting"
    },
    "title": "Yes, this is a title!"
}

Add one ARB file for each locale you need to support in your Flutter app. Name them using the following pattern: intl_LOCALE.arb. Here's a example of intl_es.arb file:

{
    "helloWorld": "¡Hola Mundo!"
}

Note: You can also download the ARB files for your project using Lokalise. Just make sure to choose the Flutter(.arb) format and enable the File structure -> One file per language. Bundle structure: option and set the value to intl_%LANG_ISO%.%FORMAT%.

3. Setup the project and generate .dart files

Install dependencies by running:

flutter pub get

Generate .dart files from provided .arb files:

flutter pub run lokalise_flutter_sdk:gen-lok-l10n

You should see a new generated folder lib/generated/.

Initialize the SDK

Change your main.dart file:

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:lokalise_flutter_sdk/ota/lokalise_sdk.dart';
import 'generated/l10n.dart';

void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Lokalise.init(
        sdkToken: 'Lokalise SDK Token',
        projectId: 'Project ID',
        preRelease: true, // Add this only if you want to use prereleases
        appVersion: 0 // 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(const MyApp());
}

class MyApp extends StatelessWidget {
    const MyApp({Key? key}) : super(key: key);

    @override
    Widget build(BuildContext context) {
        return MaterialApp(
            title: 'Lokalise SDK',
            theme: ThemeData(
                primarySwatch: Colors.blue,
            ),
            home: const MyHomePage(),
            localizationsDelegates: const [
              Lt.delegate,
              GlobalMaterialLocalizations.delegate,
              GlobalWidgetsLocalizations.delegate,
              GlobalCupertinoLocalizations.delegate,
            ],
            // To summarize you can also use the following localizationsDelegates
            // localizationsDelegates: Lt.localizationsDelegates, 
            supportedLocales: Lt.supportedLocales,
        );
    }
}

class MyHomePage extends StatefulWidget {
    const MyHomePage({Key? key}) : super(key: key);

    @override
    State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  bool _isLoading = true;

    @override
    void initState() {
        super.initState();
        Lokalise.instance.update().then( // after localization delegates
            (response) => setState(() {
              _isLoading = false; 
            }),
            onError: (error) => setState(() { _isLoading = false; })
        );
    }

    @override
    Widget build(BuildContext context) {
        return Scaffold(
            appBar: AppBar(
                title: Text(Lt.of(context).title),
            ),
            body: Center(
              child: _isLoading 
                ? const CircularProgressIndicator() 
                : Center(
                    child: Text(Lt.of(context).helloWorld),
            )),
        );
    }
}

After the translations have been changed (lib/l10n/intl_LOCALE.arb), use the flutter pub run lokalise_flutter_sdk:gen-lok-l10n command to regenerate the Dart classes.

Customization

You can customize the generated Dart class name by adding a lok-l10n.yaml file on lib/l10n like this:

output-class: 'MyCustomClassName'

Notes for the beta version

• Working with Flutter SDK bundles is possible only trough the API for now.
• To create a new bundle, make sure to follow the Over-the-air translation updates section. If you choose different options you might experience some issues. We are aware of them and are working on improvements.
• To manage bundles and create the OTA SDK token follow the Working with the OTA API section.
• Plural translations are not supported yet.

Over-the-air translation updates

If you follow the previous steps you will be able to use the translations from the ARB files in your project. Using Lokalise.instance.update() you can retrieve the latest translations version for your app, and in order to use it you only need to generate a new translation bundle on Lokalise.

To generate a new bundle you need to make an API request to the download files endpoint with the following options:

{
    "format": "flutter_sdk",
    "export_empty_as": "skip",
    "placeholder_format": "icu",
    "plural_format": "icu"
}

For more info about how to do the request, please check this.

License

This plugin is licensed under the BSD 3 Clause License.

Copyright (c) Lokalise team.