[package:intl4x] DateTime formatting redesign

[mosuem]

Redesign the date/time/datetime formatting to a builder-like style. This get rid of the custom linking process, as we get a closer mapping to the ICU4X API, and improves usability.

The mapping between this API and the ECMA-style API is not perfect, so the options will need another round of refactorings to get them right. Especially, the share DateTimeFormatOptions object should be either removed completely or at least contain only shared options for all formatters.

cc @sffc as we talked about this kind of API style.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[gemini-code-assist]

Summary of Changes

Hello @mosuem, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces significant API cleanups and refactoring across the Intl4x library. The primary focus is on redesigning the DateTimeFormat API to offer a more fluent and composable approach to date and time formatting, including enhanced control over timezone display. Additionally, the LocaleMatcher concept has been entirely removed from the library, simplifying the overall API surface and reducing configuration overhead for all internationalization features. These changes aim to improve the usability and maintainability of the Intl4x package.

Highlights

• DateTimeFormat API Redesign: The DateTimeFormat class has been significantly refactored. Instead of directly returning formatted strings, methods like d(), m(), y(), ymd(), time(), etc., now return dedicated formatter objects (e.g., DateFormatter, TimeFormatter, DateTimeFormatter). These formatter objects then expose a format(DateTime datetime) method, enabling a more fluent and chainable API for date and time formatting (e.g., intl.dateTimeFormat().d().format(dateTime)).
• Enhanced Time Zone Formatting: New withTimezone methods have been introduced on the new formatter objects (e.g., withTimezoneShort, withTimezoneLong, withTimeZoneShortOffset, etc.). This provides explicit control over how time zones are applied during date and time formatting, allowing for more precise and flexible timezone display options.
• Removal of LocaleMatcher: The LocaleMatcher concept and its associated property have been completely removed from the Intl class and all internationalization feature options (CaseMapping, Collation, DateTimeFormat, DisplayNames, ListFormat, NumberFormat, PluralRules). This simplifies the API by removing a configuration option that was likely redundant or unnecessary for the library's intended use cases, streamlining API calls and reducing complexity.
• Internal Code Simplification: Various internal code cleanups have been performed across the library. This includes the removal of unused imports (e.g., package:meta/meta.dart), deprecated helper functions (e.g., _isUnusedSymbol in hook/link.dart), and general code simplification, contributing to a leaner and more maintainable codebase.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces significant API cleanups, most notably removing the LocaleMatcher parameter from most top-level functions and refactoring the DateTimeFormat API to a more fluent, builder-style pattern. These changes greatly simplify the public API. The refactoring of DateTimeFormat is extensive and introduces a set of Formatter classes, which is a good design. However, I've found a few issues: a critical bug in the ECMA implementation for timezone formatting, some API naming inconsistencies and missing documentation in the new DateTimeFormat API, and some leftover commented-out code and an incomplete comment.

[github-actions]

PR Health

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?
intl4x	Breaking	0.12.2	0.13.0	0.13.0	✔️

This check can be disabled by tagging the PR with skip-breaking-check.

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

Coverage ⚠️

