Skip to content

Commit ec93269

Browse files
authored
Uses system default locale for text rendering when preferred locale isn't supported (#195997)
## Description Makes the engine render text with the system locale when the user's preferred locale isn't one of the app's supported locales. fixes #194931 ## Technical details When the user's preferred locale isn't one of the app's `supportedLocales`, `WidgetsApp` falls back to another locale (`en_US` by default) for localization. `RichText` and `EditableText` were passing that fallback locale to the engine for text rendering. With this PR they pass no locale in that case, so the platform's default locale is used (Skia's behavior). On Windows, an app that doesn't list Chinese now renders Han characters with Chinese fonts on a Chinese system, instead of Japanese fallback fonts. ## Alternatives considered ### 1) Adding new TextLocale API This PR adds widgets that are not publicly available. Deciding on a new public API requires more forethought and maintenance than keeping one private. I've decided to keep it private for now and we can consider promoting it or replacing it with a public API later. I think the sorts of usage of Flutter that would require it are very rare, something like making a whole new alternative framework on dart:ui. ### 2) Considering secondary preferred locales This PR only checks the user's first preferred locale. Counting any preferred locale would help a `[ja_JP, zh_CN]` user of a `zh_CN` app: the app's Chinese strings would keep `zh_CN` glyphs instead of the OS default (likely Japanese). But it would bring back the original bug for the more common `[zh_CN, en_US]` user of an English-only app. That app resolves to `en_US`, its `en_US` locale would be passed to the engine, and Han text would render with Japanese fonts again. I chose to handle the common case and documented the trade-off in a test. Apps can opt out with an explicit `WidgetsApp.locale` or `TextStyle.locale`. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/CONTRIBUTING.ai.md [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [flutter/website]: https://github.com/flutter/website [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent b1ea363 commit ec93269

6 files changed

Lines changed: 439 additions & 5 deletions

File tree

‎packages/flutter/lib/src/widgets/app.dart‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1020,6 +1020,12 @@ class WidgetsApp extends StatefulWidget {
10201020
/// omitted.
10211021
/// {@endtemplate}
10221022
///
1023+
/// If the app doesn't set [supportedLocales], [locale],
1024+
/// [localeResolutionCallback], or [localeListResolutionCallback], its locale
1025+
/// is always the default `en_US`. In that case text widgets don't pass the
1026+
/// locale to the text engine, so the platform's default locale is used for
1027+
/// font fallback. See [Localizations.isDefaultLocale].
1028+
///
10231029
/// See also:
10241030
///
10251031
/// * [MaterialApp.supportedLocales], which sets the `supportedLocales`
@@ -1677,6 +1683,20 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
16771683
}
16781684
}
16791685

1686+
// Whether the app left its locale configuration at the defaults, so the
1687+
// resolved locale is always the default en_US rather than a locale the app
1688+
// chose for its content.
1689+
//
1690+
// The default supportedLocales of WidgetsApp, MaterialApp, and CupertinoApp
1691+
// is a const list, so it is canonicalized and can be detected with
1692+
// identical().
1693+
bool get _usesDefaultLocale {
1694+
return widget.locale == null &&
1695+
widget.localeListResolutionCallback == null &&
1696+
widget.localeResolutionCallback == null &&
1697+
identical(widget.supportedLocales, const <Locale>[Locale('en', 'US')]);
1698+
}
1699+
16801700
// BUILDER
16811701

