l10n-related documentation improvements (#133114)

dev/tools/localization/bin/gen_localizations.dart

@@ -2,11 +2,11 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-// This program generates a getMaterialTranslation() and a
-// getCupertinoTranslation() function that look up the translations provided by
+// This program generates getMaterialTranslation(), getCupertinoTranslation(),
+// and getWidgetsTranslation() functions that look up the translations provided by
 // the arb files. The returned value is a generated instance of a
-// GlobalMaterialLocalizations or a GlobalCupertinoLocalizations that
-// corresponds to a single locale.
+// GlobalMaterialLocalizations, GlobalCupertinoLocalizations, or
+// GlobalWidgetsLocalizations object that corresponds to a single locale.
 //
 // The *.arb files are in packages/flutter_localizations/lib/src/l10n.
 //
@@ -40,8 +40,8 @@
 // ```
 //
 // If the data looks good, use the `-w` or `--overwrite` option to overwrite the
-// packages/flutter_localizations/lib/src/l10n/generated_material_localizations.dart
-// and packages/flutter_localizations/lib/src/l10n/generated_cupertino_localizations.dart file:
+// generated_material_localizations.dart, generated_cupertino_localizations.dart,
+// and generated_widgets_localizations.dart files in packages/flutter_localizations/lib/src/l10n/:
 //
 // ```
 // dart dev/tools/localization/bin/gen_localizations.dart --overwrite
@@ -543,19 +543,19 @@ void main(List<String> rawArgs) {
 
   // Maps of locales to resource key/value pairs for Widgets ARBs.
   final Map<LocaleInfo, Map<String, String>> widgetsLocaleToResources = <LocaleInfo, Map<String, String>>{};
-  // Maps of locales to resource key/attributes pairs for Widgets ARBs..
+  // Maps of locales to resource key/attributes pairs for Widgets ARBs.
   // https://github.com/googlei18n/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#resource-attributes
   final Map<LocaleInfo, Map<String, dynamic>> widgetsLocaleToResourceAttributes = <LocaleInfo, Map<String, dynamic>>{};
 
   // Maps of locales to resource key/value pairs for Material ARBs.
   final Map<LocaleInfo, Map<String, String>> materialLocaleToResources = <LocaleInfo, Map<String, String>>{};
-  // Maps of locales to resource key/attributes pairs for Material ARBs..
+  // Maps of locales to resource key/attributes pairs for Material ARBs.
   // https://github.com/googlei18n/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#resource-attributes
   final Map<LocaleInfo, Map<String, dynamic>> materialLocaleToResourceAttributes = <LocaleInfo, Map<String, dynamic>>{};
 
   // Maps of locales to resource key/value pairs for Cupertino ARBs.
   final Map<LocaleInfo, Map<String, String>> cupertinoLocaleToResources = <LocaleInfo, Map<String, String>>{};
-  // Maps of locales to resource key/attributes pairs for Cupertino ARBs..
+  // Maps of locales to resource key/attributes pairs for Cupertino ARBs.
   // https://github.com/googlei18n/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#resource-attributes
   final Map<LocaleInfo, Map<String, dynamic>> cupertinoLocaleToResourceAttributes = <LocaleInfo, Map<String, dynamic>>{};
 

packages/flutter/lib/src/cupertino/localizations.dart

@@ -57,7 +57,6 @@ enum DatePickerDateOrder {
 ///
 ///  * [DefaultCupertinoLocalizations], the default, English-only, implementation
 ///    of this interface.
-// TODO(xster): Supply non-english strings.
 abstract class CupertinoLocalizations {
   /// Year that is shown in [CupertinoDatePicker] spinner corresponding to the
   /// given year index.

packages/flutter/lib/src/material/material_localizations.dart

@@ -179,10 +179,11 @@ abstract class MaterialLocalizations {
   /// Label indicating that a given date is the current date.
   String get currentDateLabel;
 
-  /// Label for the scrim rendered underneath the content of a modal route.
+  /// Label for the scrim rendered underneath a [BottomSheet].
   String get scrimLabel;
 
-  /// Label for a BottomSheet.
+  /// Label for a [BottomSheet], used as the `modalRouteContentName` of the
+  /// [scrimOnTapHint].
   String get bottomSheetLabel;
 
   /// Hint text announced when tapping on the scrim underneath the content of

packages/flutter/lib/src/widgets/localizations.dart

@@ -96,7 +96,7 @@ Future<Map<Type, dynamic>> _loadAll(Locale locale, Iterable<LocalizationsDelegat
 /// the object created by an individual delegate's [load] method.
 ///
 /// An example of a class used as the value of `T` here would be
-/// MaterialLocalizations.
+/// [MaterialLocalizations].
 abstract class LocalizationsDelegate<T> {
   /// Abstract const constructor. This constructor enables subclasses to provide
   /// const constructors so that they can be used in const expressions.

packages/flutter_localizations/lib/src/l10n/README.md

@@ -15,12 +15,10 @@ apps in general, see the
 ### Translations for one locale: .arb files
 
 The Material and Cupertino libraries use
-[Application Resource Bundle](https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification)
+[Application Resource Bundle](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification)
 files, which have a `.arb` extension, to store localized translations
 of messages, format strings, and other values. This format is also
-used by the Dart [intl](https://pub.dev/packages/intl)
-package and it is supported by the
-[Google Translators Toolkit](https://translate.google.com/toolkit).
+used by the Dart [intl](https://pub.dev/packages/intl) package.
 
 The Material and Cupertino libraries only depend on a small subset
 of the ARB format. Each .arb file contains a single JSON table that

packages/flutter_localizations/lib/src/l10n/material_en.arb

@@ -73,7 +73,7 @@
 
   "scrimLabel": "Scrim",
   "@scrimLabel": {
-    "description": "The label for the scrim rendered underneath the content of a modal route."
+    "description": "The label for the scrim rendered underneath the content of a bottom sheet (used as the 'modalRouteContentName' of the 'scrimOnTapHint' message)."
   },
 
   "bottomSheetLabel": "Bottom Sheet",
@@ -83,7 +83,7 @@
 
   "scrimOnTapHint": "Close $modalRouteContentName",
   "@scrimOnTapHint": {
-    "description": "The onTapHint for the scrim rendered underneath the content of a modal route which users can tap to dismiss the content",
+    "description": "The onTapHint for the scrim rendered underneath the content of a modal route (especially a bottom sheet) which users can tap to dismiss the content.",
     "parameters": "modalRouteContentName"
   },