Devnagri Flutter SDK #

Devnagri let you update translations in your Flutter app without having to release it every single time.

By including our SDK, your app will check for updated translations in Devnagri regularly and download them in the background. The devnagri_sdk package provides support for over-the-air translation updates from devnagri.com.

Features #

• Processes .arb files into .dart files, taking inspiration from and building on the foundation of flutter gen-l10n.
• Custom localization class based on AppLocalizations by flutter gen-l10n for seamless replacement.
• Over-The-Air functionality to deliver your text updates faster.
• Additional OTA support with Mehtods which returns translated text in your desired langauge(List of String, Map, and JSON).

Getting started #

You need to have a working Flutter project. To get started with Flutter internationalization, check out the official documentation.

Note #

Enabling the Over-The-Air functionality in your project requires the following actions:

1. Prepare your Flutter project.
2. Integrate the SDK into your application.

Preparing your Flutter project #

1. Update pubspec.yaml #

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

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:        # Add this line
    sdk: flutter                # Add this line   
  intl: any                     # Add this line 
  devnagri_sdk: ^0.0.1  # Add this line

And enable the generate flag, it is found in the flutter section:

# The following section is specific to Flutter.
flutter:
  generate: true # Add this line

📘 generate flag clarification

The generate flag is required for enabling the synthetic-package customization option. For more information on how to use this option, please refer to the customization section below.

2. Add the english's .arb file to the lib/l10n/ directory #

Add the ARB file to the lib/l10n/ directory of your Flutter project.

📘 Example .arb file for test purposes

You can manually add an intl_en.arb file. For example:

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

3. Set up the project and generate .dart files #

Install dependencies by running:

flutter pub get

Generate the .dart files from the provided .arb files:

dart run devnagri_sdk:gen

You should see the generated files in the lib/l10n/generated/ directory.

Integrating the SDK in your app #

The package provides Devnagri and Dev classes. The Dev class is generated and the name is customizable.

Dev is used to:

• Configure the localization in the app using Dev.delegate and Dev.localizationsDelegates parameters.
• Retrieve the translations using Dev.of(context) calls.

Devnagri is used to:

• Configure a Devnagri project to use with the help of the Devnagri.init method.
• Get supported locales for MaterialApp with Devnagri.supportedLocales
• Get supported languages with Devnagri.supportedLanguagescontaining language name and code
• Get current app locale name with Devnagri.getCurrentLanguageName
• Retrieve the latest translations using the Devnagri.instance.update() method.
• Call Devnagri.languageChanged(context) after changing app locale to download and apply new language.

1. Import all necessary packages and classes #

import 'package:flutter/material.dart';
import 'package:devnagri_sdk/devnagri_sdk.dart';
import 'l10n/generated/l10n.dart';

2. Configure the Devnagri project in the main function #

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Devnagri.init(
          languageBundle: Dev.getLanguageBundle(),
          apiKey: 'DEVNAGRI_API_KEY_HERE',
          delayBetweenRecursion: const Duration(milliseconds: 1000), // Optional
          maxRecursionAllowed: 10 // Optional
  );
  runApp(const MyApp());
}

3. Configure localization in the app widget #

class MyAppState extends State<MyApp>  {
  Locale _currentLocale = SharedPreferences.getIntlLocale();


  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Devanagari SDK',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const DevnagriScope(
              showTakeScreenshotButton: true,
              // To show "Take Screenshot" floating button
              child: MyHomePage()),
              // Wrap home widget with DevnagriScope
      locale: _currentLocale,
      localizationsDelegates: Dev.localizationsDelegates,
      supportedLocales: Devnagri.supportedLocales,
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(
          Dev.of(context).title,
          style: const TextStyle(color: Colors.black),
        ),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Spacer(),
            Text(
              Dev.of(context).helloWorld,
            ),
            const Spacer()
          ],
        ),
      ),
    );
  }
}

The resulting app #

📘 Sample app

You can also find a sample Flutter app with the integrated SDK on GitHub.

Here's a full example that demonstrates usage of the Flutter SDK (important lines are marked with comments):

import 'package:flutter/material.dart';
import 'package:devnagri_sdk/devnagri_sdk.dart'; // Imports the SDK
import 'l10n/generated/l10n.dart'; // Imports the generated Lt class

