Updated supportedLocales doc, etc (#23683)

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

@@ -68,6 +68,8 @@ const TextStyle _errorTextStyle = TextStyle(
 ///  * [Navigator], which is used to manage the app's stack of pages.
 ///  * [MaterialPageRoute], which defines an app page that transitions in a material-specific way.
 ///  * [WidgetsApp], which defines the basic app elements but does not depend on the material library.
+///  * The Flutter Internationalization Tutorial,
+///    <https://flutter.io/tutorials/internationalization/>.
 class MaterialApp extends StatefulWidget {
   /// Creates a MaterialApp.
   ///
@@ -171,6 +173,33 @@ class MaterialApp extends StatefulWidget {
 
   /// {@macro flutter.widgets.widgetsApp.localizationsDelegates}
   ///
+  /// Internationalized apps that require translations for one of the locales
+  /// listed in [GlobalMaterialLocalizations] should specify this paramter
+  /// and list the [supportedLocales] that the application can handle.
+  ///
+  /// ```dart
+  /// import 'package:flutter_localizations/flutter_localizations.dart';
+  /// MaterialApp(
+  ///  localizationsDelegates: [
+  ///    // ... app-specific localization delegate[s] here
+  ///    GlobalMaterialLocalizations.delegate,
+  ///    GlobalWidgetsLocalizations.delegate,
+  ///  ],
+  ///  supportedLocales: [
+  ///     const Locale('en', 'US'), // English
+  ///     const Locale('he', 'IL'), // Hebrew
+  ///     // ... other locales the app supports
+  ///   ],
+  ///   // ...
+  /// )
+  /// ```
+  ///
+  /// ## Adding localizations for a new locale
+  ///
+  /// The information that follows applies to the unusual case of an app
+  /// adding translations for a language not already supported by
+  /// [GlobalMaterialLocalizations].
+  ///
   /// Delegates that produce [WidgetsLocalizations] and [MaterialLocalizations]
   /// are included automatically. Apps can provide their own versions of these
   /// localizations by creating implementations of
@@ -225,6 +254,14 @@ class MaterialApp extends StatefulWidget {
   ///   // ...
   /// )
   /// ```
+  /// See also:
+  ///
+  ///  * [supportedLocales], which must be specified along with
+  ///    [localizationsDelegates].
+  ///  * [GlobalMaterialLocalizations], a [localizationsDelegates] value
+  ///    which provides material localizations for many languages.
+  ///  * The Flutter Internationalization Tutorial,
+  ///    <https://flutter.io/tutorials/internationalization/>.
   final Iterable<LocalizationsDelegate<dynamic>> localizationsDelegates;
 
   /// {@macro flutter.widgets.widgetsApp.localeResolutionCallback}
@@ -236,26 +273,14 @@ class MaterialApp extends StatefulWidget {
   ///
   /// It is passed along unmodified to the [WidgetsApp] built by this widget.
   ///
-  /// The material widgets include translations for locales with the following
-  /// language codes:
-  /// ```
-  /// ar - Arabic
-  /// de - German
-  /// en - English
-  /// es - Spanish
-  /// fa - Farsi (Persian)
-  /// fr - French
-  /// he - Hebrew
-  /// it - Italian
-  /// ja - Japanese
-  /// ps - Pashto
-  /// pt - Portugese
-  /// ro - Romanian
-  /// ru - Russian
-  /// sd - Sindhi
-  /// ur - Urdu
-  /// zh - Chinese (simplified)
-  /// ```
+  /// See also:
+  ///
+  ///  * [localizationsDelegates], which must be specified for localized
+  ///    applications.
+  ///  * [GlobalMaterialLocalizations], a [localizationsDelegates] value
+  ///    which provides material localizations for many languages.
+  ///  * The Flutter Internationalization Tutorial,
+  ///    <https://flutter.io/tutorials/internationalization/>.
   final Iterable<Locale> supportedLocales;
 
   /// Turns on a performance overlay.

packages/flutter_localizations/lib/src/material_localizations.dart

@@ -14,10 +14,6 @@ import 'l10n/date_localizations.dart' as date_localizations;
 import 'l10n/localizations.dart';
 import 'widgets_localizations.dart';
 
-// Watch out: the supported locales list in the doc comment below must be kept
-// in sync with the list we test, see test/translations_test.dart, and of course
-// the actual list of supported locales in _MaterialLocalizationsDelegate.
-
 /// Implementation of localized strings for the material widgets using the
 /// `intl` package for date and time formatting.
 ///