Merge branch 'feat/add-linked-files' into develop

Author: JavedNicolas

README.md

@@ -411,8 +411,6 @@ print('example.emptyNameError'.tr()); //Output: Please fill in your full name
 
 ### 🔥 Linked files:
 
-> ⚠ This is only available for the default asset loader (on Json Files).
-
 You can split translations for a single locale into multiple files by using linked files. This helps keep your JSON clean and maintainable.
 
 To link an external file, set the key’s value to a path prefixed with `:/`, relative to your translations directory. For example, with default path `assets/translations` and locale `en-US`:
@@ -435,7 +433,7 @@ assets
         └── notifications.json  
 ```
 
-Each linked file must contain a valid JSON object of translation keys.  
+Each linked file must contain a valid object of translation keys (of the file type you are using [Other file types](#-loading-translations-from-other-resources)).  
 
 Don't forget to add your linked files (or linked files folder, here assets/translations/en-US/), to your pubspec.yaml : [See installation](#-installation).
 

bin/audit/audit_command.dart

@@ -1,10 +1,11 @@
 import 'dart:convert';
 import 'dart:io';
-
+import 'package:easy_localization/src/linked_file_resolver.dart';
 import 'package:path/path.dart';
+import 'package:easy_localization/src/file_loaders/io_file_loader.dart';
 
 class AuditCommand {
-  void run({required String transDir, required String srcDir}) {
+  void run({required String transDir, required String srcDir}) async {
     try {
       final translationDir = Directory(transDir);
       final sourceDir = Directory(srcDir);
@@ -19,7 +20,7 @@ class AuditCommand {
         return;
       }
 
-      final allTranslations = _loadTranslations(translationDir);
+      final allTranslations = await _loadTranslations(translationDir);
       final usedKeys = _scanSourceForKeys(sourceDir);
 
       _report(allTranslations, usedKeys);
@@ -31,15 +32,30 @@ class AuditCommand {
   /// 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) {
+  /// Also handles linked translation files (those containing ':/file.json' references)
+  Future<Map<String, Set<String>>> _loadTranslations(Directory translationsDir) async {
     final result = <String, Set<String>>{};
+    const IOFileLoader fileLoader = IOFileLoader();
+    const LinkedFileResolver linkedFileResolver = JsonLinkedFileResolver(fileLoader: fileLoader);
+
     for (var file in translationsDir.listSync().whereType<File>()) {
       if (!file.path.endsWith('.json')) continue;
 
       try {
-        final langCode = basenameWithoutExtension(file.path);
+        final local = basenameWithoutExtension(file.path);
+        final langCode = local.split('-').first;
+        final hasCountryCode = local.split('-').length > 1;
+        final countryCode = hasCountryCode ? local.split('-').last : null;
         final jsonMap = json.decode(file.readAsStringSync()) as Map<String, dynamic>;
-        result[langCode] = _flatten(jsonMap);
+
+        // Process linked files if present using the shared resolver
+        final resolvedJson = await linkedFileResolver.resolveLinkedFiles(
+          basePath: translationsDir.path,
+          languageCode: langCode,
+          baseJson: jsonMap,
+          countryCode: countryCode,
+        );
+        result[local] = _flatten(resolvedJson);
       } catch (e) {
         stderr.writeln('Error reading ${file.path}: $e');
       }

debug_linked.dart

@@ -4,10 +4,11 @@
 
 import 'dart:ui';
 
-import 'package:easy_localization/easy_localization.dart' show AssetLoader;
+import 'package:easy_localization/easy_localization.dart'
+    show AssetLoader, JsonLinkedFileResolver, RootBundleFileLoader;
 
 class CodegenLoader extends AssetLoader {
-  const CodegenLoader();
+  const CodegenLoader() : super(linkedFileResolver: const JsonLinkedFileResolver(fileLoader: RootBundleFileLoader()));
 
   @override
   Future<Map<String, dynamic>> load(String fullPath, Locale locale) {
@@ -20,11 +21,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} مكتوبة باللغة {lang}",
     "clickMe": "إضغط هنا",
     "profile": {
-      "reset_password": {
-        "label": "اعادة تعين كلمة السر",
-        "username": "المستخدم",
-        "password": "كلمة السر"
-      }
+      "reset_password": {"label": "اعادة تعين كلمة السر", "username": "المستخدم", "password": "كلمة السر"}
     },
     "clicked": {
       "zero": "لم تنقر بعد!",
@@ -55,11 +52,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} مكتوبة باللغة {lang}",
     "clickMe": "إضغط هنا",
     "profile": {
-      "reset_password": {
-        "label": "اعادة تعين كلمة السر",
-        "username": "المستخدم",
-        "password": "كلمة السر"
-      }
+      "reset_password": {"label": "اعادة تعين كلمة السر", "username": "المستخدم", "password": "كلمة السر"}
     },
     "clicked": {
       "zero": "لم تنقر بعد!",
@@ -90,11 +83,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} ist in {lang} geschrieben",
     "clickMe": "Click mich",
     "profile": {
-      "reset_password": {
-        "label": "Password zurücksetzten",
-        "username": "Name",
-        "password": "Password"
-      }
+      "reset_password": {"label": "Password zurücksetzten", "username": "Name", "password": "Password"}
     },
     "clicked": {
       "zero": "Du hast {} mal geklickt",
@@ -125,11 +114,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} ist in {lang} geschrieben",
     "clickMe": "Click mich",
     "profile": {
-      "reset_password": {
-        "label": "Password zurücksetzten",
-        "username": "Name",
-        "password": "Password"
-      }
+      "reset_password": {"label": "Password zurücksetzten", "username": "Name", "password": "Password"}
     },
     "clicked": {
       "zero": "Du hast {} mal geklickt",
@@ -160,11 +145,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} are written in the {lang} language",
     "clickMe": "Click me",
     "profile": {
-      "reset_password": {
-        "label": "Reset Password",
-        "username": "Username",
-        "password": "password"
-      }
+      "reset_password": {"label": "Reset Password", "username": "Username", "password": "password"}
     },
     "clicked": {
       "zero": "You clicked {} times!",
@@ -195,11 +176,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} are written in the {lang} language",
     "clickMe": "Click me",
     "profile": {
-      "reset_password": {
-        "label": "Reset Password",
-        "username": "Username",
-        "password": "password"
-      }
+      "reset_password": {"label": "Reset Password", "username": "Username", "password": "password"}
     },
     "clicked": {
       "zero": "You clicked {} times!",
@@ -230,11 +207,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} написан на языке {lang}",
     "clickMe": "Нажми на меня",
     "profile": {
-      "reset_password": {
-        "label": "Сбросить пароль",
-        "username": "Логин",
-        "password": "Пароль"
-      }
+      "reset_password": {"label": "Сбросить пароль", "username": "Логин", "password": "Пароль"}
     },
     "clicked": {
       "zero": "Ты кликнул {} раз!",
@@ -255,10 +228,7 @@ class CodegenLoader extends AssetLoader {
     "gender": {
       "male": "Привет мужык ;) ",
       "female": "Привет девчуля :)",
-      "with_arg": {
-        "male": "Привет мужык ;) {}",
-        "female": "Привет девчуля :) {}"
-      }
+      "with_arg": {"male": "Привет мужык ;) {}", "female": "Привет девчуля :) {}"}
     },
     "reset_locale": "Сбросить язык"
   };
@@ -268,11 +238,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} написан на языке {lang}",
     "clickMe": "Нажми на меня",
     "profile": {
-      "reset_password": {
-        "label": "Сбросить пароль",
-        "username": "Логин",
-        "password": "Пароль"
-      }
+      "reset_password": {"label": "Сбросить пароль", "username": "Логин", "password": "Пароль"}
     },
     "clicked": {
       "zero": "Ты кликнул {} раз!",
@@ -293,10 +259,7 @@ class CodegenLoader extends AssetLoader {
     "gender": {
       "male": "Привет мужык ;) ",
       "female": "Привет девчуля :)",
-      "with_arg": {
-        "male": "Привет мужык ;) {}",
-        "female": "Привет девчуля :) {}"
-      }
+      "with_arg": {"male": "Привет мужык ;) {}", "female": "Привет девчуля :) {}"}
     },
     "reset_locale": "Сбросить язык"
   };

example/lib/generated/codegen_loader.g.dart

@@ -4,4 +4,6 @@ export 'package:easy_localization/src/easy_localization_app.dart';
 export 'package:easy_localization/src/asset_loader.dart';
 export 'package:easy_localization/src/public.dart';
 export 'package:easy_localization/src/public_ext.dart';
+export 'package:easy_localization/src/linked_file_resolver.dart';
+export 'package:easy_localization/src/file_loaders/root_bundle_file_loader.dart';
 export 'package:intl/intl.dart';

lib/easy_localization.dart

@@ -1,7 +1,7 @@
 import 'dart:convert';
 import 'dart:ui';
-
 import 'package:easy_localization/easy_localization.dart';
+import 'package:easy_localization/src/file_loaders/io_file_loader.dart';
 import 'package:flutter/services.dart';
 
 /// abstract class used to building your Custom AssetLoader
@@ -16,97 +16,43 @@ import 'package:flutter/services.dart';
 ///}
 /// ```
 abstract class AssetLoader {
-  const AssetLoader();
+  // Place inside class RootBundleAssetLoader
+  final LinkedFileResolver linkedFileResolver;
+
+  const AssetLoader({required this.linkedFileResolver});
+
   Future<Map<String, dynamic>?> load(String path, Locale locale);
 }
 
 ///
 /// default used is RootBundleAssetLoader which uses flutter's assetloader
 ///
 class RootBundleAssetLoader extends AssetLoader {
-  // Place inside class RootBundleAssetLoader
-  static const int _maxLinkedDepth = 32;
+  const RootBundleAssetLoader({LinkedFileResolver? linkedFileResolver})
+      : super(
+            linkedFileResolver: linkedFileResolver ?? const JsonLinkedFileResolver(fileLoader: RootBundleFileLoader()));
 
-  const RootBundleAssetLoader();
+  factory RootBundleAssetLoader.fromIOFile() {
+    return const RootBundleAssetLoader(
+      linkedFileResolver: JsonLinkedFileResolver(fileLoader: IOFileLoader()),
+    );
+  }
 
   String getLocalePath(String basePath, Locale locale) {
     return '$basePath/${locale.toStringWithSeparator(separator: "-")}.json';
   }
 
-  String _getLinkedLocalePath(String basePath, String filePath, Locale locale) {
-    return '$basePath/${locale.toStringWithSeparator(separator: "-")}/$filePath';
-  }
-
-  Future<Map<String, dynamic>> _getLinkedTranslationFileDataFromBaseJson(
-    String basePath,
-    Locale locale,
-    Map<String, dynamic> baseJson, {
-    required Set<String> visited,
-    int depth = 0,
-  }) async {
-    if (depth > _maxLinkedDepth) {
-      throw StateError('Maximum linked files depth ($_maxLinkedDepth) exceeded for $locale at $basePath.');
-    }
-
-    final Map<String, dynamic> fullJson = Map<String, dynamic>.from(baseJson);
-
-    for (final entry in baseJson.entries) {
-      final key = entry.key;
-      var value = entry.value;
-
-      if (value is String && value.startsWith(':/')) {
-        final rawPath = value.substring(2).trim();
-        final linkedAssetPath = _getLinkedLocalePath(basePath, rawPath, locale);
-
-        if (visited.contains(linkedAssetPath)) {
-          throw StateError('Cyclic linked files detected at "$linkedAssetPath" (key: "$key").');
-        }
-
-        final Map<String, dynamic> linkedJson =
-            json.decode(await rootBundle.loadString(linkedAssetPath)) as Map<String, dynamic>;
-
-        visited.add(linkedAssetPath);
-        try {
-          final resolved = await _getLinkedTranslationFileDataFromBaseJson(
-            basePath,
-            locale,
-            linkedJson,
-            visited: visited,
-            depth: depth + 1,
-          );
-          fullJson[key] = resolved;
-        } catch (e) {
-          throw StateError(
-            'Error resolving linked file "$linkedAssetPath" for key "$key": $e',
-          );
-        }
-      }
-
-      if (value is Map<String, dynamic>) {
-        fullJson[key] = await _getLinkedTranslationFileDataFromBaseJson(
-          basePath,
-          locale,
-          value,
-          visited: visited,
-          depth: depth + 1,
-        );
-      }
-    }
-
-    return fullJson;
-  }
-
   @override
   Future<Map<String, dynamic>?> load(String path, Locale locale) async {
     var localePath = getLocalePath(path, locale);
     EasyLocalization.logger.debug('Load asset from $path');
 
-    Map<String, dynamic> baseJson = json.decode(await rootBundle.loadString(localePath));
-    return await _getLinkedTranslationFileDataFromBaseJson(
-      path,
-      locale,
-      baseJson,
-      visited: <String>{},
+    Map<String, dynamic> baseJson = json.decode(await linkedFileResolver.fileLoader.loadString(localePath));
+    return await linkedFileResolver.resolveLinkedFiles(
+      basePath: path,
+      languageCode: locale.languageCode,
+      countryCode: locale.countryCode,
+      baseJson: baseJson,
     );
   }
 }