Skip to content

Update i18n and material_ui migration docs for Flutter 3.50 - #14111

Open
jesskuras wants to merge 3 commits into
flutter:mainfrom
jesskuras:i18n-material-ui-3.50
Open

jesskuras wants to merge 3 commits into
flutter:mainfrom
jesskuras:i18n-material-ui-3.50

Conversation

@jesskuras

@jesskuras jesskuras commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Part of #14100

Updates the internationalization page and the material_ui / cupertino_ui breaking-change page for Flutter 3.50.

Internationalization page (/ui/internationalization)

  • Remove the outdated statement that flutter create hasn't yet been updated to use material_ui by default. Existing projects are pointed to dart fix --apply --code=migrate_design_widgets and the migration page.
  • Remove the redundant flutter pub add flutter_localizations intl step from the initial setup section (kept in Add your own localized messages, where gen-l10n needs it).
  • Replace the as flutter_localizations prefix import with the material_ui import that the unprefixed GlobalMaterialLocalizations.delegates code relies on, and warn about the ambiguous_import conflict when importing flutter_localizations alongside material_ui or cupertino_ui without show or hide.
  • Clarify delegate choices for CupertinoApp (including when it uses Material widgets) and WidgetsApp ([GlobalWidgetsLocalizations.delegate] with show GlobalWidgetsLocalizations).
  • Add a warning in the gen-l10n steps explaining that AppLocalizations.localizationsDelegates still uses the deprecated flutter_localizations delegates (causing non-English locales to fail at runtime despite the English-only fallback), with the l10n.yaml header workaround pulled in as a code excerpt.
  • Point GlobalMaterialLocalizations API links at the material_ui API docs, point the localization strings README link at flutter/packages's material_ui README, remove the unused [language-count] reference, and fix the Localizations widget link.
  • Explain the show GlobalWidgetsLocalizations import used by the add_language example.

Breaking-change page (/release/breaking-changes/material-ui-and-cupertino-ui)

Examples

Verification

  • dart run dash_site --site=docs refresh-excerpts: no excerpts needed updating.
  • dart run dash_site --site=docs build and check-link-references: pass.
  • Verified against material_ui 1.11.1 / cupertino_ui 1.1.7 sources and the stable flutter_tools templates.

Internationalization page:

- Remove the outdated statement that `flutter create` hasn't yet been
  updated to use `material_ui` by default.
- Replace the `as flutter_localizations` prefix import with the
  `material_ui` import that the unprefixed
  `GlobalMaterialLocalizations.delegates` code actually relies on,
  and warn about the `ambiguous_import` conflict.
- Clarify delegate choices for `CupertinoApp` and `WidgetsApp`.
- Document the current `gen-l10n` limitation with `material_ui`
  and the `l10n.yaml` header workaround.
- Point `GlobalMaterialLocalizations` API links at `material_ui`
  and explain the `hide` import used by the `add_language` example.

material_ui / cupertino_ui breaking-change page:

- Add guidance on resolving `ambiguous_import` errors after
  `dart fix --code=migrate_design_widgets`.
- Note that the compatibility bridges are deprecated by design and
  emit `deprecated_member_use`.
- Note that a `CupertinoApp` rendering `material_ui` widgets needs
  `GlobalMaterialLocalizations.delegates`.
- Document `gen-l10n` status, tracked in flutter/flutter#191072 and
  flutter/flutter#194500.

The `l10n.yaml` header workaround in `gen_l10n_example` is kept until
the `gen-l10n` fix lands in a stable release.

Fixes flutter#14100
@jesskuras
jesskuras requested review from a team and sfshaza2 as code owners November 19, 2026 21:19

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the internationalization documentation and examples to reflect the migration to the standalone material_ui and cupertino_ui packages. It adds instructions on resolving ambiguous imports, handling localizations for CupertinoApp, and working around current limitations with the gen-l10n tool (such as using ignore_for_file: deprecated_member_use and manually building the localizations delegates list). It also updates the relevant code examples with docregion tags for documentation excerpts. I have no feedback to provide as the changes are clear, accurate, and follow the repository style guide.

@flutter-website-bot

flutter-website-bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Staged preview of the updated docs.flutter.dev site (updated for commit 2c9e1b1):

https://flutter-docs-prod--docs-pr14111-i18n-material-ui-3-50-803aztq4.web.app

- Remove the redundant `flutter pub add flutter_localizations intl` step
  from initial setup in `ui/internationalization/index.md`, update the
  `WidgetsApp` note to pass `[GlobalWidgetsLocalizations.delegate]`, and
  cover both `material_ui` and `cupertino_ui` in the `ambiguous_import`
  warning.
- Clarify the `gen-l10n` English-only fallback behavior, mention
  `GlobalCupertinoLocalizations.delegates` for Cupertino-only apps, and
  remind readers to re-run `flutter gen-l10n` after updating `l10n.yaml`.
- Align `add_language/lib/main.dart` to `show GlobalWidgetsLocalizations`
  and link to the `material_ui` localizations README in `flutter/packages`.
- Tighten phrasing across both pages for clarity and natural voice.
@jesskuras
jesskuras requested a review from bkonyi November 19, 2026 22:07
@jesskuras

Copy link
Copy Markdown
Contributor Author

Would you mind taking a look at this PR to fix the issue you submitted, @bkonyi ? Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants