easy_localization 2.1.0+0

  • Readme
  • Changelog
  • Example
  • Installing
  • 98

Easy localization

Pub Version Code Climate issues GitHub closed issues GitHub contributors GitHub repo size GitHub forks GitHub stars Coveralls github branch GitHub Workflow Status CodeFactor Grade GitHub license

Easy and Fast internationalizing your Flutter Apps, this package simplify the internationalizing process using Json file

Why easy_localization #

  • [x] simplifying and making easy the internationalizing process in Flutter.
  • [x] Using JSON Files .
  • [x] Error widget
  • [x] Based on Bloc Archi
  • [x] Load locale from remote or backend.
  • [x] Automatically saving App state (save/restor the selected locale).
  • [x] Supports plural
  • [x] Supports gender
  • [x] Supports Flutter extension.
  • [x] Supports change locale dynamically .
  • [x] Supports for RTL locales
  • [x] Supports for nesting
  • [x] Customization AssetLoader localizations
  • [x] Support for context
  • [x] Testable and easy maintenence

Changelog #

[2.1.0] #

  • Added Error widget.
  • fixed many issues.
  • Based on Bloc.

[2.0.2] #

  • fixed many issues
  • optimized and clean code more stability

[2.0.1] #

  • Added change locale dynamically saveLocale default value true
  • fixed many issues

Getting Started #

Configuration #

Add this to your package's pubspec.yaml file:

dependencies:
  # stable version install from https://pub.dev/packages
  easy_localization: <last_version>

  # Dev version install from git REPO
  easy_localization:
    git: https://github.com/aissat/easy_localization.git

you must add flutter_localizations to your pubspec.yaml file:

dependencies:
  flutter_localizations:
    sdk: flutter

Load translations from local assets

You must create a folder in your project's root: the path. Some examples:

/assets/"langs" , "i18n", "locale" or anyname ...

/resources/"langs" , "i18n", "locale" or anyname ...

Inside this folder, must put the json files containing the translated keys :

path/${languageCode}-${countryCode}.json

example:

  • en.json to en-US.json
  • ar.json to ar-DZ.json
  • zh.json to zh-CN.json
  • zh.json to zh-TW.json

must declare the subtree in your pubspec.yaml as assets:

flutter:
  assets:
    - {`path`/{languageCode}-{countryCode}.json}

The next step :

import 'dart:developer';

import 'package:example/lang_view.dart';
import 'package:example/my_flutter_app_icons.dart';
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:easy_localization/easy_localization.dart';

void main(){
  runApp(EasyLocalization(
    child: MyApp(),
    supportedLocales: [Locale('en', 'US'), Locale('ar', 'DZ')],
    path: 'resources/langs',
    // fallbackLocale: Locale('en', 'US'),
    // useOnlyLangCode: true,
    // optional assetLoader default used is RootBundleAssetLoader which uses flutter's assetloader
    // assetLoader: RootBundleAssetLoader()
    // assetLoader: NetworkAssetLoader()
    // assetLoader: TestsAssetLoader()
    // assetLoader: FileAssetLoader()
    // assetLoader: StringAssetLoader()
  ));
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      localizationsDelegates: [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        EasyLocalization.of(context).delegate,
      ],
      supportedLocales: EasyLocalization.of(context).supportedLocales,
      locale: EasyLocalization.of(context).locale,
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Easy localization'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key key, this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int counter = 0;
  bool _gender = true;

  incrementCounter() {
    setState(() {
      counter++;
    });
  }

  switchGender(bool val) {
    setState(() {
      _gender = val;
    });
  }

  @override
  Widget build(BuildContext context) {
    log(tr("title"), name: this.toString() );
    return Scaffold(
      appBar: AppBar(
        title: Text("title").tr(context: context),
        actions: <Widget>[
          FlatButton(
            child: Icon(Icons.language),
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                    builder: (_) => LanguageView(), fullscreenDialog: true),
              );
            },
          ),
        ],
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Spacer(
              flex: 1,
            ),
            Text(
              'switch.with_arg',
              style: TextStyle(
                  color: Colors.grey.shade600,
                  fontSize: 19,
                  fontWeight: FontWeight.bold),
            ).tr(args: ["aissat"], gender: _gender ? "female" : "male"),
            Text(
              tr('switch', gender: _gender ? "female" : "male"),
              style: TextStyle(
                  color: Colors.grey.shade600,
                  fontSize: 15,
                  fontWeight: FontWeight.bold),
            ),
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: <Widget>[
                Icon(MyFlutterApp.male_1),
                Switch(value: _gender, onChanged: switchGender),
                Icon(MyFlutterApp.female_1),
              ],
            ),
            Spacer(
              flex: 1,
            ),
            Text('msg').tr(args: ['aissat', 'Flutter']),
            Text('clicked').plural(counter),
            FlatButton(
              onPressed: () {
                incrementCounter();
              },
              child: Text('clickMe').tr(),
            ),
            SizedBox(
              height: 15,
            ),
            Text(
                plural('amount', counter,
                    format: NumberFormat.currency(
                        locale: Intl.defaultLocale,
                        symbol: "€")),
                style: TextStyle(
                    color: Colors.grey.shade900,
                    fontSize: 18,
                    fontWeight: FontWeight.bold)),
            SizedBox(
              height: 20,
            ),
            Text('profile.reset_password.title').tr(),
            Spacer(
              flex: 2,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: incrementCounter,
        child: Text('+1'),
      ),
    );
  }
}