16821702
@override
@@ -1839,6 +1859,7 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
18391859
builder: (BuildContext context, _) {
18401860
return Localizations(
18411861
isApplicationLevel: true,
1862+
isDefaultLocale: _usesDefaultLocale,
18421863
locale: _localizationsResolver.locale,
18431864
delegates: _localizationsResolver.localizationsDelegates.toList(),
18441865
child: title ?? result,

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

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6670,6 +6670,8 @@ class RichText extends MultiChildRenderObjectWidget {
66706670
///
66716671
/// It's rarely necessary to set this property. By default its value
66726672
/// is inherited from the enclosing app with `Localizations.localeOf(context)`.
6673+
/// If the app did not choose its locale (see [Localizations.isDefaultLocale]),
6674+
/// no locale is used and the platform's default locale applies.
66736675
///
66746676
/// See [RenderParagraph.locale] for more information.
66756677
final Locale? locale;
@@ -6703,6 +6705,16 @@ class RichText extends MultiChildRenderObjectWidget {
67036705
double _getDevicePixelRatio(BuildContext context) =>
67046706
MediaQuery.maybeDevicePixelRatioOf(context) ?? View.maybeOf(context)?.devicePixelRatio ?? 1.0;
67056707

6708+
// A default locale that the app didn't choose isn't passed to the engine, so
6709+
// the platform's default locale is used for font fallback.
6710+
// See https://github.com/flutter/flutter/issues/194931.
6711+
Locale? _effectiveLocale(BuildContext context) {
6712+
if (locale != null) {
6713+
return locale;
6714+
}
6715+
return Localizations.isDefaultLocaleOf(context) ? null : Localizations.maybeLocaleOf(context);
6716+
}
6717+
67066718
@override
67076719
RenderParagraph createRenderObject(BuildContext context) {
67086720
assert(textDirection != null || debugCheckHasDirectionality(context));
@@ -6718,7 +6730,7 @@ class RichText extends MultiChildRenderObjectWidget {
67186730
textWidthBasis: textWidthBasis,
67196731
textHeightBehavior: textHeightBehavior,
67206732
hyphens: hyphens,
6721-
locale: locale ?? Localizations.maybeLocaleOf(context),
6733+
locale: _effectiveLocale(context),
67226734
registrar: selectionRegistrar,
67236735
selectionColor: selectionColor,
67246736
devicePixelRatio: _getDevicePixelRatio(context),
@@ -6740,7 +6752,7 @@ class RichText extends MultiChildRenderObjectWidget {
67406752
..textWidthBasis = textWidthBasis
67416753
..textHeightBehavior = textHeightBehavior
67426754
..hyphens = hyphens
6743-
..locale = locale ?? Localizations.maybeLocaleOf(context)
6755+
..locale = _effectiveLocale(context)
67446756
..registrar = selectionRegistrar
67456757
..selectionColor = selectionColor
67466758
..devicePixelRatio = _getDevicePixelRatio(context);

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

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1194,6 +1194,8 @@ class EditableText extends StatefulWidget {
11941194
///
11951195
/// It's rarely necessary to set this property. By default its value
11961196
/// is inherited from the enclosing app with `Localizations.localeOf(context)`.
1197+
/// If the app did not choose its locale (see [Localizations.isDefaultLocale]),
1198+
/// no locale is used and the platform's default locale applies.
11971199
///
11981200
/// See [RenderEditable.locale] for more information.
11991201
final Locale? locale;
@@ -6241,6 +6243,16 @@ class _Editable extends MultiChildRenderObjectWidget {
62416243
final Color? promptRectColor;
62426244
final Clip clipBehavior;
62436245

6246+
// A default locale that the app didn't choose isn't passed to the engine, so
6247+
// the platform's default locale is used for font fallback.
6248+
// See https://github.com/flutter/flutter/issues/194931.
6249+
Locale? _effectiveLocale(BuildContext context) {
6250+
if (locale != null) {
6251+
return locale;
6252+
}
6253+
return Localizations.isDefaultLocaleOf(context) ? null : Localizations.maybeLocaleOf(context);
6254+
}
6255+
62446256
@override
62456257
RenderEditable createRenderObject(BuildContext context) {
62466258
return RenderEditable(
@@ -6261,7 +6273,7 @@ class _Editable extends MultiChildRenderObjectWidget {
62616273
textScaler: textScaler,
62626274
textAlign: textAlign,
62636275
textDirection: textDirection,
6264-
locale: locale ?? Localizations.maybeLocaleOf(context),
6276+
locale: _effectiveLocale(context),
62656277
selection: value.selection,
62666278
offset: offset,
62676279
ignorePointer: rendererIgnoresPointer,
@@ -6305,7 +6317,7 @@ class _Editable extends MultiChildRenderObjectWidget {
63056317
..textScaler = textScaler
63066318
..textAlign = textAlign
63076319
..textDirection = textDirection
6308-
..locale = locale ?? Localizations.maybeLocaleOf(context)
6320+
..locale = _effectiveLocale(context)
63096321
..selection = value.selection
63106322
..offset = offset
63116323
..ignorePointer = rendererIgnoresPointer

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

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
/// @docImport 'package:flutter_localizations/flutter_localizations.dart';
77
///
88
/// @docImport 'app.dart';
9+
/// @docImport 'editable_text.dart';
910
/// @docImport 'reorderable_list.dart';
1011
library;
1112

@@ -349,18 +350,20 @@ class _LocalizationsScope extends InheritedWidget {
349350
const _LocalizationsScope({
350351
super.key,
351352
required this.locale,
353+
required this.isDefaultLocale,
352354
required this.localizationsState,
353355
required this.typeToResources,
354356
required super.child,
355357
});
356358

357359
final Locale locale;
360+
final bool isDefaultLocale;
358361
final _LocalizationsState localizationsState;
359362
final Map<Type, dynamic> typeToResources;
360363

361364
@override
362365
bool updateShouldNotify(_LocalizationsScope old) {
363-
return typeToResources != old.typeToResources;
366+
return typeToResources != old.typeToResources || isDefaultLocale != old.isDefaultLocale;
364367
}
365368
}
366369

@@ -483,6 +486,7 @@ class Localizations extends StatefulWidget {
483486
required this.delegates,
484487
this.child,
485488
this.isApplicationLevel = false,
489+
this.isDefaultLocale = false,
486490
}) : assert(
487491
delegates.any(
488492
(LocalizationsDelegate<dynamic> delegate) =>
@@ -514,6 +518,10 @@ class Localizations extends StatefulWidget {
514518
/// The `locale` and `delegates` parameters default to the [Localizations.locale]
515519
/// and [Localizations.delegates] values from the nearest [Localizations] ancestor.
516520
///
521+
/// If `locale` is null, [isDefaultLocale] is also inherited from the nearest
522+
/// [Localizations] ancestor. Otherwise [isDefaultLocale] is false, since the
523+
/// locale was chosen explicitly.
524+
///
517525
/// To override the [Localizations.locale] or [Localizations.delegates] for an
518526
/// entire app, specify [WidgetsApp.locale] or [WidgetsApp.localizationsDelegates]
519527
/// (or specify the same parameters for [MaterialApp]).
@@ -534,6 +542,7 @@ class Localizations extends StatefulWidget {
534542
key: key,
535543
locale: locale ?? Localizations.localeOf(context),
536544
delegates: mergedDelegates,
545+
isDefaultLocale: locale == null && Localizations.isDefaultLocaleOf(context),
537546
child: child,
538547
);
539548
}
@@ -554,6 +563,51 @@ class Localizations extends StatefulWidget {
554563
/// locale.
555564
final bool isApplicationLevel;
556565

566+
/// Whether [locale] is a default that the app did not choose, rather than a
567+
/// locale the app selected for its content.
568+
///
569+
/// For example, [WidgetsApp] sets this to true when the app doesn't
570+
/// configure its locales (no [WidgetsApp.locale], no locale resolution
571+
/// callbacks, and the default [WidgetsApp.supportedLocales]). In that case
572+
/// [locale] is always `en_US`, regardless of the user's preferred locales.
573+
///
574+
/// Text widgets such as [RichText] and [EditableText] don't pass a default
575+
/// locale to the text engine. The platform's default locale is used for
576+
/// font fallback and shaping instead, so that, for example, Han characters
577+
/// render with the glyphs the user expects.
578+
///
579+
/// Defaults to false.
580+
///
581+
/// See also:
582+
///
583+
/// * [isDefaultLocaleOf], which reads this value from a [BuildContext].
584+
final bool isDefaultLocale;
585+
586+
/// Whether the locale of the nearest [Localizations] ancestor of `context`
587+
/// is a default that the app did not choose.
588+
///
589+
/// Widgets that render text without [RichText] or [EditableText], such as
590+
/// custom render objects that use [TextPainter], can use this to pick
591+
/// the locale to give to the text engine:
592+
///
593+
/// ```dart
594+
/// final Locale? textLocale = Localizations.isDefaultLocaleOf(context)
595+
/// ? null
596+
/// : Localizations.maybeLocaleOf(context);
597+
/// ```
598+
///
599+
/// Returns false if there is no [Localizations] ancestor.
600+
///
601+
/// See also:
602+
///
603+
/// * [Localizations.isDefaultLocale], which describes when the locale is a
604+
/// default.
605+
static bool isDefaultLocaleOf(BuildContext context) {
606+
final _LocalizationsScope? scope = context
607+
.dependOnInheritedWidgetOfExactType<_LocalizationsScope>();
608+
return scope?.isDefaultLocale ?? false;
609+
}
610+
557611
/// The locale of the Localizations widget for the widget tree that
558612
/// corresponds to [BuildContext] `context`.
559613
///
@@ -629,6 +683,9 @@ class Localizations extends StatefulWidget {
629683
super.debugFillProperties(properties);
630684
properties.add(DiagnosticsProperty<Locale>('locale', locale));
631685
properties.add(IterableProperty<LocalizationsDelegate<dynamic>>('delegates', delegates));
686+
properties.add(
687+
FlagProperty('isDefaultLocale', value: isDefaultLocale, ifTrue: 'default locale'),
688+
);
632689
}
633690
}
634691

@@ -740,6 +797,7 @@ class _LocalizationsState extends State<Localizations> {
740797
child: _LocalizationsScope(
741798
key: _localizedResourcesScopeKey,
742799
locale: _locale!,
800+
isDefaultLocale: widget.isDefaultLocale,
743801
localizationsState: this,
744802
typeToResources: _typeToResources,
745803
child: Directionality(textDirection: _textDirection, child: widget.child!),

‎packages/flutter/lib/src/widgets/text.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -625,6 +625,8 @@ class Text extends StatelessWidget {
625625
///
626626
/// It's rarely necessary to set this property. By default its value
627627
/// is inherited from the enclosing app with `Localizations.localeOf(context)`.
628+
/// If the app did not choose its locale (see [Localizations.isDefaultLocale]),
629+
/// no locale is used and the platform's default locale applies.
628630
///
629631
/// See [RenderParagraph.locale] for more information.
630632
final Locale? locale;

0 commit comments

Comments
 (0)