void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Devnagri.init(
      languageBundle: Dev.getLanguageBundle(),
      apiKey: 'DEVNAGRI_API_KEY_HERE',
    );
    runApp(const MyApp());
}

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

    @override
    Widget build(BuildContext context) {
        return MaterialApp(
         debugShowCheckedModeBanner: false,
         title: 'Devanagari SDK',
         theme: ThemeData(primarySwatch: Colors.blue),
         home: const DevnagriScope(
         showTakeScreenshotButton: true, child: MyHomePage()),
        localizationsDelegates: Dev.localizationsDelegates, 
        // Localization Delegates from Dev(Generated Class)
        supportedLocales: Devnagri.supportedLocales, 
        // Supported Locales from Devnagri Package
    );
    }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(
          Dev.of(context).title,
          style: const TextStyle(color: Colors.black),
        ),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Spacer(),
            Text(Dev.of(context).helloWorld),
            const Spacer()
          ],
        ),
      ),
    );
  }
}

📘 Note on updating local translations

After the translations have been changed (lib/l10n/intl_LOCALE.arb), use the dart run devnagri_sdk:gen command to regenerate the Dart classes.

Change Langauge #

Simply put following snippet after changing your app locale.

 await Devnagri.languageChanged(context);

Get Supported Locales #

To retrieve the supported locales for your plan, use the following code. It will return a list of Language objects, each containing the language code and name.

Devnagri.supportedLanguages;

Additional utility methods: #

To retrieve current app language name

Devnagri.getCurrentLanguageName()

To retrieve Flutter's Locale object from a language code

Devnagri.getLocaleFromCode("Language Code Here i.e en")

Customization #

You can configure the gen tool by adding a dev-l10n.yaml file in the root folder of your project, it allows you to specify the following:

• output-class: The Dart class name to use for the output localization and localizations delegate classes. The default is Dev.
• arb-dir: The directory where the template and translated arb files are located. The default is lib/l10n.
• output-dir: The directory where the generated localization classes are written. This option is only relevant if you want to generate the localizations code somewhere else in the Flutter project (ignored if synthetic-package is true). If it is not specified the defaults directory is {arb-dir}/generated.
• output-localization-file: The filename for the output localization and localizations delegate classes. The default is l10n.dart.
• synthetic-package: Determines whether or not the generated output files will be generated as a synthetic package or at a specified directory in the Flutter project (to use this option is required to enable the generate flag in your pubspec file). This flag is false by default.
  • if it is false, the files will be generated in the directory specified by output-dir (check the behaviour of this property defined above).
  • If it is true, the files will be created in a synthetic package located at .dart_tool/flutter_gen/gen-l10n. To use them, use import 'package:flutter_gen/gen_l10n/l10n.dart';.

For example:

output-class: MyCustomClassName
arb-dir: devnagari/l10n
output-dir: devnagari/l10n/custom
output-localization-file: localizations.dart

Methods for Seamless Translation Integration #

Translate and return your data in its original format with our comprehensive methods. Discover how these tools can enhance your app's localization effortlessly.

Use the following method to get your list of strings translated:

Devnagri.getTranslationsWithList(List<String> stringsToTranslate)

Map Translation with Ignore Keys

Get your Map<String, String> translated using this method. You can also add keys to the ignoreKeys parameter to prevent certain keys from being translated:

Devnagri.getTranslationsWithMapAndIgnoredKeys({
  required Map<String, String> sourceTranslations,
  required List<String> ignoreKeys
})

JSON Translation with Ignore Keys

Translate your JSON with this method. You can add keys to the ignoreKeys parameter to exclude specific keys from translation:

Devnagri.getTranslationsWithJSONAndIgnoreKeys({
  required String jsonString,
  required List<String> ignoreKeys
})

Screenshots #

To keep Devnagri AI aware of context for proper translations, you can share screenshot of current screen along with currently used string. This can be achieved by pressing floating button coming out of box from devnagri_sdk, it'll do all the work for you.

To make this button visible, pass true to showTakeScreenshotButton property of DevnagriScope which wrapped on home widget in MaterialApp.

Place Devnagri.onTabChange() on tab change to register strings from new tab.

License #

This plugin is licensed under the BSD 3 Clause License.

Copyright (c) Devnagri team.