From 28e1a338d06f3e45264b99a6da0e24ca277988ab Mon Sep 17 00:00:00 2001 From: Job Paardekooper Date: Fri, 30 Jun 2023 11:25:41 -0700 Subject: [PATCH] Update Intl API documentation to include iOS support (#1042) Summary: As discussed in issue https://github.com/facebook/hermes/issues/1035, the documentation of the Intl APIs does not include the current state of the iOS support. This PR adds this information and formats the page to reflect that this page now talks about Android and iOS support and not just Android. Also the "Not yet supported" sections has been removed. The page now only mentions what **is** supported and the limitations of the functionalities that are currently supported. This makes more sense with regard to the still changing specification. Mentioning what is supported automatically means the remaining information from the spec that is not included under "supported" is not currently supported. Pull Request resolved: https://github.com/facebook/hermes/pull/1042 Reviewed By: avp Differential Revision: D47155521 Pulled By: neildhar fbshipit-source-id: c30c51008b734d922aeb5856e805642a3657a8c0 --- doc/IntlAPIs.md | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/doc/IntlAPIs.md b/doc/IntlAPIs.md index 4e8ad3ba704..09225a5c2dc 100644 --- a/doc/IntlAPIs.md +++ b/doc/IntlAPIs.md @@ -3,29 +3,28 @@ id: intl title: Internationalization APIs --- -This document describes the current state of Android implementation of the [ECMAScript Internationalization API Specification](https://tc39.es/ecma402/) (ECMA-402, or `Intl`). ECMA-402 is still evolving and the latest iteration is [7th edition](https://402.ecma-international.org/7.0/) which was published in June 2020. Each new edition is built on top of the last one and adds new capabilities typically as, +This document describes the current state of the Android and iOS implementation of the [ECMAScript Internationalization API Specification](https://tc39.es/ecma402/) (ECMA-402, or `Intl`). ECMA-402 is still evolving and the latest iteration that was taken into account is [7th edition](https://402.ecma-international.org/7.0/) which was published in June 2020. Each new edition is built on top of the last one and adds new capabilities typically as, - New `Intl` service constructors (e.g. `Intl.Collator`, `Intl.NumberFormat` etc.) or extending existing ones by accepting more parameters - New functions or properties in `Intl` objects (e.g. `Intl.Collator.prototype.compare`) - New locale aware functions in standard Javascript object prototypes (e.g. `String.prototype.localeCompare`) -One popular implementation strategy followed by other engines, is to bundle an internationalization framework (typically [ICU](http://site.icu-project.org/)) along with the application package. This guarantees deterministic behaviours at the cost of applications package bloat. We decided to consume the Android platform provided facilities for space efficiency, but at the cost of some variance in behaviours across Android platforms. +One popular implementation strategy followed by other engines, is to bundle an internationalization framework (typically [ICU](http://site.icu-project.org/)) along with the application package. This guarantees deterministic behaviours at the cost of applications package bloat. We decided to consume the Android and iOS platform provided facilities for space efficiency, but at the cost of some variance in behaviours across Android and iOS platforms. This also includes behavioural variations between different versions of Android. # ECMA-402 Compliance -## Supported +## Supported on both platforms - `Intl.Collator` - `Intl.Collator.supportedLocalesOf` - `Intl.Collator.prototype.compare` - `Intl.Collator.prototype.resolvedOptions` -- `Intl.NumberFormat` +- `Intl.NumberFormat`* - `Intl.NumberFormat.supportedLocalesOf` - `Intl.NumberFormat.prototype.format` - - `Intl.NumberFormat.prototype.formatToParts` - `Intl.NumberFormat.prototype.resolvedOptions` -- `Intl.DateTimeFormat` +- `Intl.DateTimeFormat`* - `Intl.DateTimeFormat.supportedLocalesOf` - `Intl.DateTimeFormat.prototype.format` - `Intl.DateTimeFormat.prototype.formatToParts` @@ -49,27 +48,29 @@ One popular implementation strategy followed by other engines, is to bundle an i - `toLocaleDateString` - `toLocaleTimeString` -## Not yet supported - -- [`Intl.PluralRules`](https://tc39.es/ecma402/#pluralrules-objects) +## Supported on Android only +- `Intl.NumberFormat` + - `Intl.NumberFormat.prototype.formatToParts` -- [`Intl.RelativeTimeFormat`](https://tc39.es/ecma402/#relativetimeformat-objects) +## * Limitations on property support -- [`Intl.DisplayNames`](https://tc39.es/proposal-intl-displaynames/#sec-intl-displaynames-constructor) +### Limited iOS property support +- `Intl.NumberFormat` implementation does not support the following properties, + - `notation`: 'compact' + - `notation`: 'engineering' + - `compactDisplay` + - `signDisplay` -- [`Intl.ListFormat`](https://tc39.es/proposal-intl-list-format/#sec-intl-listformat-constructor) +- `Intl.DateTimeFormat` implementation does not support the following properties, + - `numberingSystem` + - [`formatMatcher`](https://tc39.es/ecma402/#sec-basicformatmatcher) -- [`Intl.Locale`](https://tc39.es/ecma402/#sec-intl-locale-constructor) +### Limited Android property support -- `Intl.DateTimeFormat` properties - - [`dateStyle/timeStyle`](https://tc39.es/proposal-intl-datetime-style/) +- `Intl.DateTimeFormat` implementation does not support the following properties, - [`dayPeriod`](https://github.com/tc39/ecma402/issues/29) - [`fractionalSecondDigits`](https://github.com/tc39/ecma402/pull/347) -- [`BigInt.prototype.toLocaleString`](https://tc39.es/ecma402/#sup-bigint.prototype.tolocalestring) - -## Excluded - -- `Intl.DateTimeFormat`: [`formatMatcher`](https://tc39.es/ecma402/#sec-basicformatmatcher) parameter is not respected. The parameter enables the implementation to pick the best display format when it supports only a subset of all possible formats. ICU library in Android platform and hence our implementation allows all subsets and formats which makes this `formatMatcher` property unnecessary. + - [`formatMatcher`](https://tc39.es/ecma402/#sec-basicformatmatcher) The property enables the implementation to pick the best display format when it supports only a subset of all possible formats. ICU library in Android platform and hence our implementation allows all subsets and formats which makes this `formatMatcher` property unnecessary. ## Limitations across Android SDKs @@ -111,6 +112,7 @@ One popular implementation strategy followed by other engines, is to bundle an i - `Intl.NumberFormat`: Unit style does not work. - `Intl.NumberFormat`: There are issues in the precision configuration due to lack of APIs. - `Intl.DateFormat`: There are issues with the calendar configuration which needs to be dug into. + - [`dateStyle/timeStyle`](https://tc39.es/proposal-intl-datetime-style/) is not implemented. ### SDK < 21 and older @@ -157,7 +159,7 @@ In summary, 4. Platform 30 has introduced classes under [`android.icu.number`](https://developer.android.com/reference/android/icu/util/package-summary) namespace which will majorly improve our `Intl.NumberFormat` implementation -# Impact on Application Size +# Impact on Android Application Size The following numbers are measured using a test application which takes dependency on the Hermes library to evaluate a JavaScript snippet. Essentially, enabling Intl APIs adds 57-62K per ABI.