Transition from currency-aware formatting to locale-aware formatting

[fabiocarneiro]

The money2 library currently relies on a "self-sustained" approach where formatting logic and patterns are hardcoded within currency definitions. While there is a shared understanding within the community that currency-based formatting is not ideal, the solution discussed thus far has been to build an internal database of locales.

I propose that we instead adopt the intl package as a core dependency for formatting. While this library will continue to maintain its own dataset of currencies (ISO codes, names, and precision), we should offload the responsibility of locale-specific representation to a dedicated, widely-used localization engine.

The Problem: The Limits of Self-Sustained Logic

The current model treats formatting as a property of the Currency, whereas industry standards treat it as a property of the Locale.

• Incompatibility with Device Settings: Formatting is "locked" at the app or currency level and does not automatically adjust to the user's device settings. A user in Germany and a user in the US viewing the same currency should see different separators (e.g., $1.000,00 vs. $1,000.00), but the library currently forces a static style.
• Diminishing Returns on Heuristics: As seen in PR parse decimal inference #97 ("parse decimal inference"), we have implemented heuristics to improve separator accuracy without breaking backward compatibility. While PR parse decimal inference #97 was a successful stop-gap, it highlights that we are now relying on "guessing" intent. This is inherently more fragile than using a standardized, data-driven locale engine.
• The Maintenance Trap of Localization: While this library must maintain currency-specific data (which is not provided by intl), maintaining a separate database of locales is a massive undertaking. Leveraging intl allows us to focus on financial logic while letting a standard library handle the regional display logic.

Proposed Solution: Standardized Dependency for Formatting

Rather than reinventing the localization wheel, we should leverage the infrastructure provided by the intl package:

1. Adopt intl as the Internal Formatting Engine: Replace custom formatting logic and heuristics with the standard intl library.
2. Preserve the Fowler Pattern: The Money and Currency objects should remain clean Value Objects. Formatting logic should be decoupled into a locale-aware resolver called internally by .format() or .toString().
3. Initialization-Phase Warning: Since it is difficult to distinguish between legacy and new format strings during runtime usage, I propose a warning during library or currency initialization. This informs the developer that the library is moving toward a locale-first model and that the current approach of declaring formats via the currency is being deprecated.

Areas for Discussion: Fallback and Deprecation

• Deprecation Acknowledgment: How should developers acknowledge this shift to silence the initialization warning? (e.g., a global configuration flag like MoneyConfig.acknowledgeLocaleMigration()).
• Fallback Strategy: What should happen if a Locale cannot be automatically detected or resolved?
  • Option A: Fail Initialization: Make intl a hard requirement and throw an error if no valid locale context is found.
  • Option B: Neutral/ISO Fallback: Fallback to a neutral "Safety" format (e.g., USD 1,234.56).
  • Option C: Global Default: Allow a Money.defaultLocale to be defined once at the application level.

[bsutton]

So from recollection intl doesn't support the needed formatting requirements - this needs to be reviewed as a starting point. I'm not certain that I agree that supporting locales directly is a large under taking, provided we can find a reliable source of locale formats. I fallback strategy in selection locale is critical. Ive had problems in other languages causing crashes due to the locale not being available. In theory a locale can change at run time, do we need to worry about this? I suspect this is going to involve major breaking changes - depreciation warnings may not be needed - we need to design the new API, see what it breaks and then make some decisions. As I design philosophy i prefer usability over purity of design. Money2 exists because of a disagreement over this principle - I wanted to add formatting to the core package

…

