Merge pull request #770 from JavedNicolas/develop

[Feature] Linked Files

Author: aissat

README.md

@@ -73,6 +73,8 @@ flutter:
     - assets/translations/
 ```
 
+
+
 ### 🔌 Loading translations from other resources
 
 You can use JSON,CSV,HTTP,XML,Yaml files, etc.
@@ -407,6 +409,34 @@ Output:
 print('example.emptyNameError'.tr()); //Output: Please fill in your full name
 ```
 
+### 🔥 Linked 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`:
+
+```json
+{
+  "errors": ":/errors.json",
+  "validation": ":/validation.json",
+  "notifications": ":/notifications.json"
+}
+```
+
+At runtime, Easy Localization will load:
+```
+assets
+└── translations
+    └── en-US
+        ├── errors.json 
+        ├── validation.json  
+        └── notifications.json  
+```
+
+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).
+
 ### 🔥 Reset locale `resetLocale()`
 
 Reset locale to device locale

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}) {
+  Future<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,14 @@
 
 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()),
+            fileLoader: const RootBundleFileLoader());
 
   @override
   Future<Map<String, dynamic>> load(String fullPath, Locale locale) {
@@ -20,11 +24,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} مكتوبة باللغة {lang}",
     "clickMe": "إضغط هنا",
     "profile": {
-      "reset_password": {
-        "label": "اعادة تعين كلمة السر",
-        "username": "المستخدم",
-        "password": "كلمة السر"
-      }
+      "reset_password": {"label": "اعادة تعين كلمة السر", "username": "المستخدم", "password": "كلمة السر"}
     },
     "clicked": {
       "zero": "لم تنقر بعد!",
@@ -55,11 +55,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} مكتوبة باللغة {lang}",
     "clickMe": "إضغط هنا",
     "profile": {
-      "reset_password": {
-        "label": "اعادة تعين كلمة السر",
-        "username": "المستخدم",
-        "password": "كلمة السر"
-      }
+      "reset_password": {"label": "اعادة تعين كلمة السر", "username": "المستخدم", "password": "كلمة السر"}
     },
     "clicked": {
       "zero": "لم تنقر بعد!",
@@ -90,11 +86,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 +117,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 +148,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 +179,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 +210,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} написан на языке {lang}",
     "clickMe": "Нажми на меня",
     "profile": {
-      "reset_password": {
-        "label": "Сбросить пароль",
-        "username": "Логин",
-        "password": "Пароль"
-      }
+      "reset_password": {"label": "Сбросить пароль", "username": "Логин", "password": "Пароль"}
     },
     "clicked": {
       "zero": "Ты кликнул {} раз!",
@@ -255,10 +231,7 @@ class CodegenLoader extends AssetLoader {
     "gender": {
       "male": "Привет мужык ;) ",
       "female": "Привет девчуля :)",
-      "with_arg": {
-        "male": "Привет мужык ;) {}",
-        "female": "Привет девчуля :) {}"
-      }
+      "with_arg": {"male": "Привет мужык ;) {}", "female": "Привет девчуля :) {}"}
     },
     "reset_locale": "Сбросить язык"
   };
@@ -268,11 +241,7 @@ class CodegenLoader extends AssetLoader {
     "msg_named": "{} написан на языке {lang}",
     "clickMe": "Нажми на меня",
     "profile": {
-      "reset_password": {
-        "label": "Сбросить пароль",
-        "username": "Логин",
-        "password": "Пароль"
-      }
+      "reset_password": {"label": "Сбросить пароль", "username": "Логин", "password": "Пароль"}
     },
     "clicked": {
       "zero": "Ты кликнул {} раз!",
@@ -293,10 +262,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

@@ -0,0 +1,4 @@
+{
+  "test": "cyclic_test",
+  "cycle_start": ":/cycle_file1.json"
+}

i18n/en-cyclic.json

@@ -0,0 +1,4 @@
+{
+  "file1_value": "This is file 1",
+  "link_to_file2": ":/cycle_file2.json"
+}

i18n/en-cyclic/cycle_file1.json

@@ -0,0 +1,4 @@
+{
+  "file2_value": "This is file 2",
+  "link_back_to_file1": ":/cycle_file1.json"
+}

i18n/en-cyclic/cycle_file2.json

@@ -0,0 +1,19 @@
+{
+  "test": "test_linked_en",
+  "hello": "Hello",
+  "app": {
+    "name": "Test App",
+    "errors": ":/errors.json"
+  },
+  "validation": ":/validation.json",
+  "nested": {
+    "module": {
+      "messages": ":/nested/messages.json"
+    }
+  },
+  "multiple": {
+    "errors": ":/multi_errors.json",
+    "validation": ":/multi_validation.json"
+  },
+  "deep_nested": ":/deep/level1.json"
+}

i18n/en-linked.json

@@ -0,0 +1,4 @@
+{
+  "level1_value": "This is level 1",
+  "level2": ":/deep/level2.json"
+}

i18n/en-linked/deep/level1.json

@@ -0,0 +1,4 @@
+{
+  "level2_value": "This is level 2",
+  "final_message": "Deep nesting works!"
+}