Merge branch 'aissat:develop' into develop

Author: gkhloptov

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+### [3.0.8]
+
+- code audit and maintenance updates
+- improved project structure and CI/CD workflows
+
 ### [3.0.7]
 
 - add _supportedLocales in EasyLocalizationController; log and check the deviceLocale when resetLocale;

README.md

@@ -317,6 +317,29 @@ var money = plural('money_named_args', 10.23, namedArgs: {'name': 'Jane', 'money
 var money = plural('money_named_args', 10.23, namedArgs: {'name': 'Jane'}, name: 'money')  // output: Jane has 10.23 dollars
 ```
 
+### ⚙️ Configuring Plural Rules with `ignorePluralRules`
+
+In some languages, pluralization is simple and only involves using zero, one, two, and other forms, without needing to handle the `few` or `many` categories.  
+By default, `easy_localization` ignores the `few` and `many` plural forms and uses just the zero, one, two, and other forms.
+
+If you want to enable the handling of the `few` and `many` plural categories for specific languages, you can configure the `ignorePluralRules` flag to `false` in the `EasyLocalization` initialization.
+
+Here’s how to configure it:
+
+```dart
+EasyLocalization(
+  ignorePluralRules: false, // Set this line to false to enable 'few' and 'many' plural categories
+  supportedLocales: [Locale('en', 'US'), Locale('de', 'DE')],
+  path: 'assets/translations',
+  fallbackLocale: Locale('en', 'US'),
+  child: MyApp()
+)
+```
+
+Setting `ignorePluralRules: false` will enable the `few` and `many` plural categories, allowing your translations to handle all plural forms, including `few` and `many`, for supported languages.
+
+
+
 ### 🔥 Linked translations:
 
 If there's a translation key that will always have the same concrete text as another one you can just link to it. To link to another translation key, all you have to do is to prefix its contents with an `@:` sign followed by the full name of the translation key including the namespace you want to link to.
@@ -519,6 +542,21 @@ print(LocaleKeys.title.tr()); //String
 Text(LocaleKeys.title).tr(); //Widget
 ```
 
+### ✅ Audit missing keys
+
+If you prefer to not generate keys you can see an audit of your translation keys to see the one present in your app code but not in your translations file by running the audit command.
+
+```
+flutter pub run easy_localization:audit
+```
+
+If you are not using the default translations folder path (assets/translations) or the lib folder for your code you can specify your custom paths : 
+
+| Arguments                    | Short | Default               | Description                                                                 |
+| ---------------------------- | ----- | --------------------- | --------------------------------------------------------------------------- |
+| --translations-dir           | -t    | assets/translations   | Folder containing localization files                                        |
+| --source-dir                 | -s    | lib                   | Folder containing the app code files                                        |
+
 ## 🖨️ Logger
 
 [Easy Localization] logger based on [Easy Logger]

bin/audit.dart

@@ -0,0 +1,33 @@
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'audit/audit_command.dart';
+
+void main(List<String> args) {
+  final actual = args.isEmpty ? ['audit'] : args;
+  var parser = ArgParser();
+
+  parser.addOption('translations-dir', abbr: 't', defaultsTo: 'assets/translations');
+  parser.addOption('source-dir', abbr: 's', defaultsTo: 'lib');
+
+  try {
+    var argResults = parser.parse(actual);
+    final transDir = argResults['translations-dir'] as String;
+    final srcDir = argResults['source-dir'] as String;
+
+    if (!Directory(transDir).existsSync()) {
+      stderr.writeln('Error: Translation directory "$transDir" does not exist.');
+      exit(1);
+    }
+
+    if (!Directory(srcDir).existsSync()) {
+      stderr.writeln('Error: Source directory "$srcDir" does not exist.');
+      exit(1);
+    }
+
+    AuditCommand().run(transDir: transDir, srcDir: srcDir);
+  } catch (e) {
+    stderr.writeln('Error: $e');
+    exit(1);
+  }
+}

bin/audit/audit_command.dart

@@ -0,0 +1,152 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:path/path.dart';
+
+class AuditCommand {
+  void run({required String transDir, required String srcDir}) {
+    try {
+      final translationDir = Directory(transDir);
+      final sourceDir = Directory(srcDir);
+
+      if (!translationDir.existsSync()) {
+        stderr.writeln('Error: Translation directory "$transDir" does not exist.');
+        return;
+      }
+
+      if (!sourceDir.existsSync()) {
+        stderr.writeln('Error: Source directory "$srcDir" does not exist.');
+        return;
+      }
+
+      final allTranslations = _loadTranslations(translationDir);
+      final usedKeys = _scanSourceForKeys(sourceDir);
+
+      _report(allTranslations, usedKeys);
+    } catch (e) {
+      stderr.writeln('Error during audit: $e');
+    }
+  }
+
+  /// Walks [translationsDir], reads every `.json`, flattens nested maps
+  /// into dot‑separated keys, and returns a map:
+  ///   { 'en': {'home.title', 'home.subtitle', …}, 'fr': { … } }
+  Map<String, Set<String>> _loadTranslations(Directory translationsDir) {
+    final result = <String, Set<String>>{};
+    for (var file in translationsDir.listSync().whereType<File>()) {
+      if (!file.path.endsWith('.json')) continue;
+
+      try {
+        final langCode = basenameWithoutExtension(file.path);
+        final jsonMap = json.decode(file.readAsStringSync()) as Map<String, dynamic>;
+        result[langCode] = _flatten(jsonMap);
+      } catch (e) {
+        stderr.writeln('Error reading ${file.path}: $e');
+      }
+    }
+    return result;
+  }
+
+  Set<String> _flatten(Map<String, dynamic> json, [String parentKey = '']) {
+    final keys = <String>{};
+    for (var entry in json.entries) {
+      final key = entry.key;
+      final value = entry.value;
+
+      final newKey = parentKey.isEmpty ? key : '$parentKey.$key';
+      if (value is String) {
+        keys.add(newKey);
+        continue;
+      }
+
+      if (value is Map<String, dynamic>) {
+        keys.addAll(_flatten(value, newKey));
+        continue;
+      }
+
+      if (value is List || value is num || value is bool) {
+        keys.add(newKey);
+      }
+    }
+    return keys;
+  }
+
+  Set<String> _scanSourceForKeys(Directory srcDir) {
+    List<RegExp> keyPatterns = [
+      // 1) tr('foo.bar') or tr("foo.bar"), with optional args/comma before the )
+      RegExp(r"""\btr\s*\(\s*['"]([^'"]+)['"](?:\s*,[^)]*)?\)"""),
+
+      // 2) context.tr('foo.bar') same as above but with the context qualifier
+      RegExp(r"""context\s*\.\s*tr\s*\(\s*['"]([^'"]+)['"](?:\s*,[^)]*)?\)"""),
+
+      // 3) 'foo.bar'.tr() or "foo.bar".tr(), allowing whitespace/newlines
+      RegExp(r"""['"]([^'"]+)['"]\s*\.\s*tr\s*\(\s*[^)]*\)"""),
+
+      // 4) generated keys: LocaleKeys.foo_bar (whitespace around the dot ok)
+      RegExp(r"""LocaleKeys\s*\.\s*([A-Za-z0-9_]+)"""),
+
+      // 5) plural() calls
+      RegExp(r"""\bplural\s*\(\s*['"]([^'"]+)['"](?:\s*,[^)]*)?\)"""),
+
+      // 6) context.plural() calls
+      RegExp(r"""context\s*\.\s*plural\s*\(\s*['"]([^'"]+)['"](?:\s*,[^)]*)?\)"""),
+    ];
+
+    final used = <String>{};
+
+    for (var file in srcDir.listSync(recursive: true).whereType<File>().where((f) => f.path.endsWith('.dart'))) {
+      try {
+        final content = file.readAsStringSync();
+        for (var pattern in keyPatterns) {
+          final matches = pattern.allMatches(content);
+          for (var match in matches) {
+            if (match.groupCount > 0) {
+              String key = match.group(1)!;
+              if (pattern.pattern.contains('LocaleKeys')) {
+                key = key.replaceAll('_', '.');
+              }
+              used.add(key);
+            }
+          }
+        }
+      } catch (e) {
+        stderr.writeln('Error reading ${file.path}: $e');
+      }
+    }
+
+    return used;
+  }
+
+  void _report(Map<String, Set<String>> allTranslations, Set<String> usedKeys) {
+    stderr.writeln('=== Keys Audit ===');
+
+    for (var lang in allTranslations.keys) {
+      final keysInFile = allTranslations[lang]!;
+      final missing = usedKeys.difference(keysInFile);
+      final missingWithVariables = missing.where((key) => key.contains('\$')).toList();
+      final missingWithoutVariables = missing.where((key) => !key.contains('\$')).toList();
+
+      stderr.writeln('\nLanguage: $lang');
+      if (missingWithVariables.isEmpty && missingWithoutVariables.isEmpty) {
+        stderr.writeln('  ✅ all good!');
+      }
+
+      if (missingWithoutVariables.isNotEmpty) {
+        stderr.writeln('  🔴 Missing (${missingWithoutVariables.length}):');
+        for (var key in missingWithoutVariables) {
+          stderr.writeln('    – $key');
+        }
+
+        stderr.writeln('\n');
+      }
+
+      if (missingWithVariables.isNotEmpty) {
+        stderr.writeln('  🟡 Missing with variables (${missingWithVariables.length}):');
+        stderr.writeln('    These keys may not be missing as they contain variables that cannot be verified.');
+        for (var key in missingWithVariables) {
+          stderr.writeln('    – $key');
+        }
+      }
+    }
+  }
+}

bin/generate.dart

@@ -175,6 +175,8 @@ Future _writeKeys(StringBuffer classBuilder, List<FileSystemEntity> files,
   var file = '''
 // DO NOT EDIT. This is code generated via package:easy_localization/generate.dart
 
+// ignore_for_file: constant_identifier_names
+
 abstract class  LocaleKeys {
 ''';
 
@@ -234,7 +236,7 @@ Future _writeJson(
   var gFile = '''
 // DO NOT EDIT. This is code generated via package:easy_localization/generate.dart
 
-// ignore_for_file: prefer_single_quotes, avoid_renaming_method_parameters
+// ignore_for_file: prefer_single_quotes, avoid_renaming_method_parameters, constant_identifier_names
 
 import 'dart:ui';
 
@@ -255,13 +257,13 @@ class CodegenLoader extends AssetLoader{
   for (var file in files) {
     final localeName =
         path.basename(file.path).replaceFirst('.json', '').replaceAll('-', '_');
-    listLocales.add('"$localeName": $localeName');
+    listLocales.add('"$localeName": _$localeName');
     final fileData = File(file.path);
 
     Map<String, dynamic>? data = json.decode(await fileData.readAsString());
 
     final mapString = const JsonEncoder.withIndent('  ').convert(data);
-    gFile += 'static const Map<String,dynamic> $localeName = $mapString;\n';
+    gFile += 'static const Map<String,dynamic> _$localeName = $mapString;\n';
   }
 
   gFile +=

i18n/en-US.json

@@ -1,5 +1,5 @@
 {
-  "test": "test",
+  "test": "test_en-US",
   "day": {
     "zero": "{} days",
     "one": "{} day",

i18n/en.json

@@ -1,5 +1,5 @@
 {
-  "test": "test",
+  "test": "test_en",
   "day": {
     "zero": "{} days",
     "one": "{} day",

lib/src/easy_localization_app.dart

@@ -6,7 +6,6 @@ import 'package:easy_logger/easy_logger.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_localizations/flutter_localizations.dart';
 
-import 'asset_loader.dart';
 import 'localization.dart';
 
 part 'utils.dart';
@@ -230,6 +229,7 @@ class _EasyLocalizationProvider extends InheritedWidget {
   final EasyLocalizationController _localeState;
   final Locale? currentLocale;
   final _EasyLocalizationDelegate delegate;
+  final bool _translationsLoaded;
 
   /// {@macro flutter.widgets.widgetsApp.localizationsDelegates}
   ///
@@ -256,6 +256,7 @@ class _EasyLocalizationProvider extends InheritedWidget {
   _EasyLocalizationProvider(this.parent, this._localeState,
       {Key? key, required this.delegate})
       : currentLocale = _localeState.locale,
+        _translationsLoaded = _localeState.translations != null,
         super(key: key, child: parent.child) {
     EasyLocalization.logger.debug('Init provider');
   }
@@ -291,7 +292,8 @@ class _EasyLocalizationProvider extends InheritedWidget {
 
   @override
   bool updateShouldNotify(_EasyLocalizationProvider oldWidget) {
-    return oldWidget.currentLocale != locale;
+    return oldWidget.currentLocale != locale
+        || oldWidget._translationsLoaded != _translationsLoaded;
   }
 
   static _EasyLocalizationProvider? of(BuildContext context) =>

lib/src/easy_localization_controller.dart

@@ -72,14 +72,29 @@ class EasyLocalizationController extends ChangeNotifier {
   }) {
     final selectedLocale = supportedLocales.firstWhere(
       (locale) => locale.supports(deviceLocale),
-      orElse: () => _getFallbackLocale(supportedLocales, fallbackLocale),
+      orElse: () => _getFallbackLocale(
+        supportedLocales,
+        fallbackLocale,
+        deviceLocale: deviceLocale,
+      ),
     );
     return selectedLocale;
   }
 
   //Get fallback Locale
   static Locale _getFallbackLocale(
-      List<Locale> supportedLocales, Locale? fallbackLocale) {
+      List<Locale> supportedLocales, Locale? fallbackLocale,
+      {final Locale? deviceLocale}) {
+    if (deviceLocale != null) {
+      // a locale that matches the language code of the device locale is
+      // preferred over the fallback locale
+      final deviceLanguage = deviceLocale.languageCode;
+      for (Locale locale in supportedLocales) {
+        if (locale.languageCode == deviceLanguage) {
+          return locale;
+        }
+      }
+    }
     //If fallbackLocale not set then return first from supportedLocales
     if (fallbackLocale != null) {
       return fallbackLocale;
@@ -109,6 +124,7 @@ class EasyLocalizationController extends ChangeNotifier {
         }
         _fallbackTranslations = Translations(data);
       }
+      notifyListeners();
     } on FlutterError catch (e) {
       onLoadError(e);
     } catch (e) {

lib/src/public.dart

@@ -45,9 +45,12 @@ String tr(
           .tr(key, args: args, namedArgs: namedArgs, gender: gender);
 }
 
-bool trExists(String key) {
-  return Localization.instance
-      .exists(key);
+bool trExists(String key, {BuildContext? context}) {
+  return context != null
+      ? Localization.of(context)!
+	      .exists(key)
+      : Localization.instance
+	      .exists(key);
 }
 
 /// {@template plural}