to change Locale

EasyLocalization.of(context).locale = locale;

Load translations from Customization AssetLoader

for example You need to have backend endpoint (loadPath) where resources get loaded from and your endpoint must containing the translated keys.

example:

class NetworkAssetLoader extends AssetLoader {
  @override
  Future<Map<String, dynamic>> load(String localePath) async {
    return http
        .get(localePath)
        .then((response) => json.decode(response.body.toString()));
  }

The next step :

...
void main(){
  runApp(EasyLocalization(
    child: MyApp(),
    supportedLocales: [Locale('en', 'US'), Locale('ar', 'DZ')],
    path: 'https://raw.githubusercontent.com/aissat/easy_localization/master/example/resources/langs',
    assetLoader: NetworkAssetLoader()
    // fallbackLocale: Locale('en', 'US'),
    // useOnlyLangCode: true,
    // optional assetLoader default used is RootBundleAssetLoader which uses flutter's assetloader
    // assetLoader: RootBundleAssetLoader()
    // assetLoader: TestsAssetLoader()
    // assetLoader: FileAssetLoader()
    // assetLoader: StringAssetLoader()
  ));
}
...

Screenshots #

Arbic RTLEnglish LTR
alt textalt text
РусскийDutch
alt textalt text
Error widgetLanguage widget
alt textalt text

Donations #


We need your support. Projects like this can not be successful without support from the community. If you find this project useful, and would like to support further development and ongoing maintenance, please consider donating. Devs gotta eat! PayPal

  • Donate $5: Thank's for creating this project, here's a coffee for you!

  • Donate $10: Wow, I am stunned. Let me take you to the movies!

  • Donate $15: I really appreciate your work, let's grab some lunch!

  • Donate $25: That's some awesome stuff you did right there, dinner is on me!

Of course, you can also choose what you want to donate. All donations are very much appreciated!

Contributors thanks #

contributors

Changelog #

[2.1.0] #

  • Added Error widget.
  • fixed many issues.
  • Based on Bloc.
  • optimized and clean code more stability

[2.0.2] #

  • fixed many issues
  • optimized and clean code more stability

[2.0.1] #

  • Added change locale dynamically saveLocale default value true
  • fixed many issues

[2.0.0] #

this version came with many updates, here are the main ones:

  • optimized and clean code more stability

  • fixed many issues

  • added Unite test

  • Customization AssetLoader localizations assetLoader for more details see custom assetLoader

  • added fallbackLocale as optional

  • Hiding EasyLocalizationProvider

  • refactor and update approach localization for more details see example:

    // Now V2.0.0
    runApp(EasyLocalization(
      child: MyApp(),
      ...
    ));
    
    // after V2.0.0
    runApp(EasyLocalization(
      child: MyApp(),
      ...
    ));
    ...
    class MyApp extends StatelessWidget {
    @override
    Widget build(BuildContext context) {
      var data = EasyLocalizationProvider.of(context).data;
      return EasyLocalizationProvider(...);
    }}
    
