Skip to content
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

Jump to bottom

Add <when> to help select the right <match> #558

Closed
wants to merge 7 commits into from
Closed

Add <when> to help select the right <match> #558

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cbc74da
Make Lookup reference more clearly normative by moving it out of the …
eemeli Dec 9, 2023
de75c13
Add <when> to help select the right <match>
eemeli Dec 9, 2023
bacc04c
Add <matches>, with href
eemeli Dec 11, 2023
d2ca815
Apply suggestions from code review
eemeli Dec 11, 2023
3e9e314
Update spec/registry.md
eemeli Dec 11, 2023
56d3362
Update spec/registry.md
eemeli Dec 12, 2023
566b916
Apply suggestions from code review
eemeli Dec 16, 2023
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
15 changes: 13 additions & 2 deletions spec/registry.dtd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
position (open|close|standalone) "standalone"
>

<!ELEMENT matchSignature (input?,option*,match*,override*)>
<!ELEMENT matchSignature (input?,option*,override*,when*,matches?)>

<!ELEMENT input EMPTY>
<!ATTLIST input
Expand All @@ -37,11 +37,22 @@
readonly (true|false) "false"
>

<!ELEMENT matches (match*)>
<!ATTLIST matches
href CDATA #IMPLIED
validationRule IDREF #IMPLIED
>

<!ELEMENT match EMPTY>
<!ATTLIST match
locales NMTOKENS #IMPLIED
values NMTOKENS #IMPLIED
validationRule IDREF #IMPLIED
>

<!ELEMENT when (when*,matches?)>
<!ATTLIST when
option NMTOKEN #REQUIRED
values NMTOKENS #REQUIRED
>

<!ELEMENT override (input?,option*)>
Expand Down
67 changes: 51 additions & 16 deletions spec/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,33 @@ the corresponding input and options rules.
If multiple `<override>` elements would match the current locale,
only the first one is used.

Matching-function signatures additionally include one or more `<match>` elements
to define the keys against which they can match when used as selectors.
### Variant Key Matches

Selector signatures can include `<matches>` and `<when>` elements
defining the variant keys matched by the selector.

Each `<matches>` contains either a (possibly empty) set of `<match>` elements or an `href` attribute.
If `<matches>` contains both an `href` attribute and child elements
the `href` attribute is ignored.
If `<matches>` contains only an `href` attribute, any `validationRule` attributes are ignored.
The `href` attribute MUST resolve to an XML document whose root element is `<matches>`.
The contents of the resolved XML document replaces the current `matches` element for all later processing.

The `<match>` element whose `locales` best matches the current locale
using resource item [lookup](https://unicode.org/reports/tr35/#Lookup) from LDML is used.
An element with no `locales` attribute is the default
(and is considered equivalent to the `root` locale).

In situations where the available keys depend on option values,
`<when>` elements can be used to select an appropriate `<matches>` element for selection.
If the resolved or default value of a selector option
corresponding to the `<when>` `option` attribute
is included in its list of `values`,
its contents are considered before any and all later `<when>` and `<matches>` elements.
If a `<matches>` element within a matching `<when>` has a `<match>` for the current locale,
later `<matches>` outside that `<when>` are not considered.

### Function Aliases

Functions may also include `<alias>` definitions,
which provide shorthands for commonly used option baskets.
Expand Down Expand Up @@ -104,15 +129,25 @@ For the sake of brevity, only `locales="en"` is considered.

<matchSignature>
<input validationRule="anyNumber"/>
<option name="type" values="cardinal ordinal"/>
<option name="select" values="plural ordinal" default="plural"/>
<option name="minimumIntegerDigits" validationRule="positiveInteger"/>
<option name="minimumFractionDigits" validationRule="positiveInteger"/>
<option name="maximumFractionDigits" validationRule="positiveInteger"/>
<option name="minimumSignificantDigits" validationRule="positiveInteger"/>
<option name="maximumSignificantDigits" validationRule="positiveInteger"/>
<!-- Since this applies to both cardinal and ordinal, all plural options are valid. -->
<match locales="en" values="one two few other" validationRule="anyNumber"/>
<match values="zero one two few many other" validationRule="anyNumber"/>
<when option="select" values="plural">
<matches validationRule="anyNumber">
<match locales="en" values="one other"/>
</matches>
</when>
<when option="select" values="ordinal">
<matches validationRule="anyNumber">
<match locales="en" values="one two few other"/>
</matches>
</when>
<matches validationRule="anyNumber">
<match values="zero one two few many other"/>
</matches>
</matchSignature>

<formatSignature>
Expand Down Expand Up @@ -144,18 +179,18 @@ Given the above description, the `:number` function is defined to work both in a
```

Furthermore,
`:number`'s `<matchSignature>` contains two `<match>` elements
`:number`'s `<matchSignature>` contains multiple `<matches>` and `<when>` elements
which allow the validation of variant keys.
The element whose `locales` best matches the current locale
using resource item [lookup](https://unicode.org/reports/tr35/#Lookup) from LDML is used.
An element with no `locales` attribute is the default
(and is considered equivalent to the `root` locale).

- `<match locales="en" values="one two few other" .../>` can be used in locales like `en` and `en-GB`
to validate the `when other` variant by verifying that the `other` key is present
in the list of enumarated values: `one other`.
- `<match ... validationRule="anyNumber"/>` can be used to valide the `when 1` variant
by testing the `1` key against the `anyNumber` regular expression defined in the registry file.
- `<when option="select" values="plural"><matches><match locales="en" values="one other" ... />`
can be used in locales like `en` and `en-GB` if the selection type is known to be plural
to validate that only `one`, `other` or numeric keys are used for variants.
Comment on lines +185 to +187
Copy link
Member

Choose a reason for hiding this comment

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

I think we might want to make these into examples. And I think we might want to avoid "validate that only". Perhaps:

Suggested change
- `<when option="select" values="plural"><matches><match locales="en" values="one other" ... />`
can be used in locales like `en` and `en-GB` if the selection type is known to be plural
to validate that only `one`, `other` or numeric keys are used for variants.
> For example,
> `<when option="select" values="plural"><matches><match locales="en" values="one other" ... />`
> could be used when validating translations for locales such as `en` and `en-GB`
> to check that variant keys `one` and `other` have been provided
> (in addition to any numeric keys).

- `<when option="select" values="ordinal"><matches><match locales="en" values="one two few other" ... />`
can be used in locales like `en` and `en-GB` if the selection type is known to be ordinal
to validate that only `one`, `two`, `few`, `other` or numeric keys are used for variants.
- `<matches validationRule="anyNumber"><match values="zero one two few many other"/>` can be used
for all locales and selection types, validating that variant keys are either numeric
or use one of the plural category identifiers.

---

Expand Down