File	Coverage
pkgs/intl4x/example/bin/example.dart	💔 Not covered
pkgs/intl4x/lib/datetime_format.dart	💔 Not covered
pkgs/intl4x/lib/intl4x.dart	💚 100 % ⬆️ 14 %
pkgs/intl4x/lib/src/case_mapping/case_mapping_ecma.dart	💔 Not covered
pkgs/intl4x/lib/src/case_mapping/case_mapping_impl.dart	💚 100 %
pkgs/intl4x/lib/src/case_mapping/case_mapping_stub.dart	💔 0 % ⬇️ NaN %
pkgs/intl4x/lib/src/collation/collation_4x.dart	💚 77 %
pkgs/intl4x/lib/src/collation/collation_ecma.dart	💔 Not covered
pkgs/intl4x/lib/src/collation/collation_impl.dart	💚 100 %
pkgs/intl4x/lib/src/collation/collation_options.dart	💚 9 % ⬆️ 9 %
pkgs/intl4x/lib/src/collation/collation_stub.dart	💔 0 % ⬇️ NaN %
pkgs/intl4x/lib/src/datetime_format/datetime_format.dart	💔 82 % ⬇️ 11 %
pkgs/intl4x/lib/src/datetime_format/datetime_format_ecma.dart	💔 Not covered
pkgs/intl4x/lib/src/datetime_format/datetime_format_impl.dart	💔 85 % ⬇️ 15 %
pkgs/intl4x/lib/src/datetime_format/datetime_format_options.dart	💔 33 % ⬇️ 21 %
pkgs/intl4x/lib/src/datetime_format/datetime_format_stub.dart	💔 0 % ⬇️ NaN %
pkgs/intl4x/lib/src/datetime_format/icu4x/date_formatter.dart	💚 96 %
pkgs/intl4x/lib/src/datetime_format/icu4x/date_time_formatter.dart	💚 95 %
pkgs/intl4x/lib/src/datetime_format/icu4x/datetime_format_4x.dart	💚 90 %
pkgs/intl4x/lib/src/datetime_format/icu4x/time_formatter.dart	💚 9 %
pkgs/intl4x/lib/src/display_names/display_names_ecma.dart	💔 Not covered
pkgs/intl4x/lib/src/display_names/display_names_impl.dart	💚 100 %
pkgs/intl4x/lib/src/display_names/display_names_options.dart	💚 17 % ⬆️ 17 %
pkgs/intl4x/lib/src/display_names/display_names_stub.dart	💔 0 % ⬇️ NaN %
pkgs/intl4x/lib/src/list_format/list_format_ecma.dart	💔 Not covered
pkgs/intl4x/lib/src/list_format/list_format_impl.dart	💚 100 %
pkgs/intl4x/lib/src/list_format/list_format_options.dart	💚 17 % ⬆️ 17 %
pkgs/intl4x/lib/src/list_format/list_format_stub.dart	💔 0 % ⬇️ NaN %
pkgs/intl4x/lib/src/number_format/number_format_4x.dart	💔 91 % ⬇️ 2 %
pkgs/intl4x/lib/src/number_format/number_format_ecma.dart	💔 Not covered
pkgs/intl4x/lib/src/number_format/number_format_impl.dart	💚 100 %
pkgs/intl4x/lib/src/number_format/number_format_options.dart	💚 31 % ⬆️ 1 %
pkgs/intl4x/lib/src/number_format/number_format_stub.dart	💔 0 % ⬇️ NaN %
pkgs/intl4x/lib/src/options.dart	💚 100 % ⬆️ 100 %
pkgs/intl4x/lib/src/plural_rules/plural_rules_ecma.dart	💔 Not covered
pkgs/intl4x/lib/src/plural_rules/plural_rules_impl.dart	💚 100 %
pkgs/intl4x/lib/src/plural_rules/plural_rules_options.dart	💚 22 % ⬆️ 11 %
pkgs/intl4x/lib/src/plural_rules/plural_rules_stub.dart	💔 0 % ⬇️ NaN %
pkgs/intl4x/lib/src/utils.dart	💔 67 % ⬇️ 17 %

This check for test coverage is informational (issues shown here will not fail the PR).

This check can be disabled by tagging the PR with skip-coverage-check.

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources

This check can be disabled by tagging the PR with skip-leaking-check.

License Headers ✔️

// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

This check can be disabled by tagging the PR with skip-license-check.

[github-actions]

Package publishing

Package	Version	Status	Publish tag (post-merge)
package:intl	0.20.3-wip	WIP (no publish necessary)
package:intl4x	0.13.0	ready to publish	intl4x-v0.13.0
package:intl_translation	0.20.1	already published at pub.dev
package:messages_shrinker	0.2.2-wip	WIP (no publish necessary)

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

[mosuem]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant API cleanups, most notably a more fluent, builder-style API for DateTime formatting and the removal of LocaleMatcher from various option classes. The changes are consistent and well-structured, improving the overall API design. I've identified a few areas for improvement, including removing leftover debugging statements, cleaning up commented-out code, and adding documentation to new public APIs to align with the style guide.

[mosuem]

A TBD is also to further remove fields from the DateTimeFormatOptions object until it contains only common options or is gone. WDYT?

[robertbastian]

I think the options should be the union of all options, and then the constructors ignore irrelevant options