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

Update Intl API documentation to include iOS support #1042

Closed
wants to merge 1 commit into from
Closed

Update Intl API documentation to include iOS support #1042

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
44 changes: 23 additions & 21 deletions doc/IntlAPIs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`*
jobpaardekooper marked this conversation as resolved.
Show resolved Hide resolved
- `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`
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down