Skip to content

Implement :currency function in the default registry #915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 20 commits into from
Nov 14, 2024
Merged

Implement :currency function in the default registry #915

Changes from 14 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
9845582
Implement `:currency` function in the default registry
aphillips Oct 26, 2024
81ded2a
Fix some details
aphillips Oct 26, 2024
ebd8678
Clean up operand
aphillips Oct 26, 2024
cec72a3
Apply suggestions from code review
aphillips Oct 27, 2024
447bf1c
Improve operand, remove excess repeated content
aphillips Oct 27, 2024
c6ba0fd
Eliminate unnecessary extra operand section
aphillips Oct 27, 2024
2217387
Update spec/registry.md
aphillips Oct 27, 2024
241d442
Update spec/registry.md
aphillips Oct 28, 2024
3f855fc
Changes from 2024-10-28 call
aphillips Oct 28, 2024
5b81768
Changes due to 2024-11-04 call
aphillips Nov 4, 2024
d0c37eb
Make `currency` be well-formed
aphillips Nov 5, 2024
bbc7091
Rename `currencyDisplay` values
aphillips Nov 5, 2024
8a9b63f
Update spec/registry.md
aphillips Nov 6, 2024
b27e95f
Define "well-formed" currency code
aphillips Nov 6, 2024
236b781
Update spec/registry.md
aphillips Nov 6, 2024
f3b2872
Add `trailingZeroDisplay` option to :number and :currency
aphillips Nov 6, 2024
e1a1f45
Update spec/registry.md
aphillips Nov 6, 2024
ef98226
Add rounding options to :number and :currency
aphillips Nov 7, 2024
a80c0e2
Implement 2024-11-11 changes
aphillips Nov 12, 2024
c78745d
Merge branch 'main' into aphillips-currency
aphillips Nov 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
227 changes: 165 additions & 62 deletions spec/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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' }`.

> [!NOTE]
> The following options and option values are being developed during the Technical Preview
> period.

The following values for the option `style` are _not_ part of the default registry.
Implementations SHOULD avoid creating options that conflict with these, but
are encouraged to track development of these options during Tech Preview:
- `currency`
- `unit`

The following options are _not_ part of the default registry.
Implementations SHOULD avoid creating options that conflict with these, but
are encouraged to track development of these options during Tech Preview:
- `currency`
- valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier)
(no default)
- `currencyDisplay`
- `symbol` (default)
- `narrowSymbol`
- `code`
- `name`
- `currencySign`
- `accounting`
- `standard` (default)
- `unit`
- (anything not empty)
- `unitDisplay`
- `long`
- `short` (default)
- `narrow`

##### Default Value of `select` Option

The value `plural` is the default for the option `select`
Expand Down Expand Up @@ -308,37 +277,6 @@ Option values with the following names are however discarded if included in the
- `maximumFractionDigits`
- `minimumSignificantDigits`

> [!NOTE]
> The following options and option values are being developed during the Technical Preview
> period.

The following values for the option `style` are _not_ part of the default registry.
Implementations SHOULD avoid creating options that conflict with these, but
are encouraged to track development of these options during Tech Preview:
- `currency`
- `unit`

The following options are _not_ part of the default registry.
Implementations SHOULD avoid creating options that conflict with these, but
are encouraged to track development of these options during Tech Preview:
- `currency`
- valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier)
(no default)
- `currencyDisplay`
- `symbol` (default)
- `narrowSymbol`
- `code`
- `name`
- `currencySign`
- `accounting`
- `standard` (default)
- `unit`
- (anything not empty)
- `unitDisplay`
- `long`
- `short` (default)
- `narrow`

##### Default Value of `select` Option

The value `plural` is the default for the option `select`
Expand Down Expand Up @@ -384,6 +322,171 @@ 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
well-formed [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier)
or an implementation-defined currency type.
Although currency codes are expected to be uppercase,
implementations SHOULD treat them in a case-insensitive manner.
A well-formed Unicode Currency Identifier matches the production `currency_code` in this ABNF:
```abnf
currency_code = 3ALPHA
```

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]
> The `currency` is only required to be well-formed rather than checked for validity.
> This allows new currency codes to be defined
> (there are many recent examples of this occuring).
> It also avoids requiring implementations to check currency codes for validity,
> although implementations are permitted to emit _Bad Option_ or _Bad Operand_ for invalid codes.

