Implement :currency function in the default registry
#915
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -171,37 +171,6 @@ with _options_ on the _expression_ taking priority over any option values of the | |||||||||||||||||||||||||||||||||
| > would be formatted with the resolved options | ||||||||||||||||||||||||||||||||||
| > `{ notation: 'scientific', minimumFractionDigits: '1' }`. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| ##### Default Value of `select` Option | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| The value `plural` is the default for the option `select` | ||||||||||||||||||||||||||||||||||
|
|
@@ -308,37 +277,6 @@ Option values with the following names are however discarded if included in the | |||||||||||||||||||||||||||||||||
| - `maximumFractionDigits` | ||||||||||||||||||||||||||||||||||
| - `minimumSignificantDigits` | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| ##### Default Value of `select` Option | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| The value `plural` is the default for the option `select` | ||||||||||||||||||||||||||||||||||
|
|
@@ -384,6 +322,158 @@ its _resolved value_ contains the implementation-defined integer value | |||||||||||||||||||||||||||||||||
| of the _operand_ of the annotated _expression_, | ||||||||||||||||||||||||||||||||||
| together with the resolved options' values. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| ### The `:currency` function | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| The function `:currency` is a selector and formatter for currency values, | ||||||||||||||||||||||||||||||||||
| which are a specialized form of numeric selection and formatting. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| #### Operands | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| The _operand_ of the `:currency` function can be one of any number of | ||||||||||||||||||||||||||||||||||
| implementation-defined types, | ||||||||||||||||||||||||||||||||||
| each of which contains a numerical `value` and a `currency`; | ||||||||||||||||||||||||||||||||||
| or it can be a [Number Operand](#number-operands), as long as the option | ||||||||||||||||||||||||||||||||||
| `currency` is provided. | ||||||||||||||||||||||||||||||||||
| The option `currency` MUST NOT be used to override the currency of an implementation-defined type. | ||||||||||||||||||||||||||||||||||
| Using this option in such a case results in a _Bad Option_ error. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| The value of the _operand_'s `currency` MUST be either a string containing a | ||||||||||||||||||||||||||||||||||
| valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier) | ||||||||||||||||||||||||||||||||||
| or an implementation-defined currency type. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| A [Number Operand](#number-operands) without a `currency` _option_ results in a _Bad Operand_ error. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| > [!NOTE] | ||||||||||||||||||||||||||||||||||
| > For example, in ICU4J, the type `com.ibm.icu.util.CurrencyAmount` can be used | ||||||||||||||||||||||||||||||||||
| > to set the amount and currency. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| > [!NOTE] | ||||||||||||||||||||||||||||||||||
| > For runtime environments that do not provide a ready-made data structure, | ||||||||||||||||||||||||||||||||||
| > class, or type for currency values, the implementation ought to provide | ||||||||||||||||||||||||||||||||||
| > a data structure, convenience function, or documentation on how to encode | ||||||||||||||||||||||||||||||||||
| > the value and currency code for formatting. | ||||||||||||||||||||||||||||||||||
| > For example, such an implementation might define a "currency operand" | ||||||||||||||||||||||||||||||||||
| > to include a key-value structure with specific keys to be the | ||||||||||||||||||||||||||||||||||
| > local currency operand, which might look like the following: | ||||||||||||||||||||||||||||||||||
| > ```json | ||||||||||||||||||||||||||||||||||
| > { | ||||||||||||||||||||||||||||||||||
| > "value": 123.45, | ||||||||||||||||||||||||||||||||||
| > "currency": "EUR" | ||||||||||||||||||||||||||||||||||
| > } | ||||||||||||||||||||||||||||||||||
| > ``` | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| #### Options | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| Some options do not have default values defined in this specification. | ||||||||||||||||||||||||||||||||||
| The defaults for these options are implementation-dependent. | ||||||||||||||||||||||||||||||||||
| In general, the default values for such options depend on the locale, | ||||||||||||||||||||||||||||||||||
| the currency, | ||||||||||||||||||||||||||||||||||
| the value of other options, or all of these. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| Fraction digits for currency values behave differently than for other numeric formatters. | ||||||||||||||||||||||||||||||||||
| The number of fraction digits displayed is usually set by the currency used. | ||||||||||||||||||||||||||||||||||
| For example, USD uses 2 fraction digits, while JPY uses none. | ||||||||||||||||||||||||||||||||||
| Setting some other number of `fractionDigits` allows greater precision display | ||||||||||||||||||||||||||||||||||
| (such as when performing currency conversions or other specialized operations) | ||||||||||||||||||||||||||||||||||
| or disabling fraction digits if set to `0`. | ||||||||||||||||||||||||||||||||||
| The special _option_ _value_ `hideIfWhole` is used to display values without | ||||||||||||||||||||||||||||||||||
| fraction digits when the number of fraction digits is zero, | ||||||||||||||||||||||||||||||||||
| or based on the currency when the number of fraction digits for the currency is non-zero. | ||||||||||||||||||||||||||||||||||
| > For example, this _message_: | ||||||||||||||||||||||||||||||||||
| > ``` | ||||||||||||||||||||||||||||||||||
| > The special price is {$price :currency fractionDigits=hideIfWhole}. | ||||||||||||||||||||||||||||||||||
| > ``` | ||||||||||||||||||||||||||||||||||
| > When used with the value `5.00 USD` in the `en-US` locale displays as: | ||||||||||||||||||||||||||||||||||
| > ``` | ||||||||||||||||||||||||||||||||||
| > The special price is $5. | ||||||||||||||||||||||||||||||||||
| > ``` | ||||||||||||||||||||||||||||||||||
| > But like this when when value is `5.01 USD`: | ||||||||||||||||||||||||||||||||||
| > ``` | ||||||||||||||||||||||||||||||||||
| > The special price is $5.01. | ||||||||||||||||||||||||||||||||||
| > ``` | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| Implementations MAY internally alias option values that they do not have data or a backing implementation for. | ||||||||||||||||||||||||||||||||||
| Notably, the `currencyDisplay` option has a rich set of values that mirrors developments in CLDR data. | ||||||||||||||||||||||||||||||||||
| Some implementations might not be able to produce all of these formats for every currency. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| > [!NOTE] | ||||||||||||||||||||||||||||||||||
| > Except where noted otherwise, the names of _options_ and their _values_ were derived from the | ||||||||||||||||||||||||||||||||||
| > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) | ||||||||||||||||||||||||||||||||||
| > in JavaScript's `Intl.NumberFormat`. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| > [!NOTE] | ||||||||||||||||||||||||||||||||||
| > The option `select` does not accept the value `ordinal` because selecting | ||||||||||||||||||||||||||||||||||
| > currency values using ordinal rules makes no sense. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| The following options and their values are required to be available on the function `:currency`: | ||||||||||||||||||||||||||||||||||
| - `select` | ||||||||||||||||||||||||||||||||||
| - `plural` (default) | ||||||||||||||||||||||||||||||||||
| - `exact` | ||||||||||||||||||||||||||||||||||
| - `currency` | ||||||||||||||||||||||||||||||||||
| - valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier) | ||||||||||||||||||||||||||||||||||
| (no default) | ||||||||||||||||||||||||||||||||||
aphillips marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
| - `compactDisplay` (this option only has meaning when combined with the option `notation=compact`) | ||||||||||||||||||||||||||||||||||
| - `short` (default) | ||||||||||||||||||||||||||||||||||
| - `long` | ||||||||||||||||||||||||||||||||||
| - `notation` | ||||||||||||||||||||||||||||||||||
| - `standard` (default) | ||||||||||||||||||||||||||||||||||
| - `compact` | ||||||||||||||||||||||||||||||||||
| - `numberingSystem` | ||||||||||||||||||||||||||||||||||
| - valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) | ||||||||||||||||||||||||||||||||||
| (default is locale-specific) | ||||||||||||||||||||||||||||||||||
| - `currencySign` | ||||||||||||||||||||||||||||||||||
| - `accounting` | ||||||||||||||||||||||||||||||||||
| - `standard` (default) | ||||||||||||||||||||||||||||||||||
| - `currencyDisplay` (this option's values are derived from those in ICU [NumberFormatter.UnitWidth](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/number/NumberFormatter.UnitWidth.html)) | ||||||||||||||||||||||||||||||||||
aphillips marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
| - `narrow` | ||||||||||||||||||||||||||||||||||
aphillips marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
| - `short` (default) | ||||||||||||||||||||||||||||||||||
| - `full` | ||||||||||||||||||||||||||||||||||
| - `iso` | ||||||||||||||||||||||||||||||||||
| - `formal` | ||||||||||||||||||||||||||||||||||
| - `variant` | ||||||||||||||||||||||||||||||||||
| - `none` (this is called `hidden` in ICU) | ||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||
| Proposed Above | Intl Equivalent | Suggested | Comments |
|---|---|---|---|
narrow |
narrowSymbol |
narrow |
No need to be extra verbose |
short |
symbol |
symbol |
(default) symbol is consistent with user expectations |
full |
name |
name |
ICU's name is actually FULL_NAME. Can be misleading, e.g. JPY renders as 123,457円 |
iso |
code |
code |
code might be better because some codes are not ISO4217 |
formal |
n/a | formal |
Variations such as TRD => NT$ |
variant |
n/a | variant |
Variations such as the TRY one illustrated above |
none |
n/a | none |
Frequently used for columns of currency values |
Would that rename work for you?
There was a problem hiding this comment.
The rename looks good.
Side note: we should look at having documentation of the equivalent options for Intl and ICU (maybe others). Perhaps on the site rather than the spec.
Outdated
There was a problem hiding this comment.
A somewhat dormant issue exists for adding at least "formal" to JS: tc39/ecma402#643
I'm not really sure about "variant", or what it's a variant of. Looking at the data, it looks like these are for the most part abbreviations, stored as <symbol alt="variant">. Would therefore "variantSymbol" maybe make more sense? That also more clearly implies what the fallback behaviour might be if a variant is not available (as is most often the case).
I have no opinions about "none" or "hidden", as neither is available in JS and neither term is used in any of the existing JS formatters.
Overall, I would prefer to leave out these option values, but I don't strongly object to them either.
Ping @sffc and @ryzokuken about this, in case you have thoughts on these. As is, we'll need to special-case the handling for this one option in the JS spec, and the values chosen here may end up influencing the corresponding ones for Intl.NumberFormat.
There was a problem hiding this comment.
The variant symbols are often "abbreviation-like", but they really are alternate symbols. The recent fad of creating custom currency symbols unique to a specific currency to some degree corresponds with these symbols. The relationship with formal is kind of unclear. It's a bit clunky, TBH (you can't tell if a currency has a variant and specifying variant in the pattern depends on the currency of the value to some degree).
There was a problem hiding this comment.
Is the fallback behaviour for formatting currencies with no variant documented somewhere?
There was a problem hiding this comment.
Yes, the fallback for each element with alt=... is documented. It is normally the unmarked element (ie, without the alt=...), but in some documented cases (notably locale display names) it may be constructed.
There was a problem hiding this comment.
Note that variant is restricted (currently) to currency symbols.
The usability problem is that when a user writes the source message, she's not going to know about the need for variant. At Amazon, our currency formatter had enums for the presentation format ("in sentence", "standalone", "compact", "iso code", and such) that correspond to specific user interface use cases. Various locale/currency/site configurations then produced the correct symbol/pattern in each of these. This was helpful because it let us do one thing with (e.g.) TRY in the Türkiye site and different thing elsewhere without the developer (or translator) having to know whether a variant existed and, further, whether it was desired or not. Often "what to do" will depend entirely on which currency and which presentation case is wanted
The enums here are taken from NumberFormatter (and Intl.NumberFormat), which are procedural APIs for getting this effect. They are wrong for MessageFormat, I think, because MF is supposed to hide procedural gorp like that. As currently speced, the developer has to want the variant symbol all the time (unlikely) or the translator has to put it there (possibly at odds with the display use case) for specific locales (and not generally knowing the currency). You don't want to have to ever write:
.local $curCode = {$amount :get field=currency}
.match $curCode
TRY {{You have {$amount :currency currencyDisplay=variant} left in your account.}}
UAH {{You have {$amount :currency currencyDisplay=variant} left in your account.}}
NTD {{You have {$amount :currency currencyDisplay=formal} left in your account.}}
* {{You have {$mount :currency} left in your account.}}
aphillips marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment.
While considering #933, I realised that plural selection on currency values depends on being able to introspect the fraction digits which are by default locale-dependent. The ICU FormattedNumber might do that automatically, but in other APIs the operation can get a bit trickier.
There was a problem hiding this comment.
It's not locale-dependent. It's currency dependent. This is why fraction digits are different in this function!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should be left out. This is novel currency formatting behaviour, and we should not be introducing it here via message formatting. Is this already somehow supported in ICU4J and ICU4C? If this makes sense for formatting currencies, wouldn't this also make sense for many other number formatting situations?
I do not object to a value like this in principle, but I object to it being introduced here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This value is supported by ICU.
The use cases for currencies are more common than for other number values (with the possible exception of units). Normally one is trying to get consistent widths (or one doesn't care). With currency values you generally want a specific number of fractional digits or no fraction digits. Mutation of the value to produce this is undesirable.
However, I agree that this is "special sauce" and shouldn't be required here. Should we introduce optional values?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is important for currencies.
As we discussed in the meeting, we should signal that for some of the options it is ok to use defaults if the underlying system doesn't support the choice.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As we allow for implementations to support option values beyond the ones we explicitly define, the easiest way of making this optional is to leave it out for now. This would also more clearly allow for an implementation that did not support "hide if whole" fraction display to emit an error, rather than be required to fail silently.
Could you give me a pointer to how/where this is supported? I could not find this myself.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's defined here: NumberFormatter.TrailingZeroDisplay
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can add the separate option using the Intl spelling. Do you have a list of other options to add?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We're missing the following, which could well be added in a separate PR:
roundingPriorityauto(default)morePrecisionlessPrecisionroundingIncrementroundingModeceilfloorexpandtrunchalfCeilhalfFloorhalfExpand(default)halfTrunchalfEvenThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can't do this right this second, but will add these to this PR. Should they be optional or standard? I'm leaning towards standard.
Almost all of our work between now and 46.1 appears to be fixing up the registry/function set, plus some housekeeping.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm fine either way.
Good!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added. I made them standard.
@mihnita @catamorphism Please note this (proposed) change.