Add maybeLocaleOf to Localizations (#68911)

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

@@ -5541,7 +5541,7 @@ class RichText extends MultiChildRenderObjectWidget {
       strutStyle: strutStyle,
       textWidthBasis: textWidthBasis,
       textHeightBehavior: textHeightBehavior,
-      locale: locale ?? Localizations.localeOf(context, nullOk: true),
+      locale: locale ?? Localizations.maybeLocaleOf(context),
     );
   }
 
@@ -5559,7 +5559,7 @@ class RichText extends MultiChildRenderObjectWidget {
       ..strutStyle = strutStyle
       ..textWidthBasis = textWidthBasis
       ..textHeightBehavior = textHeightBehavior
-      ..locale = locale ?? Localizations.localeOf(context, nullOk: true);
+      ..locale = locale ?? Localizations.maybeLocaleOf(context);
   }
 
   @override

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

@@ -2779,7 +2779,7 @@ class _Editable extends LeafRenderObjectWidget {
       textScaleFactor: textScaleFactor,
       textAlign: textAlign,
       textDirection: textDirection,
-      locale: locale ?? Localizations.localeOf(context, nullOk: true),
+      locale: locale ?? Localizations.maybeLocaleOf(context),
       selection: value.selection,
       offset: offset,
       onSelectionChanged: onSelectionChanged,
@@ -2824,7 +2824,7 @@ class _Editable extends LeafRenderObjectWidget {
       ..textScaleFactor = textScaleFactor
       ..textAlign = textAlign
       ..textDirection = textDirection
-      ..locale = locale ?? Localizations.localeOf(context, nullOk: true)
+      ..locale = locale ?? Localizations.maybeLocaleOf(context)
       ..selection = value.selection
       ..offset = offset
       ..onSelectionChanged = onSelectionChanged

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

@@ -51,7 +51,7 @@ ImageConfiguration createLocalImageConfiguration(BuildContext context, { Size? s
   return ImageConfiguration(
     bundle: DefaultAssetBundle.of(context),
     devicePixelRatio: MediaQuery.maybeOf(context)?.devicePixelRatio ?? 1.0,
-    locale: Localizations.localeOf(context, nullOk: true),
+    locale: Localizations.maybeLocaleOf(context),
     textDirection: Directionality.maybeOf(context),
     size: size,
     platform: defaultTargetPlatform,

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

@@ -416,14 +416,38 @@ class Localizations extends StatefulWidget {
   /// true, in which case it returns null.
   static Locale? localeOf(BuildContext context, { bool nullOk = false }) {
     assert(context != null);
-    assert(nullOk != null);
     final _LocalizationsScope? scope = context.dependOnInheritedWidgetOfExactType<_LocalizationsScope>();
     if (nullOk && scope == null)
       return null;
-    assert(scope != null, 'a Localizations ancestor was not found');
+    assert(() {
+      if (scope == null) {
+        throw FlutterError(
+          'Requested the Locale of a context that does not include a Localizations ancestor.\n'
+          'To request the Locale, the context used to retrieve the Localizations widget must '
+          'be that of a widget that is a descendant of a Localizations widget.'
+        );
+      }
+      if (!nullOk && scope.localizationsState.locale == null) {
+        throw FlutterError(
+          'Localizations.localeOf found a Localizations widget that had a unexpected null locale.\n'
+        );
+      }
+      return true;
+    }());
     return scope!.localizationsState.locale;
   }
 
+  /// The locale of the Localizations widget for the widget tree that
+  /// corresponds to [BuildContext] `context`.
+  ///
+  /// If no [Localizations] widget is in scope then this function will return
+  /// null. Equivalent to calling [localeOf] with `nullOk` set to true.
+  static Locale? maybeLocaleOf(BuildContext context) {
+    assert(context != null);
+    final _LocalizationsScope? scope = context.dependOnInheritedWidgetOfExactType<_LocalizationsScope>();
+    return scope?.localizationsState.locale;
+  }
+
   // There doesn't appear to be a need to make this public. See the
   // Localizations.override factory constructor.
   static List<LocalizationsDelegate<dynamic>> _delegatesOf(BuildContext context) {

packages/flutter/test/widgets/localizations_test.dart

@@ -34,6 +34,24 @@ void main() {
     await tester.pump();
     expect(find.text('loaded'), findsOneWidget);
   });
+
+  testWidgets('Localizations.localeOf throws when no localizations exist', (WidgetTester tester) async {
+    final GlobalKey contextKey = GlobalKey(debugLabel: 'Test Key');
+    await tester.pumpWidget(Container(key: contextKey));
+
+    expect(() => Localizations.localeOf(contextKey.currentContext!), throwsA(isAssertionError.having(
+          (AssertionError e) => e.message,
+      'message',
+      contains('does not include a Localizations ancestor'),
+    )));
+  });
+
+  testWidgets('Localizations.maybeLocaleOf returns null when no localizations exist', (WidgetTester tester) async {
+    final GlobalKey contextKey = GlobalKey(debugLabel: 'Test Key');
+    await tester.pumpWidget(Container(key: contextKey));
+
+    expect(Localizations.maybeLocaleOf(contextKey.currentContext!), isNull);
+  });
 }
 
 class FakeLocalizationsDelegate extends LocalizationsDelegate<String> {