v4.0.0-dev — API refactor, caching, fallback fixes, and benchmark suite

README.md

@@ -32,6 +32,7 @@ Easy and Fast internationalization for your Flutter Apps
 - 💻 Code generation for localization files and keys.
 - 🛡️ Null safety
 - 🖨️ Customizable logger.
+- 🗄️ Pluggable storage (`SharedPreferencesStorage`, `InMemoryStorage`, or custom).
 
 ## Getting Started
 
@@ -102,14 +103,17 @@ import 'package:easy_localization/easy_localization.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
-  await EasyLocalization.ensureInitialized();
-
+  await EasyLocalization.ensureInitialized(
+    assetLoader: RootBundleAssetLoader(
+      path: 'assets/translations',
+      supportedLocales: [Locale('en', 'US'), Locale('de', 'DE')],
+    ),
+  );
+
   runApp(
     EasyLocalization(
-      supportedLocales: [Locale('en', 'US'), Locale('de', 'DE')],
-      path: 'assets/translations', // <-- change the path of the translation files 
       fallbackLocale: Locale('en', 'US'),
-      child: MyApp()
+      child: MyApp(),
     ),
   );
 }
@@ -135,9 +139,7 @@ class MyApp extends StatelessWidget {
 | ----------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | key                     | false    |                           | Widget key.                                                                                                                                                                   |
 | child                   | true     |                           | Place for your main page widget.                                                                                                                                              |
-| supportedLocales        | true     |                           | List of supported locales.                                                                                                                                                    |
-| path                    | true     |                           | Path to your folder with localization files.                                                                                                                                  |
-| assetLoader             | false    | `RootBundleAssetLoader()` | Class loader for localization files. You can use custom loaders from [Easy Localization Loader](https://github.com/aissat/easy_localization_loader) or create your own class. |
+| assetLoader             | true     |                           | Class loader for localization files. Passes `path` and `supportedLocales` via `RootBundleAssetLoader`. You can use custom loaders from [Easy Localization Loader](https://github.com/aissat/easy_localization_loader) or create your own class. |
 | fallbackLocale          | false    |                           | Returns the locale when the locale is not in the list `supportedLocales`.                                                                                                     |
 | startLocale             | false    |                           | Overrides device locale.                                                                                                                                                      |
 | saveLocale              | false    | `true`                    | Save locale in device storage.                                                                                                                                                |
@@ -149,21 +151,98 @@ class MyApp extends StatelessWidget {
 
 ### 🔥 Initialize library
 
-Call `EasyLocalization.ensureInitialized()` in your main before runApp.
+Call `EasyLocalization.ensureInitialized()` in your main before runApp. Pass an `assetLoader` with your translation `path` and `supportedLocales`.
+
+```dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  await EasyLocalization.ensureInitialized(
+    assetLoader: RootBundleAssetLoader(
+      path: 'assets/translations',
+      supportedLocales: [Locale('en', 'US'), Locale('de', 'DE')],
+    ),
+  );
+
+  runApp(EasyLocalization(
+    fallbackLocale: Locale('en', 'US'),
+    child: MyApp(),
+  ));
+}
+```
+
+### 🗄️ Storage
+
+The selected locale can be persisted across app restarts using a pluggable storage backend.
+
+#### `IEasyLocalizationStorage`
+
+Abstract interface with two implementations:
+
+| Implementation | Backend | Use case |
+|---|---|---|
+| `SharedPreferencesStorage` | `shared_preferences` | Production (default when omitted) |
+| `InMemoryStorage` | In-memory map | Tests, ephemeral use |
+
+Pass storage to `ensureInitialized()`:
 
 ```dart
-void main() async{
-  // ...
-  // Needs to be called so that we can await for EasyLocalization.ensureInitialized();
+void main() async {
   WidgetsFlutterBinding.ensureInitialized();
 
-  await EasyLocalization.ensureInitialized();
-  // ...
-  runApp(....)
-  // ...
+  await EasyLocalization.ensureInitialized(
+    assetLoader: RootBundleAssetLoader(
+      path: 'assets/translations',
+      supportedLocales: [Locale('en', 'US'), Locale('de', 'DE')],
+    ),
+    storage: SharedPreferencesStorage(), // optional
+  );
+
+  runApp(EasyLocalization(
+    fallbackLocale: Locale('en', 'US'),
+    child: MyApp(),
+  ));
+}
+```
+
+#### Custom storage
+
+Implement `IEasyLocalizationStorage` for any backend:
+
+```dart
+class MyStorage implements IEasyLocalizationStorage {
+  @override
+  Future<void> init() async { /* open connection */ }
+
+  @override
+  Future<String?> getValue(String key) async { /* read */ }
+
+  @override
+  Future<void> setValue(String key, String value) async { /* write */ }
+
+  @override
+  Future<void> removeValue(String key) async { /* delete */ }
+
+  @override
+  Future<void> close() async { /* cleanup */ }
 }
 ```
 
+#### Testing with `InMemoryStorage`
+
+```dart
+final storage = InMemoryStorage();
+await EasyLocalization.ensureInitialized(
+  assetLoader: const RootBundleAssetLoader(path: 'assets/translations'),
+  storage: storage,
+);
+
+// In-memory — no mock setup needed
+print(await storage.getValue('locale')); // null
+```
+
+---
+
 ### 🔥 Change or get locale
 
 Easy localization uses extension methods [BuildContext] for access to locale.
@@ -417,7 +496,7 @@ RaisedButton(
 
 At any time, you can take the main [properties](#-easy-localization-widget-properties) of the Easy localization widget using [BuildContext].
 
-Are supported: supportedLocales, fallbackLocale, localizationDelegates.
+Are supported: supportedLocales, fallbackLocale, localizationDelegates, assetLoader.
 
 Example:
 
@@ -454,12 +533,14 @@ Steps:
   ```dart
   import 'generated/codegen_loader.g.dart';
   ...
-  void main(){
+  void main() async {
+    WidgetsFlutterBinding.ensureInitialized();
+    await EasyLocalization.ensureInitialized(
+      assetLoader: CodegenLoader(),
+    );
     runApp(EasyLocalization(
       child: MyApp(),
-      supportedLocales: [Locale('en', 'US'), Locale('ar', 'DZ')],
-      path: 'resources/langs',
-      assetLoader: CodegenLoader()
+      fallbackLocale: Locale('en', 'US'),
     ));
   }
   ...

bin/generate.dart

@@ -244,7 +244,7 @@ class CodegenLoader extends AssetLoader{
   const CodegenLoader();
 
   @override
-  Future<Map<String, dynamic>?> load(String path, Locale locale) {
+  Future<Map<String, dynamic>> load({Locale? locale}) {
     return Future.value(mapLocales[locale.toString()]);
   }
 

example/lib/generated/codegen_loader.g.dart

@@ -6,11 +6,11 @@ import 'dart:ui';
 
 import 'package:easy_localization/easy_localization.dart' show AssetLoader;
 
-class CodegenLoader extends AssetLoader {
+class CodegenLoader implements AssetLoader {
   const CodegenLoader();
 
   @override
-  Future<Map<String, dynamic>> load(String fullPath, Locale locale) {
+  Future<Map<String, dynamic>> load(Locale locale) {
     return Future.value(mapLocales[locale.toString()]);
   }
 
@@ -310,4 +310,8 @@ class CodegenLoader extends AssetLoader {
     "ru_RU": ru_RU,
     "ru": ru
   };
+
+  @override
+  // TODO: implement path
+  String get path => throw UnimplementedError();
 }

example/lib/lang_view.dart

@@ -12,7 +12,7 @@ class LanguageView extends StatelessWidget {
           '',
           style: TextStyle(color: Colors.black),
         ),
-        backgroundColor: Colors.white,
+        // backgroundColor: Colors.white,
         iconTheme: IconThemeData(color: Colors.black),
         elevation: 0,
       ),
@@ -29,7 +29,7 @@ class LanguageView extends StatelessWidget {
               child: Text(
                 'Choose language',
                 style: TextStyle(
-                  color: Colors.blue,
+                  color: Theme.of(context).primaryColor,
                   fontFamily: 'Montserrat',
                   fontWeight: FontWeight.w700,
                   fontSize: 18,
@@ -97,26 +97,41 @@ class _SwitchListTileMenuItem extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return Container(
-      margin: EdgeInsets.only(left: 10, right: 10, top: 5),
-      decoration: BoxDecoration(
-        border:
-            isSelected(context) ? Border.all(color: Colors.blueAccent) : null,
+    return Material(
+      type: MaterialType.transparency,
+      child: Container(
+        margin: EdgeInsets.symmetric(vertical: 2, horizontal: 24),
+        decoration: BoxDecoration(
+          border: isSelected(context)
+              ? Border.all(color: Theme.of(context).primaryColor)
+              : null,
+        ),
+        child: ListTile(
+            dense: true,
+            title: Text(
+              title,
+            ),
+            subtitle: Text(
+              subtitle,
+            ),
+            onTap: () async {
+              log(locale.toString(), name: toString());
+              final sw = Stopwatch()..start();
+              await context.setLocale(locale); //BuildContext extension method
+              sw.stop();
+              final ms = sw.elapsedMicroseconds / 1000;
+              debugPrint('BENCH\tswitch (interactive: ${locale.toString().padRight(8)})\t${ms.toStringAsFixed(2)} ms');
+              if (context.mounted) {
+                ScaffoldMessenger.of(context).showSnackBar(
+                  SnackBar(
+                    content: Text('Switch time: ${ms.toStringAsFixed(2)} ms'),
+                    duration: const Duration(seconds: 1),
+                  ),
+                );
+                Navigator.pop(context);
+              }
+            }),
       ),
-      child: ListTile(
-          dense: true,
-          // isThreeLine: true,
-          title: Text(
-            title,
-          ),
-          subtitle: Text(
-            subtitle,
-          ),
-          onTap: () async {
-            log(locale.toString(), name: toString());
-            await context.setLocale(locale); //BuildContext extension method
-            Navigator.pop(context);
-          }),
     );
   }
 }

example/lib/main.dart

@@ -8,22 +8,8 @@ import 'lang_view.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
-  await EasyLocalization.ensureInitialized();
-
-  runApp(EasyLocalization(
-    supportedLocales: [
-      Locale('en', 'US'),
-      Locale('ar', 'DZ'),
-      Locale('de', 'DE'),
-      Locale('ru', 'RU')
-    ],
-    path: 'resources/langs',
-    child: MyApp(),
-    // fallbackLocale: Locale('en', 'US'),
-    // startLocale: Locale('de', 'DE'),
-    // saveLocale: false,
-    // useOnlyLangCode: true,
-
+  await EasyLocalization.ensureInitialized(
+    assetLoader: RootBundleAssetLoader(path: 'resources/langs/json'),
     // optional assetLoader default used is RootBundleAssetLoader which uses flutter's assetloader
     // install easy_localization_loader for enable custom loaders
     // assetLoader: RootBundleAssetLoader()
@@ -35,18 +21,30 @@ void main() async {
     // assetLoader: XmlAssetLoader() //multiple files
     // assetLoader: XmlSingleAssetLoader() //single file
     // assetLoader: CodegenLoader()
-  ));
+  );
+
+  runApp(
+    EasyLocalization(
+      child: MyApp(),
+      // fallbackLocale: Locale('en', 'US'),
+      // startLocale: Locale('ar', 'DZ'),
+      supportedLocales: [Locale('en', 'US'), Locale('ar', 'DZ')],
+      saveLocale: false,
+      // useOnlyLangCode: true,
+    ),
+  );
 }
 
 class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
+    print('supportedLocales => ${context.supportedLocales}');
     return MaterialApp(
       localizationsDelegates: context.localizationDelegates,
       supportedLocales: context.supportedLocales,
       locale: context.locale,
       theme: ThemeData(
-        primarySwatch: Colors.blue,
+        useMaterial3: true,
       ),
       home: MyHomePage(title: 'Easy localization'),
     );
@@ -94,7 +92,7 @@ class _MyHomePageState extends State<MyHomePage> {
             },
             child: Icon(
               Icons.language,
-              color: Colors.white,
+              // color: Colors.white,
             ),
           ),
         ],

example/linux/flutter/CMakeLists.txt

@@ -82,7 +82,7 @@ add_custom_command(
   COMMAND ${CMAKE_COMMAND} -E env
     ${FLUTTER_TOOL_ENVIRONMENT}
     "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.sh"
-      linux-x64 ${CMAKE_BUILD_TYPE}
+      ${FLUTTER_TARGET_PLATFORM} ${CMAKE_BUILD_TYPE}
   VERBATIM
 )
 add_custom_target(flutter_assemble DEPENDS

example/pubspec.yaml

@@ -14,7 +14,7 @@ publish_to: none
 version: 1.0.0+1
 
 environment:
-  sdk: ">=2.12.0-0 <4.0.0"
+  sdk: ">=3.1.0 <4.0.0"
 
 dependencies:
   flutter:
@@ -49,6 +49,10 @@ flutter:
   # To add assets to your application, add an assets section, like this:
   assets:
     - resources/langs/
+    - resources/langs/json/
+    - resources/langs/yml/
+    - resources/langs/xml/
+
   #  - images/a_dot_burr.jpeg
   #  - images/a_dot_ham.jpeg
   # An image asset can refer to one or more resolution-specific "variants", see