l10n tool improvements, stocks app refresh (#44313)

* Add pubspec.yaml comment

* Add --help flag

dev/tools/localization/gen_l10n.dart

@@ -37,6 +37,22 @@ import 'messages_all.dart';
 /// );
 /// ```
 ///
+/// ## Update pubspec.yaml
+///
+/// Please make sure to update your pubspec.yaml to include the following
+/// packages:
+///
+/// ```
+/// dependencies:
+///   # Internationalization support.
+///   flutter_localizations:
+///     sdk: flutter
+///   intl: 0.16.0
+///   intl_translation: 0.17.7
+///
+///   # rest of dependencies
+/// ```
+///
 /// ## iOS Applications
 ///
 /// iOS applications define key application metadata, including supported
@@ -56,7 +72,6 @@ import 'messages_all.dart';
 /// you wish to add from the pop-up menu in the Value field. This list should
 /// be consistent with the languages listed in the @className.supportedLocales
 /// property.
-
 class @className {
   @className(Locale locale) : _localeName = locale.toString();
 
@@ -292,13 +307,46 @@ String _importFilePath(String path, String fileName) {
   return '$replaceLib/$fileName';
 }
 
-Future<void> main(List<String> args) async {
+Future<void> main(List<String> arguments) async {
   final argslib.ArgParser parser = argslib.ArgParser();
-  parser.addOption('arb-dir', defaultsTo: path.join('lib', 'l10n'));
-  parser.addOption('template-arb-file', defaultsTo: 'app_en.arb');
-  parser.addOption('output-localization-file', defaultsTo: 'app_localizations.dart');
-  parser.addOption('output-class', defaultsTo: 'AppLocalizations');
-  final argslib.ArgResults results = parser.parse(args);
+  parser.addFlag(
+    'help',
+    defaultsTo: false,
+    negatable: false,
+    help: 'Print this help message.',
+  );
+  parser.addOption(
+    'arb-dir',
+    defaultsTo: path.join('lib', 'l10n'),
+    help: 'The directory where all localization files should reside. For '
+      'example, the template and translated arb files should be located here. '
+      'Also, the generated output messages Dart files for each locale and the '
+      'generated localizations classes will be created here.',
+  );
+  parser.addOption(
+    'template-arb-file',
+    defaultsTo: 'app_en.arb',
+    help: 'The template arb file that will be used as the basis for '
+      'generating the Dart localization and messages files.',
+  );
+  parser.addOption(
+    'output-localization-file',
+    defaultsTo: 'app_localizations.dart',
+    help: 'The filename for the output localization and localizations '
+      'delegate classes.',
+  );
+  parser.addOption(
+    'output-class',
+    defaultsTo: 'AppLocalizations',
+    help: 'The Dart class name to use for the output localization and '
+      'localizations delegate classes.',
+  );
+
+  final argslib.ArgResults results = parser.parse(arguments);
+  if (results['help'] == true) {
+    print(parser.usage);
+    exit(0);
+  }
 
   final String arbPathString = results['arb-dir'];
   final String outputFileString = results['output-localization-file'];

examples/stocks/lib/i18n/regenerate.md

@@ -15,8 +15,8 @@ for more info.
 `messages_all.dart`, and `stock_strings.dart` with the following command:
 
 ```dart
-dart ${FLUTTER_PATH}/dev/tools/localization/gen_l10n.dart --arb-dir=lib/i18n
-  --template-arb-file=stocks_en_EN.arb --output-localization-file=stock_strings.dart
+dart ${FLUTTER_PATH}/dev/tools/localization/gen_l10n.dart --arb-dir=lib/i18n \
+  --template-arb-file=stocks_en_US.arb --output-localization-file=stock_strings.dart \
   --output-class=StockStrings
 ```
 

examples/stocks/lib/i18n/stock_strings.dart

@@ -23,6 +23,23 @@ import 'messages_all.dart';
 /// );
 /// ```
 ///
+/// ## Update pubspec.yaml
+///
+/// Please make sure to update your pubspec.yaml to include the following
+/// packages:
+///
+/// ```
+/// dependencies:
+///   # rest of dependencies
+///
+///   flutter_localizations:
+///     sdk: flutter
+///   intl: 0.16.0
+///   intl_translation: 0.17.7
+///
+///   # rest of dependencies
+/// ```
+///
 /// ## iOS Applications
 ///
 /// iOS applications define key application metadata, including supported
@@ -42,7 +59,6 @@ import 'messages_all.dart';
 /// you wish to add from the pop-up menu in the Value field. This list should
 /// be consistent with the languages listed in the StockStrings.supportedLocales
 /// property.
-
 class StockStrings {
   StockStrings(Locale locale) : _localeName = locale.toString();