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 17 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
235 changes: 173 additions & 62 deletions spec/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,9 @@ The following options and their values are required to be available on the funct
- ([digit size option](#digit-size-options))
- `maximumSignificantDigits`
- ([digit size option](#digit-size-options))
- `trailingZeroDisplay`
- `auto` (default)
- `stripIfInteger`

If the _operand_ of the _expression_ is an implementation-defined type,
such as the _resolved value_ of an _expression_ with a `:number` or `:integer` _annotation_,
Expand All @@ -171,37 +174,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 +280,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 +325,176 @@ 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 _option_ `trailingZeroDisplay` has a value `stripIfInteger` that is useful
for displaying currencies with their fraction digits removed when the fraction
part of the _operand_ is zero.
This is sometimes used in _messages_ to make the displayed value omit the fraction part
automatically.
> For example, this _message_:
> ```
> The special price is {$price :currency trailingZeroDisplay=stripIfInteger}.
> ```
> 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.
> ```

Comment on lines +409 to +426
Copy link
Collaborator

Choose a reason for hiding this comment

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

Nitpick: This seems a bit superfluous as we don't explain other options like this, but I don't object to including it.

Suggested change
The _option_ `trailingZeroDisplay` has a value `stripIfInteger` that is useful
for displaying currencies with their fraction digits removed when the fraction
part of the _operand_ is zero.
This is sometimes used in _messages_ to make the displayed value omit the fraction part
automatically.
> For example, this _message_:
> ```
> The special price is {$price :currency trailingZeroDisplay=stripIfInteger}.
> ```
> 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.
> ```

Copy link
Member Author

Choose a reason for hiding this comment

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

We could put this in the user guide. I included it here because it might otherwise be mysterious.

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`
- `narrowSymbol`
- `symbol` (default)
- `name`
- `code`
- `formal`
- `variant`
- `none` (this is called `hidden` in ICU)
Copy link
Collaborator

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

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

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

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)
- ([digit size option](#digit-size-options))
- `minimumSignificantDigits`
- ([digit size option](#digit-size-options))
- `maximumSignificantDigits`
- ([digit size option](#digit-size-options))
- `trailingZeroDisplay`
- `auto` (default)
- `stripIfInteger`

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 trailingZeroDisplay=stripIfInteger}
> {{{$n :currency currencySign=accounting}}}
> ```
> would be formatted with the resolved options
> `{ currencySign: 'accounting', trailingZeroDisplay: 'stripIfInteger', currency: 'USD' }`.

Copy link
Member

Choose a reason for hiding this comment

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

Question.

It appears reasonable to allow composition of currency with numeric values, eg:

.input {$n :number }
{{{$n :currency currencySign=accounting}}}

or

.input {$n :integer }
{{{$n :currency currencySign=accounting}}}

whereby any options on the numeric functions are ignored for the currency formatting.

Not a blocker, since this can be done later.

Copy link
Member Author

Choose a reason for hiding this comment

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

It is reasonable, but not using the messages in your examples, since $n (if just a number) doesn't have a currency code associated with it. Note that Measure and CurrencyAmount in ICU4J are not subclasses of Number. ICU might choose to treat either as numbers, of course. I'm just pointing out that tuple-types might not work out-of-the-box. In addition, the implementation might resolve the value to a non-currency type:

.input {$c :currency}
.local $discounted = {$c :math subtract=2}
{{{$discounted} might only be a Number...}}

The reverse is also potentially true as well: one could use the :number or :integer formatter or selector against a :currency annotated value, although I can't fathom why you'd want to. Bad Operand might be a blessing in this case.

Note that the options would not be ignored in cases where they overlap (which they do quite significantly and on purpose). The primary differences are the handling of fractional digits, display of the currency symbol, and the handling of sign/currencySign (which might want to be harmonized??).

Mainly, this behavior is up to the implementation, since currency types or tuples might not be on the number/integer menu of types.

.input {$n :number useGrouping=never numberingSystem=Latn}
.local $c = {$n :currency currencyCode=INR}
{{This prints in rupees without lakhs (or other groupings) and with Latin digits: {$c}}}

Copy link
Member

Choose a reason for hiding this comment

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

Sorry, I fat-fingered. I had copied the example, and meant to delete the currencySign option, and instead deleted the currencyCode option!

I had also meant just composition one way, from a number to a currency amount, as you have it:

.input {$n :number useGrouping=never numberingSystem=Latn}
.local $c = {$n :currency currencyCode=INR}
{{This prints in rupees without lakhs (or other groupings) and with Latin digits: {$c}}}

I hadn't meant from a currency amount to a number.

.input {$c :currency}
.local $n = {$c :number useGrouping=never numberingSystem=Latn}
{{This prints just the number part of a currency amount: {$n}}}

#### Selection

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

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

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

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