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

.github/workflows/playwright.yml

@@ -0,0 +1,27 @@
+name: Playwright Tests
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+jobs:
+  test:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: lts/*
+    - name: Install dependencies
+      run: npm ci
+    - name: Install Playwright Browsers
+      run: npx playwright install --with-deps
+    - name: Run Playwright tests
+      run: npx playwright test
+    - uses: actions/upload-artifact@v4
+      if: ${{ !cancelled() }}
+      with:
+        name: playwright-report
+        path: playwright-report/
+        retention-days: 30

.gitignore

@@ -625,7 +625,5 @@ coverage/lcov.info
 pubspec.lock
 .idea/codeStyles/Project.xml
 
-example/ios/Runner.xcodeproj/project.pbxproj
-
 # Allow
 !/bin/

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+### [4.0.0-dev]
+
+- **BREAKING**: Moved `path` and `supportedLocales` into `AssetLoader` instead of `EasyLocalization` widget
+- **BREAKING**: `AssetLoader.load()` signature changed from `load(String path, Locale locale)` to `load({Locale? locale})`
+- **BREAKING**: `ensureInitialized()` now takes `assetLoader` and optional `storage` instead of no params
+- **BREAKING**: Removed `useFallbackTranslationsForEmptyResources` (v4 always falls back for empty keys; use `useFallbackTranslations` to control the behavior at the feature level)
+- **BREAKING**: Removed `ignorePluralRules` (plural rules are now always applied; override by returning a single form in your translations if needed)
+- **BREAKING**: Removed `extraAssetLoaders` (compose multiple sources in a custom `AssetLoader` instead)
+- Added `IEasyLocalizationStorage` interface with `SharedPreferencesStorage` and `InMemoryStorage` implementations
+- Added `CachedAssetLoader` and `OptimizedAssetLoader` with built-in caching
+- Fixed fallback translations bug: base-locale `null` entries no longer overwrite real fallback values
+- Fixed `useOnlyLangCode` with country-code locales (static `_locale` race condition)
+- Fixed `ListTile` ink-splash warnings in example app
+- Added `EasyLocalizationCompat` extension with `withConfig()` and `migrateAssetLoader()` helpers for v3→v4 migration
+- Updated README and example for v4 API
+
 ### [3.0.3]
 
 - replace log() with stdout.writeln()
@@ -60,6 +76,7 @@
 ```dart
 context.locale = locale;
 ```
+
 :information_source: No breaking changes, you can use old the static method `EasyLocalization.of(context)`
 
 ### [2.2.2]
@@ -85,6 +102,7 @@ context.locale = locale;
   ```
 
 - Added support Custom assets loaders [Easy Localization Loader](https://github.com/aissat/easy_localization_loader).
+
   - Added support CSV files.
 
     ```dart
@@ -134,7 +152,7 @@ context.locale = locale;
 
     ```json
     {
-      "msg_named": "{} مكتوبة باللغة {lang}",
+      "msg_named": "{} مكتوبة باللغة {lang}"
     }
     ```
 
@@ -153,7 +171,7 @@ context.locale = locale;
     ```
 
   - generate the json Loader in a dart class
-  
+
     ```cmd
     flutter pub run easy_localization:generate
     ```
@@ -198,7 +216,7 @@ this version came with many updates, here are the main ones:
 - Hiding `EasyLocalizationProvider`
 - refactor and update approach localization for more details see [example:](https://github.com/aissat/easy_localization/tree/master/example)
 
-  ``` dart
+  ```dart
   // Now V2.0.0
   runApp(EasyLocalization(
     child: MyApp(),
@@ -221,18 +239,18 @@ this version came with many updates, here are the main ones:
 
 - added Support for context
 
-    ``` dart
-    tr("key", context: context),
-    plural("key", 1 , context: context),
-    ```
+  ```dart
+  tr("key", context: context),
+  plural("key", 1 , context: context),
+  ```
 
 ## [1.4.1]
 
 - optimized and clean code
 - fixed many issues
 - added extension for Strings
 
-  ``` dart
+  ```dart
   // after 1.4.1
   Text('title'.tr()),
   Text('switch'.tr( gender: _gender ? "female" : "male")),
@@ -243,14 +261,14 @@ this version came with many updates, here are the main ones:
 
 - refactor code changed call ~~`AppLocalizations.of(context).tr()`~~ ~~`AppLocalizations.of(context).plural()`~~ to `tr()` and `plural()`
 
-  ``` dart
+  ```dart
   // after 1.4.0
   Text(
     tr('switch', gender: _gender ? "female" : "male"),
   ),
   ```
 
-  ``` dart
+  ```dart
   // before 1.4.0
   Text(
     AppLocalizations.of(context).tr('switch', gender: _gender ? "female" : "male"),
@@ -259,75 +277,77 @@ this version came with many updates, here are the main ones:
 
 - added Flutter extension for Text widget
 
-  ``` dart
+  ```dart
   // after 1.4.0
   Text('switch').tr( gender: _gender ? "female" : "male"),
   Text('counter').plural(counter),
   ```
 
 ## [1.3.5]
 
-- merge  `gender()`  and `tr()`  .
+- merge `gender()` and `tr()` .
 
-  ``` json
+  ```json
   {
-    "gender":{
+    "gender": {
       "male": "Hi man ;)",
       "female": "Hello girl :)"
     }
   }
   ```
 
-  ``` dart
+  ```dart
   new Text(
     AppLocalizations.of(context).tr('switch', gender: _gender ? "female" : "male"),
   ),
   ```
 
 - use parameters `args` for gender.
-  
-  ``` json
+
+  ```json
   {
-    "gender":{
+    "gender": {
       "male": "Hi man ;) {}",
       "female": "Hello girl :) {}"
     }
   }
   ```
 
-  ``` dart
+  ```dart
   new Text(
     AppLocalizations.of(context).tr('switch', args:["Naama"] gender: _gender ? "female" : "male"),
   ),
+  ```
 
 ## [1.3.4]
 
-- adeed Gender [female,male]  `gender()`  .
+- adeed Gender [female,male] `gender()` .
 
-  ``` json
+  ```json
   {
-    "gender":{
+    "gender": {
       "male": "Hi man ;)",
       "female": "Hello girl :)"
     }
   }
   ```
 
-  ``` dart
+  ```dart
   new Text(
     AppLocalizations.of(context).gender('switch', _gender ? "female" : "male"),
   ),
   `
+  ```
 
 ## [1.3.3+1]
 
-- updated  `plural()` thanks [shushper](https://github.com/shushper) .
+- updated `plural()` thanks [shushper](https://github.com/shushper) .
 
-  ``` json
+  ```json
   {
     "text": {
       "day": {
-        "zero":"{} дней",
+        "zero": "{} дней",
         "one": "{} день",
         "two": "{} дня",
         "few": "{} дня",
@@ -340,28 +360,27 @@ this version came with many updates, here are the main ones:
 
 ## [1.3.3]
 
-- removed  `data.savedLocale` .
+- removed `data.savedLocale` .
 - optimized and clean code
 - fixed many issues
 
 ## [1.3.2]
 
 - `plural()` added property resolver for nested key translations
 
-  ``` json
+  ```json
   {
-  "text": {
-    "day": {
-      "zero": "day",
-      "one": "day",
-      "other": "days"
+    "text": {
+      "day": {
+        "zero": "day",
+        "one": "day",
+        "other": "days"
       }
     }
   }
-
   ```
 
-  ``` dart
+  ```dart
   new Text(
     AppLocalizations.of(context).plural("text.day", 2),
   ),
@@ -388,7 +407,7 @@ this version came with many updates, here are the main ones:
 - Added property resolver for nested key translations
 - return translate key if the element or path not exist
 
-``` json
+```json
 {
   "title": "Hello",
   "msg": "Hello {} in the {} world ",