Feature/display translations in documentation comments (#52)

Adds optional to generate comments with localization details.

README.md

@@ -49,6 +49,8 @@ flappy_translator:
   expose_get_string: false
   expose_loca_strings: false
   expose_locale_maps: false
+  generate_comments: false
+  comment_languages: []
 ```
 
 | Setting                 | Default | Description                                                                        |
@@ -65,6 +67,8 @@ flappy_translator:
 | expose_get_string       | false   | The default value for whether a getString method should be exposed.                |
 | expose_loca_strings     | false   | The default value for whether a locaStrings getter should be exposed.              |
 | expose_locale_maps      | false   | The default value for whether a localeMaps getter should be exposed.               |
+| generate_comments       | false   | Whether documentation comments should be used to display translations.             |
+| comment_languages       | []      | Languages that are displayed in the comments. Empty -> All languages are used.     |
 
 ### Run package
 

bin/flappy_translator.dart

@@ -29,6 +29,10 @@ void main() {
     exposeGetString: settings[_YamlArguments.exposeGetString],
     exposeLocaStrings: settings[_YamlArguments.exposeLocaStrings],
     exposeLocaleMaps: settings[_YamlArguments.exposeLocaleMaps],
+    generateComments: settings[_YamlArguments.generateComments],
+    commentLanguages: (settings[_YamlArguments.commentLanguages] as YamlList?)
+        ?.map<String>((node) => node.toString())
+        .toList(),
   );
 }
 
@@ -52,6 +56,8 @@ class _YamlArguments {
   static const exposeGetString = 'expose_get_string';
   static const exposeLocaStrings = 'expose_loca_strings';
   static const exposeLocaleMaps = 'expose_locale_maps';
+  static const generateComments = 'generate_comments';
+  static const commentLanguages = 'comment_languages';
 }
 
 /// Returns configuration settings for flappy_translator from pubspec.yaml

example/pubspec.lock

@@ -42,7 +42,7 @@ packages:
       name: characters
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.1.0"
+    version: "1.2.0"
   charcode:
     dependency: transitive
     description:
@@ -158,13 +158,20 @@ packages:
       url: "https://pub.dartlang.org"
     source: hosted
     version: "0.17.0"
+  material_color_utilities:
+    dependency: transitive
+    description:
+      name: material_color_utilities
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "0.1.3"
   meta:
     dependency: transitive
     description:
       name: meta
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.3.0"
+    version: "1.7.0"
   package_config:
     dependency: transitive
     description:
@@ -239,7 +246,7 @@ packages:
       name: vector_math
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "2.1.0"
+    version: "2.1.1"
   watcher:
     dependency: transitive
     description:
@@ -262,5 +269,5 @@ packages:
     source: hosted
     version: "3.1.0"
 sdks:
-  dart: ">=2.12.0 <3.0.0"
+  dart: ">=2.14.0 <3.0.0"
   flutter: ">=2.0.0"

example/pubspec.yaml

@@ -31,6 +31,9 @@ flappy_translator:
   expose_get_string: false
   expose_loca_strings: false
   expose_locale_maps: false
+  generate_comments: false
+  comment_languages: []
+
 
 flutter:
   uses-material-design: true

lib/src/configs/default_settings.dart

@@ -34,4 +34,10 @@ class DefaultSettings {
 
   /// The default value for whether a localeMaps getter should be exposed
   static const exposeLocaleMaps = false;
+
+  /// The default value for whether comments containing the translation should be included in the generated code
+  static const generateComments = false;
+
+  /// The default value for which languages to use in the generated comments. Defaults to all languages.
+  static const commentLanguages = <String>[];
 }

lib/src/extensions/list_extensions.dart

@@ -0,0 +1,17 @@
+extension ListExtensions<E> on List<E> {
+  /// Maps a list of elements to a list of elements of another type.
+  ///
+  /// The [predicate] filters elements that are passed to the [transform] function.
+  /// This does not change the order or index of the elements.
+  /// The [transform] function is called for each element in the list with its respective index and maps it to a new element.
+  List<T> mapIndexedWhere<T>(T Function(int index, E element) transform,
+      [bool Function(int index, E element)? predicate]) {
+    final result = <T>[];
+    for (var i = 0; i < length; i++) {
+      if (predicate != null ? predicate(i, this[i]) : true) {
+        result.add(transform(i, this[i]));
+      }
+    }
+    return result;
+  }
+}

lib/src/services/code_generation/code_generator.dart

@@ -3,6 +3,7 @@ import 'package:dart_style/dart_style.dart';
 import '../../configs/constants.dart' as constants;
 import '../../configs/default_settings.dart';
 import '../../utils/flappy_logger.dart';
+import '../../extensions/list_extensions.dart';
 import 'template.dart';
 
 /// A service which generates I18n class and delegate using string concatenation
@@ -11,6 +12,7 @@ class CodeGenerator {
   final String _quoteString;
   final bool replaceNoBreakSpaces;
   final _parametersRegex = RegExp(r'(\%[[0-9a-zA-Z]+]*\$(d|s))');
+  final List<String> _commentLanguages = [];
 
   late String _template;
   late List<Map<String, String>> _maps;
@@ -44,6 +46,16 @@ class CodeGenerator {
     _fields = '';
   }
 
+  void enableCommentGeneration([List<String> commentLanguages = const []]) {
+    if (commentLanguages.isEmpty) {
+      _commentLanguages.addAll(_supportedLanguages);
+    } else {
+      // make sure to not use languages that are not supported
+      _commentLanguages.addAll(_supportedLanguages
+          .where((supportedLang) => commentLanguages.contains(supportedLang)));
+    }
+  }
+
   void setSupportedLanguages(List<String> supportedLanguages) {
     _supportedLanguages = supportedLanguages;
 
@@ -71,7 +83,10 @@ class CodeGenerator {
   }
 
   void addField(String key, String defaultWord, List<String> words) {
-    var result = '';
+    var result = _supportedLanguages
+        .mapIndexedWhere((i, lang) => '/// * $lang: ${words[i]} \n',
+            (_, lang) => _commentLanguages.contains(lang))
+        .join('');
     final getTextString = '_getText($_quoteString$key$_quoteString)';
     final hasParameters = _parametersRegex.hasMatch(defaultWord);
     if (hasParameters) {
@@ -83,7 +98,7 @@ class CodeGenerator {
             'required $parameterType ${_getParameterNameFromPlaceholder(match.group(0)!)}, ';
       }
 
-      result =
+      result +=
           (!dependOnContext ? 'static ' : '') + 'String $key({$parameters}) =>';
       result += getTextString;
 
@@ -97,7 +112,7 @@ class CodeGenerator {
 
       result += ';\n\n';
     } else {
-      result = (!dependOnContext ? 'static ' : '') +
+      result += (!dependOnContext ? 'static ' : '') +
           'String get $key => $getTextString;\n\n';
     }
 

lib/src/services/flappy_translator.dart

@@ -23,6 +23,8 @@ class FlappyTranslator {
     bool? exposeGetString,
     bool? exposeLocaStrings,
     bool? exposeLocaleMaps,
+    bool? generateComments,
+    List<String>? commentLanguages,
   }) {
     final file = File(inputFilePath);
     Validator.validateFile(file);
@@ -42,6 +44,8 @@ class FlappyTranslator {
     exposeGetString ??= DefaultSettings.exposeGetString;
     exposeLocaStrings ??= DefaultSettings.exposeLocaStrings;
     exposeLocaleMaps ??= DefaultSettings.exposeLocaleMaps;
+    generateComments ??= DefaultSettings.generateComments;
+    commentLanguages ??= DefaultSettings.commentLanguages;
 
     final codeGenerator = CodeGenerator(
       className: className,
@@ -64,6 +68,9 @@ class FlappyTranslator {
     final supportedLanguages = parser.supportedLanguages;
     Validator.validateSupportedLanguages(supportedLanguages);
     codeGenerator.setSupportedLanguages(supportedLanguages);
+    if (generateComments) {
+      codeGenerator.enableCommentGeneration(commentLanguages);
+    }
     FlappyLogger.logProgress('Locales $supportedLanguages determined.');
 
     final localizationsTable = parser.localizationsTable;

test/extensions/list_extensions_test.dart

@@ -0,0 +1,26 @@
+import 'package:flappy_translator/src/extensions/list_extensions.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('mapIndexedWhere', () {
+    expect(
+        ['a', 'b', 'c'].mapIndexedWhere((i, e) => e).toList(), ['a', 'b', 'c']);
+    expect(['a', 'b', 'c'].mapIndexedWhere((i, e) => i).toList(), [0, 1, 2]);
+    // with filter
+    expect(
+        ['aasd', 'bas', 'cas', 'a', 'asdas']
+            .mapIndexedWhere((i, e) => e.length)
+            .toList(),
+        [4, 3, 3, 1, 5]);
+    expect(
+        ['aasd', 'bas', 'cas', 'a', 'asdas']
+            .mapIndexedWhere((i, e) => e, (i, e) => e.length != 3)
+            .toList(),
+        ['aasd', 'a', 'asdas']);
+    expect(
+        ['123456', '123', '123', '12345678', '123456']
+            .mapIndexedWhere((i, e) => e[i], (i, e) => e.length != 3)
+            .toList(),
+        ['1', '4', '5']);
+  });
+}