diff --git a/exploration/number-selection.md b/exploration/number-selection.md new file mode 100644 index 0000000000..17774ad0d5 --- /dev/null +++ b/exploration/number-selection.md @@ -0,0 +1,200 @@ +# Selection on Numerical Values + +Status: **Accepted** + +
+ Metadata +
+
Contributors
+
@eemeli
+
First proposed
+
2023-09-06
+
Pull Request
+
#471
+
+
+ +## Objective + +Define how selection on numbers happens. + +## Background + +As discussed by the working group and explicitly identified in +discussion of #457, +there is a need to support multiple types of selection on numeric values in MF2. + +MF1 supported selection on either cardinal plurals or ordinal numbers, +via the `plural` and `selectordinal` selectors. +It also customized this selection beyond the capabilities of `com.ibm.icu.text.PluralRules` +by allowing for explicit value matching and an `offset` parameter. + +As pointed out by @mihnita in particular, +category selection is not always appropriate for selection on a number: +the number may be representing some completely other quantity, +such as a four-digit year or the integer value of an enumerator. + +Furthermore, as pointed out by @ryzokuken +in #457 (comment), +ordinal selection works similarly to plural selection, but uses a separate set of rules +for each locale. +This is visible in English, for example, where plural rules use only `one` and `other` +but ordinal rules use `one` (_1st_, _21st_, etc.), `few` (_2nd_, _22nd_, etc.), +`many` (_3rd_, _23rd_, etc.), and `other` (_4th_, _5th_, etc.). + +Additionally, +MF1 provides `ChoiceFormat` selection based on a complex rule set +(and which allows determining if a number falls into a specific range). + +Both JS and ICU PluralRules implementations provide for determining the plural category +of a range based on its start and end values. +Range-based selectors are not initially considered here. + +## Use-Cases + +As a user, I want to write messages that use the correct plural for +my locale and enables translation to locales that use different rules. + +As a user, I want to write messages that use the correct ordinal for +my locale and enables translation to locales that use different rules. + +As a user, I want to write messages in which the pattern used depends on exactly matching +a numeric value. + +As a user, I want to write messages that mix exact matching and +either plural or ordinal selection in a single message. +> For example: +>``` +>.match {$numRemaining} +>0 {{You have no more chances remaining (exact match)}} +>1 {{You have one more chance remaining (exact match)}} +>one {{You have {$numRemaining} chance remaining (plural)}} +> * {{You have {$numRemaining} chances remaining (plural)}} +>``` + + +## Requirements + +- Enable cardinal plural selection. +- Enable ordinal number selection. +- Enable exact match selection. +- Enable simultaneous "exact match" and either plural or ordinal selection. + > For example, allow variants `[1]` and `[one]` in the same message. +- Selection must support relevant formatting options, such as `minimumFractionDigits`. + > For example, in English the value `1` matches plural rule `one` while the value `1.0` + > matches the plural rule `other` (`*`) +- Encourage developers to provide the formatting options used in patterns to the selector + so that proper selection can be done. + +## Constraints + +ICU MF1 messages using `plural` and `selectordinal` should be representable in MF2. + +## Proposed Design + +Given that we already have a `:number`, +it makes sense to add a `` to it with an option + +```xml +