  • added Support for context

      tr("key", context: context),
      plural("key", 1 , context: context),
    

[1.4.1] #

  • optimized and clean code

  • fixed many issues

  • added extension for Strings

    // after 1.4.1
    Text('title'.tr()),
    Text('switch'.tr( gender: _gender ? "female" : "male")),
    Text('counter'.plural(counter)),
    

[1.4.0] #

  • refactor code changed call AppLocalizations.of(context).tr() AppLocalizations.of(context).plural() to tr() and plural()

    // after 1.4.0
    Text(
      tr('switch', gender: _gender ? "female" : "male"),
    ),
    
    // before 1.4.0
    Text(
      AppLocalizations.of(context).tr('switch', gender: _gender ? "female" : "male"),
    ),
    
  • added Flutter extension for Text widget

    // after 1.4.0
    Text('switch').tr( gender: _gender ? "female" : "male"),
    Text('counter').plural(counter),
    

[1.3.5] #

  • merge gender() and tr() .

    {
      "switch":{
        "male": "Hi man ;)",
        "female": "Hello girl :)"
      }
    }
    
    new Text(
      AppLocalizations.of(context).tr('switch', gender: _gender ? "female" : "male"),
    ),
    
  • use parameters args for gender.

    {
      "switch":{
        "male": "Hi man ;) {}",
        "female": "Hello girl :) {}"
      }
    }
    
    new Text(
      AppLocalizations.of(context).tr('switch', args:["Naama"] gender: _gender ? "female" : "male"),
    ),
    

[1.3.4] #

  • adeed Gender [female,male] gender() .

    {
      "switch":{
        "male": "Hi man ;)",
        "female": "Hello girl :)"
      }
    }
    
