Intl resolved options order correction, normalize description (#36056)

* Added `"languageDisplay"` to `resolvedOptions()` of `Intl.DisplayNames` objects * Swapped order of `"style"` and `"type"` properties in Intl.ListFormat's `resolvedOptions()` to match 402 spec * Reordered `Intl.NumberFormat` `resolvedOptions` to reflect spec order. * Reordered `resolvedOptions` properties for `Intl.PluralRules` to reflect spec order * fixup! Added `"languageDisplay"` to `resolvedOptions()` of `Intl.DisplayNames` objects * fixup! Swapped order of `"style"` and `"type"` properties in Intl.ListFormat's `resolvedOptions()` to match 402 spec * Standardize format, first three * Fixes * Swapped order of `"style"` and `"type"` properties in Intl.ListFormat's `resolvedOptions()` to match 402 spec * Reordered `Intl.NumberFormat` `resolvedOptions` to reflect spec order. * Reordered `resolvedOptions` properties for `Intl.PluralRules` to reflect spec order * fixup! Swapped order of `"style"` and `"type"` properties in Intl.ListFormat's `resolvedOptions()` to match 402 spec * Fix others * numberformat --------- Co-authored-by: Joshua Chen <[email protected]>
mdn · Sep 27, 2024 · 643fa96 · 643fa96
1 parent 1c63473
commit 643fa96
Show file tree

Hide file tree

Showing 11 changed files with 132 additions and 266 deletions.
diff --git a/.../web/javascript/reference/global_objects/intl/collator/resolvedoptions/index.md b/.../web/javascript/reference/global_objects/intl/collator/resolvedoptions/index.md
@@ -7,8 +7,7 @@ browser-compat: javascript.builtins.Intl.Collator.resolvedOptions
 
 {{JSRef}}
 
-The **`resolvedOptions()`** method of {{jsxref("Intl.Collator")}} instances returns a new object with properties reflecting the locale and collation options
-computed during initialization of this collator object.
+The **`resolvedOptions()`** method of {{jsxref("Intl.Collator")}} instances returns a new object with properties reflecting the options computed during initialization of this `Collator` object.
 
 {{EmbedInteractiveExample("pages/js/intl-collator-prototype-resolvedoptions.html")}}
 
@@ -24,29 +23,22 @@ None.
 
 ### Return value
 
-A new object with properties reflecting the locale and collation options computed
-during the initialization of the given {{jsxref("Intl.Collator")}} object.
-
-## Description
-
-The resulting object has the following properties:
+A new object with properties reflecting the options computed during the initialization of this `Collator` object. The object has the following properties, in the order they are listed:
 
 - `locale`
-  - : The BCP 47 language tag for the locale actually used. If any Unicode extension
-    values were requested in the input BCP 47 language tag that led to this locale,
-    the key-value pairs that were requested and are supported for this locale are
-    included in `locale`.
-- `usage`, `sensitivity`, `ignorePunctuation`
-  - : The values provided for these properties in the `options` argument or
-    filled in as defaults.
+  - : The BCP 47 language tag for the locale actually used, determined by the [locale negotiation](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation) process. Only the `co`, `kn`, and `kf` Unicode extension keys, if requested and supported, may be included in the output.
+- `usage`
+  - : The value provided for this property in the `options` argument, with default filled in as needed. It is either `"sort"` or `"search"`. The default is `"sort"`.
+- `sensitivity`
+  - : The value provided for this property in the `options` argument, with default filled in as needed. It is either `"base"`, `"accent"`, `"case"`, or `"variant"`. The default is `"variant"` for usage `"sort"`; it's locale dependent for usage `"search"`.
+- `ignorePunctuation`
+  - : The value provided for this property in the `options` argument, with default filled in as needed. It is a boolean. The default is `true` for Thai (`th`) and `false` for all other languages.
 - `collation`
-  - : The value requested using the Unicode extension key `"co"`, if it is
-    supported for `locale`, or `"default"`.
-- `numeric`, `caseFirst`
-  - : The values requested for these properties in the `options` argument or
-    using the Unicode extension keys `"kn"` and `"kf"` or filled
-    in as defaults. If the implementation does not support these properties, they are
-    omitted.
+  - : The value provided for this property in the `options` argument, or using the Unicode extension key `"co"`, with default filled in as needed. It is a supported [collation type](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getCollations#supported_collation_types) for this locale. The default is `"default"`.
+- `numeric`
+  - : The value provided for this property in the `options` argument, or using the Unicode extension key `"kn"`, with default filled in as needed. It is a boolean. The default is `false`. If the implementation does not support this Unicode extension key, this property is omitted.
+- `caseFirst`
+  - : The value provided for this property in the `options` argument, or using the Unicode extension key `"kf"`, with default filled in as needed. It is either `"upper"`, `"lower"`, or `"false"`. The default is `"false"`. If the implementation does not support this Unicode extension key, this property is omitted.
 
 ## Examples
 

diff --git a/...javascript/reference/global_objects/intl/datetimeformat/datetimeformat/index.md b/...javascript/reference/global_objects/intl/datetimeformat/datetimeformat/index.md
@@ -31,7 +31,7 @@ Intl.DateTimeFormat(locales, options)
 
   - : A string with a BCP 47 language tag or an {{jsxref("Intl.Locale")}} instance, or an array of such locale identifiers. The runtime's default locale is used when `undefined` is passed or when none of the specified locale identifiers is supported. For the general form and interpretation of the `locales` argument, see [the parameter description on the `Intl` main page](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
 
-    The following Unicode extension key is allowed:
+    The following Unicode extension keys are allowed:
 
     - `nu`
       - : See [`numberingSystem`](#numberingsystem).

diff --git a/...avascript/reference/global_objects/intl/datetimeformat/resolvedoptions/index.md b/...avascript/reference/global_objects/intl/datetimeformat/resolvedoptions/index.md
@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Intl.DateTimeFormat.resolvedOptions
 
 {{JSRef}}
 
-The **`resolvedOptions()`** method of {{jsxref("Intl.DateTimeFormat")}} instances returns a new object with properties reflecting the locale and date and time formatting options computed during initialization of this `Intl.DateTimeFormat` object.
+The **`resolvedOptions()`** method of {{jsxref("Intl.DateTimeFormat")}} instances returns a new object with properties reflecting the options computed during initialization of this `DateTimeFormat` object.
 
 {{EmbedInteractiveExample("pages/js/intl-datetimeformat-prototype-resolvedoptions.html")}}
 
@@ -23,33 +23,39 @@ None.
 
 ### Return value
 
-A new object with properties reflecting the options computed during the initialization of the given {{jsxref("Intl.DateTimeFormat")}} object. The object has the following properties, in the order they are listed:
+A new object with properties reflecting the options computed during the initialization of this `DateTimeFormat` object. The object has the following properties, in the order they are listed:
 
 - `locale`
-  - : The BCP 47 language tag for the locale actually used. Only the `ca`, `hc`, and `nu` Unicode extension keys may be included in the output.
+  - : The BCP 47 language tag for the locale actually used, determined by the [locale negotiation](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation) process. Only the `ca`, `hc`, and `nu` Unicode extension keys, if requested, may be included in the output.
 - `calendar`
-  - : One of the [supported calendar types](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getCalendars#supported_calendar_types), reflecting the value provided for this property in the `options` argument or the `ca` Unicode extension key. The default is locale dependent.
+  - : The value provided for this property in the `options` argument, or using the Unicode extension key `"ca"`, with default filled in as needed. It is a supported [calendar type](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getCalendars#supported_calendar_types) for this locale. The default is locale dependent.
 - `numberingSystem`
-  - : One of the [supported numbering system types](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getNumberingSystems#supported_numbering_system_types), reflecting the value provided for this property in the `options` argument or the `nu` Unicode extension key. The default is locale dependent.
+  - : The value provided for this property in the `options` argument, or using the Unicode extension key `"nu"`, with default filled in as needed. It is a supported [numbering system](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getNumberingSystems#supported_numbering_system_types) for this locale. The default is locale dependent.
 - `timeZone`
 
-  - : One of the [IANA time zone names](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTimeZones), reflecting the value provided for this property in the `options` argument. The default is the runtime's default time zone; should never be `undefined`.
+  - : The value provided for this property in the `options` argument, with default filled in as needed. It is a canonicalized [IANA time zone name](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTimeZones). The default is the runtime's default time zone.
 
     > [!NOTE]
     > While the IANA database changes from time to time, the Unicode CLDR database (which browsers use) keeps old time zone names for stability purposes. All browsers canonicalize time zone names, but in different directions. For example, `new Intl.DateTimeFormat("en-US", { timeZone: "Europe/Kiev" }).resolvedOptions().timeZone` and `new Intl.DateTimeFormat("en-US", { timeZone: "Europe/Kyiv" }).resolvedOptions().timeZone` will return the same string in the same browser, but maybe different strings in different browsers. See {{jsxref("Intl/Locale/getTimeZones", "Intl.Locale.prototype.getTimeZones")}} for more information.
 
-- `hourCycle`
-  - : The value provided for this property in the `options` argument, or provided in the Unicode extension key `"hc"`, with default filled in as needed. Only present if the `options` argument included `hour` or `timeStyle`.
-- `hour12`
-  - : The value provided for this property in the `options` argument, or computed from the `hourCycle` property. Only present if the `options` argument included `hour` or `timeStyle`.
-- `weekday`, `era`, `year`, `month`, `day`, `dayPeriod`, `hour`, `minute`, `second`, `fractionalSecondDigits`, `timeZoneName`
-  - : The values resulting from format matching between the corresponding properties in the `options` argument and the available combinations and representations for date-time formatting in the selected locale. Some of these properties may not be present, indicating that the corresponding components will not be represented in formatted output. If the `dateStyle` or `timeStyle` shortcuts were used in `options`, these individual component properties will never be present.
-- `dateStyle`, `timeStyle`
-  - : The values provided for these properties in the `options` argument, if any.
+- `hourCycle` {{optional_inline}}
+  - : The value provided for this property in the `options` argument, or using the Unicode extension key `"hc"`, with default filled in as needed. If `hour12` was provided in the `options`, then that overrides other `hourCycle` settings. It is only present if the resolved options also include `hour` or `timeStyle`. It is either `"h11"`, `"h12"`, `"h23"`, or `"h24"`. The default is locale dependent, although `"h24"` is never a default.
+- `hour12` {{optional_inline}}
+  - : Calculated from `hourCycle`. It is only present if the resolved options also include `hour` or `timeStyle`. It is `true` if `hourCycle` is `"h11"` or `"h12"`, and `false` if `hourCycle` is `"h23"` or `"h24"`.
+- `weekday`, `era`, `year`, `month`, `day`, `dayPeriod`, `hour`, `minute`, `second`, `fractionalSecondDigits`, `timeZoneName` {{optional_inline}}
 
-## Description
+  - : The values resulting from format matching between the corresponding properties in the `options` argument and the available combinations and representations for date-time formatting in the selected locale. Some of these properties may not be present, indicating that the corresponding components will not be represented in formatted output. `weekday`, `era`, and `dayPeriod` are either `"narrow"`, `"short"`, or `"long"`; `year`, `day`, `hour`, `minute`, and `second` are either `"numeric"`, `"2-digit"`, or `"narrow"`; `month` is either `"numeric"`, `"2-digit"`, `"narrow"`, `"short"`, or `"long"`; `fractionalSecondDigits` is either `1`, `2`, or `3`; `timeZoneName` is either `"short"`, `"long"`, `"shortOffset"`, `"longOffset"`, `"shortGeneric"`, or `"longGeneric"`.
 
-Although `dateStyle` and `timeStyle` are shortcuts for individual date and time component styles, the exact (locale dependent) component styles they resolve to are not included in the resolved options. This ensures the result of `resolvedOptions()` can be passed directly to the `Intl.DateTimeFormat()` constructor (because an `options` object with both `dateStyle` or `timeStyle` and individual date or time component styles is not valid).
+    If these properties were requested in `options`, the constructor prevents `dateStyle` and `timeStyle` from being specified, so the below group will never be present.
+
+- `dateStyle`, `timeStyle` {{optional_inline}}
+
+  - : The values provided for these properties in the `options` argument. They are either `"full"`, `"long"`, `"medium"`, `"short"`, or `"none"`. Some of these properties may not be present, indicating that the corresponding components will not be represented in formatted output.
+
+    If these properties were requested in `options`, the constructor prevents individual date time component options from being specified, so the above group will never be present.
+
+    > [!NOTE]
+    > Although `dateStyle` and `timeStyle` are shortcuts for individual date and time component styles, the exact (locale dependent) component styles they resolve to are not included in the resolved options. This ensures the result of `resolvedOptions()` can be passed directly to the `Intl.DateTimeFormat()` constructor (because an `options` object with both `dateStyle` or `timeStyle` and individual date or time component styles is not valid).
 
 ## Examples
 

diff --git a/.../javascript/reference/global_objects/intl/displaynames/resolvedoptions/index.md b/.../javascript/reference/global_objects/intl/displaynames/resolvedoptions/index.md
@@ -7,10 +7,7 @@ browser-compat: javascript.builtins.Intl.DisplayNames.resolvedOptions
 
 {{JSRef}}
 
-The **`resolvedOptions()`** method of {{jsxref("Intl.DisplayNames")}} instances
-returns a new object with properties reflecting the locale and style formatting
-options computed during the construction of this `Intl.DisplayNames`
-object.
+The **`resolvedOptions()`** method of {{jsxref("Intl.DisplayNames")}} instances returns a new object with properties reflecting the options computed during initialization of this `DisplayNames` object.
 
 ## Syntax
 
@@ -24,35 +21,18 @@ None.
 
 ### Return value
 
-An object with properties reflecting the locale and formatting options computed during
-the construction of the given {{jsxref("Intl.DisplayNames")}} object.
-
-## Description
-
-The object returned by `resolvedOptions()` has the following properties:
+A new object with properties reflecting the options computed during the initialization of this `DisplayNames` object. The object has the following properties, in the order they are listed:
 
 - `locale`
-  - : The BCP 47 language tag for the locale actually used. If any Unicode extension
-    values were requested in the input BCP 47 language tag that led to this locale,
-    the key-value pairs that were requested and are supported for this locale are
-    included in `locale`.
+  - : The BCP 47 language tag for the locale actually used, determined by the [locale negotiation](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation) process. No Unicode extension key will be included in the output.
 - `style`
-  - : The value provided for this property in the `options` argument of the
-    constructor or the default value (`"long"`). Its value is either
-    `"long"`, `"short"`, or `"narrow"`.
+  - : The value provided for this property in the `options` argument, with default filled in as needed. It is either `"narrow"`, `"short"`, or `"long"`. The default is `"long"`.
 - `type`
-  - : The value provided for this property in the `options` argument of the
-    constructor or the default value (`"language"`). Its value is either
-    `"language"`, `"region"`, `"script"`, or
-    `"currency"`.
+  - : The value provided for this property in the `options` argument. It is either `"language"`, `"region"`, `"script"`, `"currency"`, `"calendar"`, or `"dateTimeField"`. It is required so there is no default.
 - `fallback`
-  - : The value provided for this property in the options argument of the constructor or
-    the default value (`"code"`). Its value is either `"code"`
-    or `"none"`.
+  - : The value provided for this property in the `options` argument. It is either `"code"` or `"none"`. The default is `"code"`.
 - `languageDisplay`
-  - : The value provided for this property in the options argument of the constructor or
-    the default value (`"dialect"`). Its value is either `"dialect"`
-    or `"standard"`.
+  - : The value provided for this property in the `options` argument. It is either `"dialect"` or `"standard"`. The default is `"dialect"`.
 
 ## Examples