> [!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:
> ```
> {
> "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.
Copy link
Collaborator

@eemeli eemeli Nov 5, 2024

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.

Copy link
Member Author

@aphillips aphillips Nov 5, 2024

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?

Copy link
Member

@macchiati macchiati Nov 5, 2024

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.

Copy link
Collaborator

@eemeli eemeli Nov 6, 2024

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.

This value is supported by ICU.

Could you give me a pointer to how/where this is supported? I could not find this myself.

Copy link
Member Author

@aphillips aphillips Nov 6, 2024

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

Copy link
Member Author

@aphillips aphillips Nov 6, 2024

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?

Copy link
Collaborator

@eemeli eemeli Nov 6, 2024

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:

  • roundingPriority
    • auto (default)
    • morePrecision
    • lessPrecision
  • roundingIncrement
    • 1 (default), 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, and 5000
  • roundingMode
    • ceil
    • floor
    • expand
    • trunc
    • halfCeil
    • halfFloor
    • halfExpand (default)
    • halfTrunc
    • halfEven

Copy link
Member Author

@aphillips aphillips Nov 6, 2024

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.

Copy link
Collaborator

@eemeli eemeli Nov 6, 2024

Choose a reason for hiding this comment

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

Should they be optional or standard?

I'm fine either way.

Almost all of our work between now and 46.1 appears to be fixing up the registry/function set, plus some housekeeping.

Good!

Copy link
Member Author

@aphillips aphillips Nov 7, 2024

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.

> 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`
- well-formed [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier)
(no default)
- `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))
- `narrowSymbol`
- `symbol` (default)
- `name`
- `code`
- `formal`
- `variant`
- `none` (this is called `hidden` in ICU)
Copy link
Collaborator

@eemeli eemeli Nov 6, 2024

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

@aphillips aphillips Nov 6, 2024

Choose a reason for hiding this comment

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

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).

Copy link
Collaborator

@eemeli eemeli Nov 6, 2024

Choose a reason for hiding this comment

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

Is the fallback behaviour for formatting currencies with no variant documented somewhere?

Copy link
Member

@macchiati macchiati Nov 6, 2024

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

@aphillips aphillips Nov 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

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.}}

- `useGrouping`
- `auto` (default)
- `always`
- `never`
- `min2`
- `minimumIntegerDigits`
- ([digit size option](#digit-size-options), default: `1`)
- `fractionDigits` (unlike number/integer formats, the fraction digits for currency formatting are fixed)
- `auto` (default) (the number of digits used by the currency)
- `hideIfWhole` (see note above)
- ([digit size option](#digit-size-options))
- `minimumSignificantDigits`
- ([digit size option](#digit-size-options))
- `maximumSignificantDigits`
- ([digit size option](#digit-size-options))

If the _operand_ of the _expression_ is an implementation-defined type,
such as the _resolved value_ of an _expression_ with a `:currency` _annotation_,
it can include option values.
These are included in the resolved option values of the _expression_,
with _options_ on the _expression_ taking priority over any option values of the _operand_.

> For example, the _placeholder_ in this _message_:
> ```
> .input {$n :currency currency=USD fractionDigits=hideIfWhole}
> {{{$n :currency currencySign=accounting}}}
> ```
> would be formatted with the resolved options
> `{ currencySign: 'accounting', fractionDigits: 'hideIfWhole', currency: 'USD' }`.

#### Selection

The _function_ `:currency` performs selection as described in [Number Selection](#number-selection) below.
Copy link
Collaborator

@eemeli eemeli Nov 14, 2024

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

@aphillips aphillips Nov 14, 2024

Choose a reason for hiding this comment

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

It's not locale-dependent. It's currency dependent. This is why fraction digits are different in this function!

Copy link
Member

@macchiati macchiati Nov 14, 2024

Choose a reason for hiding this comment

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

+1


#### Composition

When an _operand_ or an _option_ value uses a _variable_ annotated,
directly or indirectly, by a `:currency` _annotation_,
its _resolved value_ contains an implementation-defined currency value
of the _operand_ of the annotated _expression_,
together with the resolved options' values.

### Number Operands

The _operand_ of a number function is either an implementation-defined type or
Expand Down