    new Text(
      AppLocalizations.of(context).gender('switch', _gender ? "female" : "male"),
    ),
    `
    

[1.3.3+1] #

  • updated plural() thanks shushper .

    {
      "text": {
        "day": {
          "zero":"{} дней",
          "one": "{} день",
          "two": "{} дня",
          "few": "{} дня",
          "many": "{} дней",
          "other": "{} дней"
        }
      }
    }
    

[1.3.3] #

  • removed data.savedLocale .
  • optimized and clean code
  • fixed many issues

[1.3.2] #

  • plural() added property resolver for nested key translations

    {
    "text": {
      "day": {
        "zero": "day",
        "one": "day",
        "other": "days"
        }
      }
    }
    
    
    new Text(
      AppLocalizations.of(context).plural("text.day", 2),
    ),
    
  • fixed many issues

[1.3.1] #

  • add useOnlyLangCode flag

[1.3.0] #

  • Load translations from remote or backend
  • fixed many issues

[1.2.1] #

  • supported shared_preferences
  • Save selected localization

[1.2.0] #

  • Added property resolver for nested key translations
  • return translate key if the element or path not exist
{
  "title": "Hello",
  "msg": "Hello {} in the {} world ",
  "clickMe": "Click me",
  "profile": {
    "reset_password": {
      "title": "Reset Password",
      "username": "Username",
      "password": "password"
    }
  },
  "clicked": {
    "zero": "You clicked {} times!",
    "one": "You clicked {} time!",
    "other": "You clicked {} times!"
  }
}

new Text(
  AppLocalizations.of(context).tr('profile.reset_password.title'),
 ),

[1.0.4] #

  • Added Support country codes

[1.0.3] #

  • Updated tr() function added Multi Argument

[1.0.2] #

  • Added string pluralisation .
  • Added Argument to tr() function.

example/lib/main.dart

import 'dart:developer';
import 'dart:ui';

import 'package:example/lang_view.dart';
import 'package:example/my_flutter_app_icons.dart';
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:easy_localization/easy_localization.dart';

void main() {
  runApp(EasyLocalization(
    child: MyApp(),
    supportedLocales: [
      Locale('en', 'US'),
      Locale('ar', 'DZ'),
      Locale('de', 'DE'),
      Locale('ru', 'RU')
    ],
    path: 'resources/langs',
    // fallbackLocale: Locale('en', 'US'),
    // saveLocale: false,
    // useOnlyLangCode: true,
    // optional assetLoader default used is RootBundleAssetLoader which uses flutter's assetloader
    // assetLoader: RootBundleAssetLoader()
    // assetLoader: NetworkAssetLoader()
    // assetLoader: TestsAssetLoader()
    // assetLoader: FileAssetLoader()
    // assetLoader: StringAssetLoader()
    // preloaderColor: Colors.red,
  ));
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    log(EasyLocalization.of(context).locale.toString(),
        name: this.toString() + "# locale");
    log("title".tr().toString(), name: this.toString() + "# locale");
    return MaterialApp(
      title: 'title'.tr(),
      localizationsDelegates: [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        EasyLocalization.of(context).delegate,
      ],
      supportedLocales: EasyLocalization.of(context).supportedLocales,
      locale: EasyLocalization.of(context).locale,
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Easy localization'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key key, this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int counter = 0;
  bool _gender = true;

  incrementCounter() {
    setState(() {
      counter++;
    });
  }

  switchGender(bool val) {
    setState(() {
      _gender = val;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("title").tr(context: context),
        //Text(AppLocalizations.of(context).tr('title')),
        actions: <Widget>[
          FlatButton(
            child: Icon(Icons.language),
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                    builder: (_) => LanguageView(), fullscreenDialog: true),
              );
            },
          ),
        ],
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Spacer(
              flex: 1,
            ),
            Text(
              'switch.with_arg',
              style: TextStyle(
                  color: Colors.grey.shade600,
                  fontSize: 19,
                  fontWeight: FontWeight.bold),
            ).tr(args: ["aissat"], gender: _gender ? "female" : "male"),
            Text(
              tr('switch', gender: _gender ? "female" : "male"),
              style: TextStyle(
                  color: Colors.grey.shade600,
                  fontSize: 15,
                  fontWeight: FontWeight.bold),
            ),
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: <Widget>[
                Icon(MyFlutterApp.male_1),
                Switch(value: _gender, onChanged: switchGender),
                Icon(MyFlutterApp.female_1),
              ],
            ),
            Spacer(
              flex: 1,
            ),
            Text('msg').tr(args: ['aissat', 'Flutter']),
            Text('clicked').plural(counter),
            FlatButton(
              onPressed: () {
                incrementCounter();
              },
              child: Text('clickMe').tr(),
            ),
            SizedBox(
              height: 15,
            ),
            Text(
                plural('amount', counter,
                    format: NumberFormat.currency(
                        locale: Intl.defaultLocale, symbol: "€")),
                style: TextStyle(
                    color: Colors.grey.shade900,
                    fontSize: 18,
                    fontWeight: FontWeight.bold)),
            SizedBox(
              height: 20,
            ),
            RaisedButton(
              onPressed: () {
                EasyLocalization.of(context).deleteSaveLocale();
              },
              child: Text('reset_locale').tr(),
            ),
            Spacer(
              flex: 1,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: incrementCounter,
        child: Text('+1'),
      ),
    );
  }
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  easy_localization: ^2.1.0+0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:easy_localization/easy_localization.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
96
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
98
Learn more about scoring.

We analyzed this package on Apr 3, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6
  • Flutter: 1.12.13+hotfix.8

Health issues and suggestions

Document public APIs. (-0.30 points)

41 out of 42 API elements have no dartdoc comment.Providing good documentation for libraries, classes, functions, and other API elements improves code readability and helps developers find and use your API.

Format lib/src/bloc/easy_localization_bloc.dart.

Run flutter format to format lib/src/bloc/easy_localization_bloc.dart.

Format lib/src/easy_localization_app.dart.

Run flutter format to format lib/src/easy_localization_app.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.6.0 <3.0.0
flutter 0.0.0
intl ^0.16.0 0.16.1
shared_preferences ^0.5.6+3 0.5.6+3
Transitive dependencies
collection 1.14.11 1.14.12
flutter_web_plugins 0.0.0
meta 1.1.8
path 1.6.4
shared_preferences_macos 0.0.1+6
shared_preferences_platform_interface 1.0.3
shared_preferences_web 0.1.2+4
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_localizations
flutter_test