On Sat, 10 Jan 2026, 2:47 am Fábio Carneiro, ***@***.***> wrote: *fabiocarneiro* created an issue (onepub-dev/money.dart#98) <#98> The money library currently relies on a "self-sustained" approach where formatting logic and patterns are hardcoded within currency definitions. While there is a shared understanding within the community that currency-based formatting is not ideal, the solution discussed thus far has been to build an internal database of locales. I propose that we instead adopt the *intl* package as a core dependency for formatting. While this library will continue to maintain its own dataset of currencies (ISO codes, names, and precision), we should offload the responsibility of locale-specific representation to a dedicated, widely-used localization engine. The Problem: The Limits of Self-Sustained Logic The current model treats formatting as a property of the *Currency*, whereas industry standards treat it as a property of the *Locale*. - *Incompatibility with Device Settings:* Formatting is "locked" at the app or currency level and does not automatically adjust to the user's device settings. A user in Germany and a user in the US viewing the same currency should see different separators (e.g., $1.000,00 vs. $1,000.00), but the library currently forces a static style. - *Diminishing Returns on Heuristics:* As seen in *PR #97 <#97> ("parse decimal inference")*, we have implemented heuristics to improve separator accuracy without breaking backward compatibility. While PR #97 <#97> was a successful stop-gap, it highlights that we are now relying on "guessing" intent. This is inherently more fragile than using a standardized, data-driven locale engine. - *The Maintenance Trap of Localization:* While this library must maintain currency-specific data (which is not provided by intl), maintaining a separate database of *locales* is a massive undertaking. Leveraging intl allows us to focus on financial logic while letting a standard library handle the regional display logic. Proposed Solution: Standardized Dependency for Formatting Rather than reinventing the localization wheel, we should leverage the infrastructure provided by the *intl* package: 1. *Adopt intl as the Internal Formatting Engine:* Replace custom formatting logic and heuristics with the standard intl library. 2. *Preserve the Fowler Pattern:* The Money and Currency objects should remain clean Value Objects. Formatting logic should be decoupled into a locale-aware resolver called internally by .format() or .toString(). 3. *Initialization-Phase Warning:* Since it is difficult to distinguish between legacy and new format strings during runtime usage, I propose a *warning during library or currency initialization*. This informs the developer that the library is moving toward a locale-first model and that the current approach of declaring formats via the currency is being deprecated. Areas for Discussion: Fallback and Deprecation - *Deprecation Acknowledgment:* How should developers acknowledge this shift to silence the initialization warning? (e.g., a global configuration flag like MoneyConfig.acknowledgeLocaleMigration()). - *Fallback Strategy:* What should happen if a Locale cannot be automatically detected or resolved? - *Option A: Fail Initialization:* Make intl a hard requirement and throw an error if no valid locale context is found. - *Option B: Neutral/ISO Fallback:* Fallback to a neutral "Safety" format (e.g., USD 1,234.56). - *Option C: Global Default:* Allow a Money.defaultLocale to be defined once at the application level. — Reply to this email directly, view it on GitHub <#98>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG32OHEFZF4BTAJGK5XBND4F7ESXAVCNFSM6AAAAACRGLBZHSVHI2DSMVQWIX3LMV43ASLTON2WKOZTG44TONBSGU2DENI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[fabiocarneiro]

So from recollection intl doesn't support the needed formatting requirements - this needs to be reviewed as a starting point.

It would be nice to document exactly which formatting capability is missing, and perhaps contribute to intl adding this capability there.

I did not mean the formatting had to be done by intl, but that it was possible to obtain the correct separators from that library.

import 'package:intl/intl.dart';

void main() {
    String decimal = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.DECIMAL_SEP;
    String group = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.GROUP_SEP;
    print('Decimal Separator: ${decimal}');
    print('Group Separator: ${group}');
}

I'm not certain that I agree that supporting locales directly is a large under taking, provided we can find a reliable source of locale formats.

It has been 5 years since this was the plan, and no "reliable" source has been found. Maybe intl can be the reliable source? I think it's a huge advantage to be able to rely on a package maintained by the Dart team, such as intl. Any new updates and corrections will automatically be added to this library at no cost.

As a design philosophy, I prefer usability over the purity of design. Money2 exists because of a disagreement over this principle - I wanted to add formatting to the core package

I agree that this library should format the numbers. Formatting a monetary value can be substantially different than formatting a number. For example, abbreviating million to M and billion to B can make perfect sense when you speak about monetary values, but would be completely wrong depending on the context (scientific or technology for example)

The reason I started using this instead of money is that I felt the other one was abandoned, and I don't want to waste time thinking about how to format and parse numbers across the entire codebase.

With that said, I have also seen implementations of money libraries in several languages, and each language has particularities that shape the library in certain ways. For example, Kotlin supports operator overloading, so it does not need the typical Money.add, Money.subtract you find in several languages (as the + and - can operators can do the same). I would see it as a big disadvantage not to support that very convenient language feature, in favor of strictly adhering to an example seen in another language. With that said, there is still some beauty in keeping the standards, and if there is no benefit in deviating from them, then it's just "not invented here" syndrome.

we need to design the new API

Maybe the API doesn't change at all? It could be enough to have a Locale detected by intl and just get the library to use the separators provided by intl, no matter which currency is being used.

[bsutton]

The separators aren't enough, for example in India they use an odd thousand grouping (1000,00.00). There is also the placement of the currency symbol. As to finding a source, at this point now real effort had been put into it. This could be as simple as using one of the other languages as the source.

…

On Sat, 10 Jan 2026, 10:14 am Fábio Carneiro, ***@***.***> wrote: *fabiocarneiro* left a comment (onepub-dev/money.dart#98) <#98 (comment)> So from recollection intl doesn't support the needed formatting requirements - this needs to be reviewed as a starting point. It would be nice to document exactly which formatting capability is missing, and perhaps contribute to intl adding this capability there. I did not mean the formatting had to be done by intl, but that it was possible to obtain the correct separators from that library. import 'package:intl/intl.dart'; void main() { String decimal = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.DECIMAL_SEP; String group = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.GROUP_SEP; print('Decimal Separator: ${decimal}'); print('Group Separator: ${group}'); } I'm not certain that I agree that supporting locales directly is a large under taking, provided we can find a reliable source of locale formats. It has been 5 years, this is a plan, and no "reliable" source has been found. Maybe intl can be the reliable source? I think it's a huge advantage to be able to rely on a package maintained by the Dart team, such as intl. Any new updates and corrections would automatically come to this library at no cost. As a design philosophy, I prefer usability over the purity of design. Money2 exists because of a disagreement over this principle - I wanted to add formatting to the core package I agree that this library should format the numbers. Formatting a monetary value can be substantially different than formatting a number. For example, abbreviating million to M and billion to B can make perfect sense when you speak about monetary values, but would be completely wrong in a regular number. The reason I started using this instead of money is that I felt the other one was abandoned, and I don't want to waste time thinking about how to format and parse numbers across the entire codebase. With that said, I have also seen implementations of money libraries in several languages, and each language has particularities that shape the library in certain ways. For example, Kotlin supports operator overloading, so it does not need the typical Money.add, Money.subtract you find in several languages (as the + and - can operators can do the same). I would see it as a big disadvantage not to support that very convenient language feature, in favor of strictly adhering to an example seen in another language. With that said, there is still some beauty in keeping the standards, and if there is no benefit in deviating from them, then it's just "not invented here" syndrome. we need to design the new API Maybe the API doesn't change at all? It could be enough to have a Locale detected by intl and just get the library to use the separators provided by intl, no matter which currency is being used. — Reply to this email directly, view it on GitHub <#98 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG32OFB53UBVIVOQ52BY6L4GAY4FAVCNFSM6AAAAACRGLBZHSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMZQHEZDGOBRGA> . You are receiving this because you commented.Message ID: <onepub-dev/money .***@***.***>

[bsutton]

The api needs to change. At the minimum you should be able to request a format for a specific locale - the questions is whether these will be breaking. I would prefer to make breaking changes to something that is suboptimal, for what is essential short term backwards compatibility.

…

On Sat, 10 Jan 2026, 10:25 am Brett Sutton, ***@***.***> wrote: The separators aren't enough, for example in India they use an odd thousand grouping (1000,00.00). There is also the placement of the currency symbol. As to finding a source, at this point now real effort had been put into it. This could be as simple as using one of the other languages as the source. On Sat, 10 Jan 2026, 10:14 am Fábio Carneiro, ***@***.***> wrote: > *fabiocarneiro* left a comment (onepub-dev/money.dart#98) > <#98 (comment)> > > So from recollection intl doesn't support the needed formatting > requirements - this needs to be reviewed as a starting point. > > It would be nice to document exactly which formatting capability is > missing, and perhaps contribute to intl adding this capability there. > > I did not mean the formatting had to be done by intl, but that it was > possible to obtain the correct separators from that library. > > import 'package:intl/intl.dart'; > void main() { > String decimal = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.DECIMAL_SEP; > String group = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.GROUP_SEP; > print('Decimal Separator: ${decimal}'); > print('Group Separator: ${group}'); > } > > I'm not certain that I agree that supporting locales directly is a large > under taking, provided we can find a reliable source of locale formats. > > It has been 5 years, this is a plan, and no "reliable" source has been > found. Maybe intl can be the reliable source? I think it's a huge advantage > to be able to rely on a package maintained by the Dart team, such as intl. > Any new updates and corrections would automatically come to this library at > no cost. > > As a design philosophy, I prefer usability over the purity of design. > Money2 exists because of a disagreement over this principle - I wanted to > add formatting to the core package > > I agree that this library should format the numbers. Formatting a > monetary value can be substantially different than formatting a number. For > example, abbreviating million to M and billion to B can make perfect sense > when you speak about monetary values, but would be completely wrong in a > regular number. > > The reason I started using this instead of money is that I felt the other > one was abandoned, and I don't want to waste time thinking about how to > format and parse numbers across the entire codebase. > > With that said, I have also seen implementations of money libraries in > several languages, and each language has particularities that shape the > library in certain ways. For example, Kotlin supports operator overloading, > so it does not need the typical Money.add, Money.subtract you find in > several languages (as the + and - can operators can do the same). I would > see it as a big disadvantage not to support that very convenient language > feature, in favor of strictly adhering to an example seen in another > language. With that said, there is still some beauty in keeping the > standards, and if there is no benefit in deviating from them, then it's > just "not invented here" syndrome. > > we need to design the new API > > Maybe the API doesn't change at all? It could be enough to have a Locale > detected by intl and just get the library to use the separators provided by > intl, no matter which currency is being used. > > — > Reply to this email directly, view it on GitHub > <#98 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AAG32OFB53UBVIVOQ52BY6L4GAY4FAVCNFSM6AAAAACRGLBZHSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMZQHEZDGOBRGA> > . > You are receiving this because you commented.Message ID: > ***@***.***> >

[bsutton]

I think we are agreeing that the API design shirt be dart native rather than trying to adopt ideas from other languages that don't fit. Having said that we should certainly look at other language implementations. For instance the Java money library is well designed.

…

On Sat, 10 Jan 2026, 10:27 am Brett Sutton, ***@***.***> wrote: The api needs to change. At the minimum you should be able to request a format for a specific locale - the questions is whether these will be breaking. I would prefer to make breaking changes to something that is suboptimal, for what is essential short term backwards compatibility. On Sat, 10 Jan 2026, 10:25 am Brett Sutton, ***@***.***> wrote: > The separators aren't enough, for example in India they use an odd > thousand grouping (1000,00.00). > There is also the placement of the currency symbol. > > As to finding a source, at this point now real effort had been put into > it. > This could be as simple as using one of the other languages as the source. > > > On Sat, 10 Jan 2026, 10:14 am Fábio Carneiro, ***@***.***> > wrote: > >> *fabiocarneiro* left a comment (onepub-dev/money.dart#98) >> <#98 (comment)> >> >> So from recollection intl doesn't support the needed formatting >> requirements - this needs to be reviewed as a starting point. >> >> It would be nice to document exactly which formatting capability is >> missing, and perhaps contribute to intl adding this capability there. >> >> I did not mean the formatting had to be done by intl, but that it was >> possible to obtain the correct separators from that library. >> >> import 'package:intl/intl.dart'; >> void main() { >> String decimal = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.DECIMAL_SEP; >> String group = NumberFormat.decimalPattern(Intl.getCurrentLocale()).symbols.GROUP_SEP; >> print('Decimal Separator: ${decimal}'); >> print('Group Separator: ${group}'); >> } >> >> I'm not certain that I agree that supporting locales directly is a large >> under taking, provided we can find a reliable source of locale formats. >> >> It has been 5 years, this is a plan, and no "reliable" source has been >> found. Maybe intl can be the reliable source? I think it's a huge advantage >> to be able to rely on a package maintained by the Dart team, such as intl. >> Any new updates and corrections would automatically come to this library at >> no cost. >> >> As a design philosophy, I prefer usability over the purity of design. >> Money2 exists because of a disagreement over this principle - I wanted to >> add formatting to the core package >> >> I agree that this library should format the numbers. Formatting a >> monetary value can be substantially different than formatting a number. For >> example, abbreviating million to M and billion to B can make perfect sense >> when you speak about monetary values, but would be completely wrong in a >> regular number. >> >> The reason I started using this instead of money is that I felt the >> other one was abandoned, and I don't want to waste time thinking about how >> to format and parse numbers across the entire codebase. >> >> With that said, I have also seen implementations of money libraries in >> several languages, and each language has particularities that shape the >> library in certain ways. For example, Kotlin supports operator overloading, >> so it does not need the typical Money.add, Money.subtract you find in >> several languages (as the + and - can operators can do the same). I would >> see it as a big disadvantage not to support that very convenient language >> feature, in favor of strictly adhering to an example seen in another >> language. With that said, there is still some beauty in keeping the >> standards, and if there is no benefit in deviating from them, then it's >> just "not invented here" syndrome. >> >> we need to design the new API >> >> Maybe the API doesn't change at all? It could be enough to have a Locale >> detected by intl and just get the library to use the separators provided by >> intl, no matter which currency is being used. >> >> — >> Reply to this email directly, view it on GitHub >> <#98 (comment)>, >> or unsubscribe >> <https://github.com/notifications/unsubscribe-auth/AAG32OFB53UBVIVOQ52BY6L4GAY4FAVCNFSM6AAAAACRGLBZHSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMZQHEZDGOBRGA> >> . >> You are receiving this because you commented.Message ID: >> ***@***.***> >> >

[fabiocarneiro]

The separators aren't enough, for example in India they use an odd thousand

I'm very familiar with the grouping in India, having worked with them for many years. You`re referring to Crores and Lakhs.

import 'package:intl/intl.dart';

void main() {
    String locale = Intl.getCurrentLocale();
    String decimal = NumberFormat.decimalPattern(locale).symbols.DECIMAL_SEP;
    String group = NumberFormat.decimalPattern(locale).symbols.GROUP_SEP;
    String pattern = NumberFormat.decimalPattern(locale).symbols.DECIMAL_PATTERN;
    print('Locale: ${locale}');
    print('Decimal Separator: ${decimal}');
    print('Group Separator: ${group}');
    print('Pattern: ${pattern}');
}

// Locale: en_US
// Decimal Separator: .
// Group Separator: ,
// Pattern: #,##0.###

// Locale: en_IN
// Decimal Separator: .
// Group Separator: ,
// Pattern: #,##,##0.###

[bsutton]

Ok, so we are still short of the currency symbol location and positioning of the +/-.

…

On Sat, 10 Jan 2026, 10:45 am Fábio Carneiro, ***@***.***> wrote: *fabiocarneiro* left a comment (onepub-dev/money.dart#98) <#98 (comment)> The separators aren't enough, for example in India they use an odd thousand I'm very familiar with the grouping in India, having worked with them for many years. You`re referring to Crores and Lakhs. import 'package:intl/intl.dart'; void main() { String locale = Intl.getCurrentLocale(); String decimal = NumberFormat.decimalPattern(locale).symbols.DECIMAL_SEP; String group = NumberFormat.decimalPattern(locale).symbols.GROUP_SEP; String pattern = NumberFormat.decimalPattern(locale).symbols.DECIMAL_PATTERN; print('Locale: ${locale}'); print('Decimal Separator: ${decimal}'); print('Group Separator: ${group}'); print('Pattern: ${pattern}'); } // Locale: en_US// Decimal Separator: .// Group Separator: ,// Pattern: #,##0.### // Locale: en_IN// Decimal Separator: .// Group Separator: ,// Pattern: #,##,##0.### — Reply to this email directly, view it on GitHub <#98 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG32OEACK7UEJIFFF3DIE34GA4SNAVCNFSM6AAAAACRGLBZHSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMZRGAYTGNRRHE> . You are receiving this because you commented.Message ID: <onepub-dev/money .***@***.***>

[fabiocarneiro]

They also provide a specific pattern for currencies, which contains the symbol:

import 'package:intl/intl.dart';

void main() {
    String locale = Intl.getCurrentLocale();
    String decimal = NumberFormat.decimalPattern(locale).symbols.DECIMAL_SEP;
    String group = NumberFormat.decimalPattern(locale).symbols.GROUP_SEP;
    String decimalPattern = NumberFormat.decimalPattern(locale).symbols.DECIMAL_PATTERN;
    String currencyPattern = NumberFormat.decimalPattern(locale).symbols.CURRENCY_PATTERN;
    print('Locale: ${locale}');
    print('Decimal Separator: ${decimal}');
    print('Group Separator: ${group}');
    print('Decimal Pattern: ${decimalPattern}');
    print('Currency Pattern: ${currencyPattern}');
}

// Locale: en_US
// Decimal Separator: .
// Group Separator: ,
// Decimal Pattern: #,##0.###
// Currency Pattern: ¤#,##0.00

// Locale: en_IN
// Decimal Separator: .
// Group Separator: ,
// Decimal Pattern: #,##,##0.###
// Currency Pattern: ¤#,##,##0.00

[bsutton]

So that just leaves the -ve sign. Worst case scenario is we use intl to generate a yaml file and then we find another source for the -ve sign. This would allow use to not depend on intl which is somewhat advantageous - I've had quit a bit of problems with dependency conflicts caused by intl over the years.

…

On Sun, 11 Jan 2026, 10:20 pm Fábio Carneiro, ***@***.***> wrote: *fabiocarneiro* left a comment (onepub-dev/money.dart#98) <#98 (comment)> They also provide a specific pattern for currencies: import 'package:intl/intl.dart'; void main() { String locale = Intl.getCurrentLocale(); String decimal = NumberFormat.decimalPattern(locale).symbols.DECIMAL_SEP; String group = NumberFormat.decimalPattern(locale).symbols.GROUP_SEP; String decimalPattern = NumberFormat.decimalPattern(locale).symbols.DECIMAL_PATTERN; String currencyPattern = NumberFormat.decimalPattern(locale).symbols.CURRENCY_PATTERN; print('Locale: ${locale}'); print('Decimal Separator: ${decimal}'); print('Group Separator: ${group}'); print('Decimal Pattern: ${decimalPattern}'); print('Currency Pattern: ${currencyPattern}'); } // Locale: en_US// Decimal Separator: .// Group Separator: ,// Decimal Pattern: #,##0.###// Currency Pattern: ¤#,##0.00 // Locale: en_IN// Decimal Separator: .// Group Separator: ,// Decimal Pattern: #,##,##0.###// Currency Pattern: ¤#,##,##0.00 — Reply to this email directly, view it on GitHub <#98 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG32OGWIVLFOTO3QQ264ML4GIWYDAVCNFSM6AAAAACRGLBZHSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMZUGQYTMNZTGA> . You are receiving this because you commented.Message ID: <onepub-dev/money .***@***.***>