From 4ae9bff83b11d916f8f3c634bf102fba0392b148 Mon Sep 17 00:00:00 2001 From: Justin McCandless Date: Thu, 6 Aug 2026 15:22:01 -0700 Subject: [PATCH 1/5] Update for post-decoupling i18n setup --- .../content/ui/internationalization/index.md | 91 +++++++------------ 1 file changed, 33 insertions(+), 58 deletions(-) diff --git a/sites/docs/src/content/ui/internationalization/index.md b/sites/docs/src/content/ui/internationalization/index.md index 69180da064..148a98251e 100644 --- a/sites/docs/src/content/ui/internationalization/index.md +++ b/sites/docs/src/content/ui/internationalization/index.md @@ -57,45 +57,14 @@ in a directory of your choice with the `flutter create` command. $ flutter create ``` -To use `flutter_localizations`, -add the package as a dependency to your `pubspec.yaml` file, -as well as the `intl` package: - -```console -$ flutter pub add flutter_localizations --sdk=flutter -$ flutter pub add intl:any -``` - -This creates a `pubspec.yml` file with the following entries: - - -```yaml -dependencies: - flutter: - sdk: flutter - flutter_localizations: - sdk: flutter - intl: any -``` - -Then import the `flutter_localizations` library and specify -`localizationsDelegates` and `supportedLocales` for -your `MaterialApp` or `CupertinoApp`: - - -```dart -import 'package:flutter_localizations/flutter_localizations.dart'; -``` +Then specify `localizationsDelegates` and `supportedLocales` for your +`MaterialApp` or `CupertinoApp`: ```dart return const MaterialApp( title: 'Localizations Sample App', - localizationsDelegates: [ - GlobalMaterialLocalizations.delegate, - GlobalWidgetsLocalizations.delegate, - GlobalCupertinoLocalizations.delegate, - ], + localizationsDelegates: GlobalMaterialLocalizations.delegates, supportedLocales: [ Locale('en'), // English Locale('es'), // Spanish @@ -104,19 +73,17 @@ return const MaterialApp( ); ``` -After introducing the `flutter_localizations` package -and adding the previous code, -the `Material` and `Cupertino` -packages should now be correctly localized in -one of the supported locales. -Widgets should be adapted to the localized messages, -along with correct left-to-right or right-to-left layout. +After introducing the `flutter_localizations` package and adding the previous +code, the `Material` and `Cupertino` packages should now be correctly localized +in one of the supported locales. Widgets should be adapted to the localized +messages, along with correct left-to-right or right-to-left layout. Try switching the target platform's locale to Spanish (`es`) and the messages should be localized. -Apps based on `WidgetsApp` are similar except that the -`GlobalMaterialLocalizations.delegate` isn't needed. +Apps that are not based on `MaterialApp` should instead use +`GlobalCupertinoLocalizations.delegates` or +`flutter_localizations.GlobalWidgetsLocalizations.delegate`. The full `Locale.fromSubtags` constructor is preferred as it supports [`scriptCode`][], though the `Locale` default @@ -128,7 +95,7 @@ The elements of the `localizationsDelegates` list are factories that produce collections of localized values. `GlobalMaterialLocalizations.delegate` provides localized strings and other values for the Material Components -library. `GlobalWidgetsLocalizations.delegate` +library. `flutter_localizations.GlobalWidgetsLocalizations.delegate` defines the default text direction, either left-to-right or right-to-left, for the widgets library. @@ -190,18 +157,29 @@ widget should re-render in Spanish. ### Adding your own localized messages - -After adding the `flutter_localizations` package, -you can configure localization. To add localized text to your application, complete the following instructions: -1. Add the `intl` package as a dependency, pulling - in the version pinned by `flutter_localizations`: +1. Add the package `flutter_localizations` as a dependency to your + `pubspec.yaml` file, as well as the `intl` package, at the version pinned by + `flutter_localizations`: - ```console - $ flutter pub add intl:any - ``` +```console +$ flutter pub add flutter_localizations --sdk=flutter +$ flutter pub add intl:any +``` + +This creates the following entries in the `pubspec.yml` file: + + +```yaml +dependencies: + flutter: + sdk: flutter + flutter_localizations: + sdk: flutter + intl: any +``` 2. Open the `pubspec.yaml` file and enable the `generate` flag. This flag is found in the `flutter` section in the pubspec file. @@ -276,10 +254,8 @@ complete the following instructions: return const MaterialApp( title: 'Localizations Sample App', localizationsDelegates: [ - AppLocalizations.delegate, // Add this line - GlobalMaterialLocalizations.delegate, - GlobalWidgetsLocalizations.delegate, - GlobalCupertinoLocalizations.delegate, + AppLocalizations.delegate, // Add this delegate + ...GlobalMaterialLocalizations.delegates, ], supportedLocales: [ Locale('en'), // English @@ -1145,8 +1121,7 @@ adds the `NnMaterialLocalizations` delegate instance to the app's ```dart const MaterialApp( localizationsDelegates: [ - GlobalWidgetsLocalizations.delegate, - GlobalMaterialLocalizations.delegate, + ...GlobalMaterialLocalizations.delegates, NnMaterialLocalizations.delegate, // Add the newly created delegate ], supportedLocales: [Locale('en', 'US'), Locale('nn')], From b24828f866cc8cbee4038b857b2ce42b50d26be6 Mon Sep 17 00:00:00 2001 From: Justin McCandless Date: Thu, 6 Aug 2026 15:47:25 -0700 Subject: [PATCH 2/5] Update example --- .../internationalization/gen_l10n_example/lib/main.dart | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/examples/internationalization/gen_l10n_example/lib/main.dart b/examples/internationalization/gen_l10n_example/lib/main.dart index a9a725c2ec..7c6466f0be 100644 --- a/examples/internationalization/gen_l10n_example/lib/main.dart +++ b/examples/internationalization/gen_l10n_example/lib/main.dart @@ -1,9 +1,5 @@ import 'package:flutter/material.dart'; -// #docregion localization-delegates-import -import 'package:flutter_localizations/flutter_localizations.dart'; -// #enddocregion localization-delegates-import - // #docregion app-localizations-import import 'l10n/app_localizations.dart'; @@ -19,9 +15,7 @@ class MyApp extends StatelessWidget { title: 'Localizations Sample App', localizationsDelegates: [ AppLocalizations.delegate, // Add this line - GlobalMaterialLocalizations.delegate, - GlobalWidgetsLocalizations.delegate, - GlobalCupertinoLocalizations.delegate, + ...GlobalMaterialLocalizations.delegate, ], supportedLocales: [ Locale('en'), // English From b0883b2fec6cf0b3f5eb42356fa78d311cdb8bbd Mon Sep 17 00:00:00 2001 From: Justin McCandless Date: Fri, 7 Aug 2026 15:25:29 -0700 Subject: [PATCH 3/5] Bring back flutter_localizations import. But namespace it. --- .../gen_l10n_example/lib/main.dart | 5 +++ .../content/ui/internationalization/index.md | 31 +++++++++++++++++-- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/examples/internationalization/gen_l10n_example/lib/main.dart b/examples/internationalization/gen_l10n_example/lib/main.dart index 7c6466f0be..b3b55db27c 100644 --- a/examples/internationalization/gen_l10n_example/lib/main.dart +++ b/examples/internationalization/gen_l10n_example/lib/main.dart @@ -1,5 +1,10 @@ import 'package:flutter/material.dart'; +// #docregion localization-delegates-import +import 'package:flutter_localizations/flutter_localizations.dart' + as flutter_localizations; +// #enddocregion localization-delegates-import + // #docregion app-localizations-import import 'l10n/app_localizations.dart'; diff --git a/sites/docs/src/content/ui/internationalization/index.md b/sites/docs/src/content/ui/internationalization/index.md index 148a98251e..fd8439501c 100644 --- a/sites/docs/src/content/ui/internationalization/index.md +++ b/sites/docs/src/content/ui/internationalization/index.md @@ -57,8 +57,35 @@ in a directory of your choice with the `flutter create` command. $ flutter create ``` -Then specify `localizationsDelegates` and `supportedLocales` for your -`MaterialApp` or `CupertinoApp`: +To use `flutter_localizations`, add the package as a dependency to your +`pubspec.yaml` file, as well as the `intl` package: + +```console +$ flutter pub add flutter_localizations --sdk=flutter +$ flutter pub add intl:any +``` + +This creates a `pubspec.yml` file with the following entries: + + +```yaml +dependencies: + flutter: + sdk: flutter + flutter_localizations: + sdk: flutter + intl: any +``` + +Then import the `flutter_localizations` library and specify +`localizationsDelegates` and `supportedLocales` for +your `MaterialApp` or `CupertinoApp`: + + +```dart +import 'package:flutter_localizations/flutter_localizations.dart' as + flutter_localizations; +``` ```dart From 9566ac8b29b840c430fce9fa753673a1e6132999 Mon Sep 17 00:00:00 2001 From: Justin McCandless Date: Fri, 7 Aug 2026 15:41:31 -0700 Subject: [PATCH 4/5] Ran codegen script --- .../src/content/ui/internationalization/index.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/sites/docs/src/content/ui/internationalization/index.md b/sites/docs/src/content/ui/internationalization/index.md index fd8439501c..89a1a844c7 100644 --- a/sites/docs/src/content/ui/internationalization/index.md +++ b/sites/docs/src/content/ui/internationalization/index.md @@ -83,15 +83,17 @@ your `MaterialApp` or `CupertinoApp`: ```dart -import 'package:flutter_localizations/flutter_localizations.dart' as - flutter_localizations; +import 'package:flutter_localizations/flutter_localizations.dart' + as flutter_localizations; ``` ```dart return const MaterialApp( title: 'Localizations Sample App', - localizationsDelegates: GlobalMaterialLocalizations.delegates, + localizationsDelegates: [ + ...GlobalMaterialLocalizations.delegate, + ], supportedLocales: [ Locale('en'), // English Locale('es'), // Spanish @@ -281,8 +283,8 @@ dependencies: return const MaterialApp( title: 'Localizations Sample App', localizationsDelegates: [ - AppLocalizations.delegate, // Add this delegate - ...GlobalMaterialLocalizations.delegates, + AppLocalizations.delegate, // Add this line + ...GlobalMaterialLocalizations.delegate, ], supportedLocales: [ Locale('en'), // English @@ -1148,7 +1150,8 @@ adds the `NnMaterialLocalizations` delegate instance to the app's ```dart const MaterialApp( localizationsDelegates: [ - ...GlobalMaterialLocalizations.delegates, + GlobalWidgetsLocalizations.delegate, + GlobalMaterialLocalizations.delegate, NnMaterialLocalizations.delegate, // Add the newly created delegate ], supportedLocales: [Locale('en', 'US'), Locale('nn')], From c4e439e9811171f4ee0f1269bf9797202c490797 Mon Sep 17 00:00:00 2001 From: Justin McCandless Date: Mon, 10 Aug 2026 15:39:00 -0700 Subject: [PATCH 5/5] Code review --- .../gen_l10n_example/lib/examples.dart | 2 +- .../gen_l10n_example/lib/main.dart | 2 +- .../lib/no_app_localizations.dart | 89 +++++++++++++++++++ .../content/ui/internationalization/index.md | 17 ++-- 4 files changed, 103 insertions(+), 7 deletions(-) create mode 100644 examples/internationalization/gen_l10n_example/lib/no_app_localizations.dart diff --git a/examples/internationalization/gen_l10n_example/lib/examples.dart b/examples/internationalization/gen_l10n_example/lib/examples.dart index 00c83aa532..80f964e0e5 100644 --- a/examples/internationalization/gen_l10n_example/lib/examples.dart +++ b/examples/internationalization/gen_l10n_example/lib/examples.dart @@ -1,6 +1,6 @@ // ignore_for_file: unused_local_variable -import 'package:flutter/material.dart'; +import 'package:material_ui/material_ui.dart'; import 'l10n/app_localizations.dart'; diff --git a/examples/internationalization/gen_l10n_example/lib/main.dart b/examples/internationalization/gen_l10n_example/lib/main.dart index b3b55db27c..9ab8eb6ed4 100644 --- a/examples/internationalization/gen_l10n_example/lib/main.dart +++ b/examples/internationalization/gen_l10n_example/lib/main.dart @@ -1,4 +1,4 @@ -import 'package:flutter/material.dart'; +import 'package:material_ui/material_ui.dart'; // #docregion localization-delegates-import import 'package:flutter_localizations/flutter_localizations.dart' diff --git a/examples/internationalization/gen_l10n_example/lib/no_app_localizations.dart b/examples/internationalization/gen_l10n_example/lib/no_app_localizations.dart new file mode 100644 index 0000000000..ddbe150b6d --- /dev/null +++ b/examples/internationalization/gen_l10n_example/lib/no_app_localizations.dart @@ -0,0 +1,89 @@ +import 'package:material_ui/material_ui.dart'; + +import 'package:flutter_localizations/flutter_localizations.dart' + as flutter_localizations; + +import 'l10n/app_localizations.dart'; + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + // #docregion material-app + return const MaterialApp( + title: 'Localizations Sample App', + localizationsDelegates: GlobalMaterialLocalizations.delegates, + supportedLocales: [ + Locale('en'), // English + Locale('es'), // Spanish + ], + home: MyHomePage(), + ); + // #enddocregion material-app + } +} + +class MyHomePage extends StatefulWidget { + const MyHomePage({super.key}); + + @override + State createState() => _MyHomePageState(); +} + +class _MyHomePageState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + // The [AppBar] title text should update its message + // according to the system locale of the target platform. + // Switching between English and Spanish locales should + // cause this text to update. + title: Text(AppLocalizations.of(context)!.helloWorld), + ), + body: Center( + child: Column( + mainAxisAlignment: MainAxisAlignment.center, + children: [ + // Add the following code + Localizations.override( + context: context, + locale: const Locale('en'), + // Using a Builder here to get the correct BuildContext. + // Alternatively, you can create a new widget and Localizations.override + // will pass the updated BuildContext to the new widget. + child: Builder( + builder: (context) { + // Examples of internationalized strings. + return Column( + children: [ + // Returns 'Hello John' + Text(AppLocalizations.of(context)!.hello('John')), + // Returns 'no wombats' + Text(AppLocalizations.of(context)!.nWombats(0)), + // Returns '1 wombat' + Text(AppLocalizations.of(context)!.nWombats(1)), + // Returns '5 wombats' + Text(AppLocalizations.of(context)!.nWombats(5)), + // Returns 'he' + Text(AppLocalizations.of(context)!.pronoun('male')), + // Returns 'she' + Text(AppLocalizations.of(context)!.pronoun('female')), + // Returns 'they' + Text(AppLocalizations.of(context)!.pronoun('other')), + ], + ); + }, + ), + ), + ], + ), + ), + ); + } +} + +void main() { + runApp(const MyApp()); +} diff --git a/sites/docs/src/content/ui/internationalization/index.md b/sites/docs/src/content/ui/internationalization/index.md index 89a1a844c7..32af665f40 100644 --- a/sites/docs/src/content/ui/internationalization/index.md +++ b/sites/docs/src/content/ui/internationalization/index.md @@ -57,6 +57,15 @@ in a directory of your choice with the `flutter create` command. $ flutter create ``` +In the near future, Flutter projects will be encouraged to use the `material_ui` +and `cupertino_ui` packages, but the `flutter create` command has not yet been +updated to do this by default. You can get ahead of things and migrate now by +running the following command: + +```console +$ dart fix --apply --code=migrate_design_widgets +``` + To use `flutter_localizations`, add the package as a dependency to your `pubspec.yaml` file, as well as the `intl` package: @@ -87,13 +96,11 @@ import 'package:flutter_localizations/flutter_localizations.dart' as flutter_localizations; ``` - + ```dart return const MaterialApp( title: 'Localizations Sample App', - localizationsDelegates: [ - ...GlobalMaterialLocalizations.delegate, - ], + localizationsDelegates: GlobalMaterialLocalizations.delegates, supportedLocales: [ Locale('en'), // English Locale('es'), // Spanish @@ -103,7 +110,7 @@ return const MaterialApp( ``` After introducing the `flutter_localizations` package and adding the previous -code, the `Material` and `Cupertino` packages should now be correctly localized +code, the `Material` and `Cupertino` libraries should now be correctly localized in one of the supported locales. Widgets should be adapted to the localized messages, along with correct left-to-right or right-to-left layout.