feat: Get platform locale info and listen to its changes

[ndonkoHenri]

Fixes #3010

Test Code

import flet as ft


async def main(page: ft.Page):
    def format_locales(locales: list[ft.Locale]) -> str:
        """Format locale list for display."""
        return ", ".join(str(loc) for loc in locales)

    def handle_locale_change(e: ft.LocaleChangeEvent):
        page.add(ft.Text(f"Locales changed: {format_locales(e.locales)}"))

    page.on_locale_change = handle_locale_change
    page.scroll = ft.ScrollMode.AUTO
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    initial_locales = (await page.get_device_info()).locales
    page.add(
        ft.Text(f"Initial locales: {format_locales(initial_locales)}"),
        ft.Text(
            "Change your system or browser language to trigger on_locale_change.",
            color=ft.Colors.BLUE,
        ),
    )


ft.run(main)

Summary by Sourcery

Add support for accessing platform locale preferences and reacting to locale changes across Flutter and Python APIs.

New Features:

• Expose ordered device locale list on all platforms via DeviceInfo.locales and underlying Flutter device info mapping.
• Introduce Page.on_locale_change and LocaleChangeEvent to notify apps when host platform locale preferences change.
• Add Locale.language_tag and string formatting to represent locales in BCP47-style and display-friendly forms.
• Provide a Python example demonstrating how to read device locales and handle locale change events.

Enhancements:

• Make DeviceInfo and platform-specific DeviceInfo classes keyword-only dataclasses for clearer, safer initialization.

Documentation:

• Document device locale retrieval and locale change handling in the Page control docs and add API docs for LocaleChangeEvent.

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[cloudflare-workers-and-pages]

Deploying flet-docs with    Cloudflare Pages

Latest commit:	a51cff0
Status:	✅  Deploy successful!
Preview URL:	https://1f610ac8.flet-docs.pages.dev
Branch Preview URL:	https://get-device-locales.flet-docs.pages.dev

View logs

[cloudflare-workers-and-pages]

Deploying flet-examples with    Cloudflare Pages

Latest commit:	a51cff0
Status:	✅  Deploy successful!
Preview URL:	https://b96999d5.flet-examples.pages.dev
Branch Preview URL:	https://get-device-locales.flet-examples.pages.dev

View logs

[Copilot]

Pull request overview

This PR adds support for detecting platform locale information and listening to locale changes in Flet applications, addressing issue #3010. The implementation provides a way to retrieve device locales and react to system language preference changes across all supported platforms.

Changes:

• Added locales field to all DeviceInfo classes to expose system locale preferences
• Implemented LocaleChangeEvent and on_locale_change handler for runtime locale change notifications
• Added language_tag property and __str__ method to the Locale class for better locale string formatting

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
sdk/python/packages/flet/src/flet/controls/types.py	Added language_tag property, __str__ method, and _raw_to_string helper to Locale class for formatting locale identifiers
sdk/python/packages/flet/src/flet/controls/page.py	Added LocaleChangeEvent dataclass and on_locale_change event handler to Page class
sdk/python/packages/flet/src/flet/controls/device_info.py	Added required locales field to all DeviceInfo classes; changed to kw_only=True dataclasses; fixed typo in Windows build lab example (though incorrectly changed)
sdk/python/packages/flet/src/flet/init.py	Exported LocaleChangeEvent class
sdk/python/packages/flet/mkdocs.yml	Added LocaleChangeEvent to documentation navigation
sdk/python/packages/flet/docs/types/localechangeevent.md	Added documentation page for LocaleChangeEvent
sdk/python/packages/flet/docs/controls/page.md	Added reference to device locale example
sdk/python/examples/controls/page/device_locale.py	Added example demonstrating locale retrieval and change detection
packages/flet/lib/src/utils/locale.dart	Added toMap() method to serialize Locale for transmission to Python
packages/flet/lib/src/utils/device_info.dart	Added getDeviceLocales() function and included locales in device info for all platforms
packages/flet/lib/src/controls/page.dart	Implemented didChangeLocales lifecycle method with deduplication to trigger locale change events
.gitignore	Added .fvm/ for Flutter Version Management

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.