[gen_l10n] Add base method code comments for improved discoverability (#69016)

packages/flutter_tools/lib/src/localizations/gen_l10n.dart

@@ -205,16 +205,22 @@ String generateMethod(Message message, AppResourceBundle bundle) {
     .replaceAll('@(message)', generateMessage());
 }
 
-String generateBaseClassMethod(Message message) {
-  final String comment = message.description ?? 'No description provided in @${message.resourceId}';
+String generateBaseClassMethod(Message message, LocaleInfo templateArbLocale) {
+  final String comment = message.description ?? 'No description provided for @${message.resourceId}.';
+  final String templateLocaleTranslationComment = '''
+  /// In $templateArbLocale, this message translates to:
+  /// **${generateString(message.value)}**''';
+
   if (message.placeholders.isNotEmpty) {
     return baseClassMethodTemplate
       .replaceAll('@(comment)', comment)
+      .replaceAll('@(templateLocaleTranslationComment)', templateLocaleTranslationComment)
       .replaceAll('@(name)', message.resourceId)
       .replaceAll('@(parameters)', generateMethodParameters(message).join(', '));
   }
   return baseClassGetterTemplate
     .replaceAll('@(comment)', comment)
+    .replaceAll('@(templateLocaleTranslationComment)', templateLocaleTranslationComment)
     .replaceAll('@(name)', message.resourceId);
 }
 
@@ -993,7 +999,7 @@ class LocalizationsGenerator {
     _generatedLocalizationsFile = fileTemplate
       .replaceAll('@(header)', header)
       .replaceAll('@(class)', className)
-      .replaceAll('@(methods)', _allMessages.map(generateBaseClassMethod).join('\n'))
+      .replaceAll('@(methods)', _allMessages.map((Message message) => generateBaseClassMethod(message, _templateArbLocale)).join('\n'))
       .replaceAll('@(importFile)', '$directory/$outputFileName')
       .replaceAll('@(supportedLocales)', supportedLocalesCode.join(',\n    '))
       .replaceAll('@(supportedLanguageCodes)', supportedLanguageCodes.join(', '))

packages/flutter_tools/lib/src/localizations/gen_l10n_templates.dart

@@ -180,12 +180,16 @@ class @(class) extends @(baseLanguageClassName) {
 ''';
 
 const String baseClassGetterTemplate = '''
-  // @(comment)
+  /// @(comment)
+  ///
+@(templateLocaleTranslationComment)
   String get @(name);
 ''';
 
 const String baseClassMethodTemplate = '''
-  // @(comment)
+  /// @(comment)
+  ///
+@(templateLocaleTranslationComment)
   String @(name)(@(parameters));
 ''';
 

packages/flutter_tools/test/general.shard/generate_localizations_test.dart

@@ -29,18 +29,18 @@ const String singleMessageArbFileString = '''
 {
   "title": "Title",
   "@title": {
-    "description": "Title for the application"
+    "description": "Title for the application."
   }
 }''';
 const String twoMessageArbFileString = '''
 {
   "title": "Title",
   "@title": {
-    "description": "Title for the application"
+    "description": "Title for the application."
   },
   "subtitle": "Subtitle",
   "@subtitle": {
-    "description": "Subtitle for the application"
+    "description": "Subtitle for the application."
   }
 }''';
 const String esArbFileName = 'app_es.arb';
@@ -1071,6 +1071,136 @@ void main() {
   });
 
   group('writeOutputFiles', () {
+    test('message without placeholders - should generate code comment with description and template message translation', () {
+      _standardFlutterDirectoryL10nSetup(fs);
+      final LocalizationsGenerator generator = LocalizationsGenerator(fs);
+      try {
+        generator.initialize(
+          inputPathString: defaultL10nPathString,
+          outputPathString: defaultL10nPathString,
+          templateArbFileName: defaultTemplateArbFileName,
+          outputFileString: defaultOutputFileString,
+          classNameString: defaultClassNameString,
+        );
+        generator.loadResources();
+        generator.writeOutputFiles();
+      } on Exception catch (e) {
+        fail('Generating output files should not fail: $e');
+      }
+
+      final File baseLocalizationsFile = fs.file(
+        fs.path.join(syntheticL10nPackagePath, 'output-localization-file.dart')
+      );
+      expect(baseLocalizationsFile.existsSync(), isTrue);
+
+      final String baseLocalizationsFileContents = fs.file(
+        fs.path.join(syntheticL10nPackagePath, 'output-localization-file.dart')
+      ).readAsStringSync();
+      expect(baseLocalizationsFileContents, contains('/// Title for the application.'));
+      expect(baseLocalizationsFileContents, contains('''
+  /// In en, this message translates to:
+  /// **'Title'**'''));
+    });
+
+    test('template message translation handles newline characters', () {
+      final Directory l10nDirectory = fs.currentDirectory.childDirectory('lib').childDirectory('l10n')
+        ..createSync(recursive: true);
+      l10nDirectory.childFile(defaultTemplateArbFileName)
+        .writeAsStringSync(r'''
+{
+  "title": "Title \n of the application",
+  "@title": {
+    "description": "Title for the application."
+  }
+}''');
+      l10nDirectory.childFile(esArbFileName)
+        .writeAsStringSync(singleEsMessageArbFileString);
+
+
+
+      final LocalizationsGenerator generator = LocalizationsGenerator(fs);
+      try {
+        generator.initialize(
+          inputPathString: defaultL10nPathString,
+          outputPathString: defaultL10nPathString,
+          templateArbFileName: defaultTemplateArbFileName,
+          outputFileString: defaultOutputFileString,
+          classNameString: defaultClassNameString,
+        );
+        generator.loadResources();
+        generator.writeOutputFiles();
+      } on Exception catch (e) {
+        fail('Generating output files should not fail: $e');
+      }
+
+      final File baseLocalizationsFile = fs.file(
+        fs.path.join(syntheticL10nPackagePath, 'output-localization-file.dart')
+      );
+      expect(baseLocalizationsFile.existsSync(), isTrue);
+
+      final String baseLocalizationsFileContents = fs.file(
+        fs.path.join(syntheticL10nPackagePath, 'output-localization-file.dart')
+      ).readAsStringSync();
+      expect(baseLocalizationsFileContents, contains('/// Title for the application.'));
+      expect(baseLocalizationsFileContents, contains(r'''
+  /// In en, this message translates to:
+  /// **'Title \n of the application'**'''));
+    });
+
+    test('message with placeholders - should generate code comment with description and template message translation', () {
+      final Directory l10nDirectory = fs.currentDirectory.childDirectory('lib').childDirectory('l10n')
+        ..createSync(recursive: true);
+      l10nDirectory.childFile(defaultTemplateArbFileName)
+        .writeAsStringSync(r'''
+{
+  "price": "The price of this item is: ${price}",
+  "@price": {
+    "description": "The price of an online shopping cart item.",
+    "placeholders": {
+      "price": {
+        "type": "double",
+        "format": "decimalPattern"
+      }
+    }
+  }
+}''');
+      l10nDirectory.childFile(esArbFileName)
+        .writeAsStringSync(r'''
+{
+  "price": "el precio de este artículo es: ${price}"
+}''');
+
+      final LocalizationsGenerator generator = LocalizationsGenerator(fs);
+      try {
+        generator.initialize(
+          inputPathString: defaultL10nPathString,
+          outputPathString: defaultL10nPathString,
+          templateArbFileName: defaultTemplateArbFileName,
+          outputFileString: defaultOutputFileString,
+          classNameString: defaultClassNameString,
+        );
+        generator.loadResources();
+        generator.writeOutputFiles();
+      } on Exception catch (e) {
+        final L10nException exception = e as L10nException;
+        print(exception.message);
+        fail('Generating output files should not fail: $e');
+      }
+
+      final File baseLocalizationsFile = fs.file(
+        fs.path.join(syntheticL10nPackagePath, 'output-localization-file.dart')
+      );
+      expect(baseLocalizationsFile.existsSync(), isTrue);
+
+      final String baseLocalizationsFileContents = fs.file(
+        fs.path.join(syntheticL10nPackagePath, 'output-localization-file.dart')
+      ).readAsStringSync();
+      expect(baseLocalizationsFileContents, contains('/// The price of an online shopping cart item.'));
+      expect(baseLocalizationsFileContents, contains(r'''
+  /// In en, this message translates to:
+  /// **'The price of this item is: \${price}'**'''));
+    });
+
     test('should generate a file per language', () {
       const String singleEnCaMessageArbFileString = '''
 {