Improving Intl in Hermes

[neildhar]

Opening this discussion to discuss problems with the Intl implementation, and share our plans for addressing them. We’re aware that the current implementation has missing functionality and bugs on both Android and iOS, and are working towards addressing these while minimizing the cost and disruption to users.

Our current strategy has been to implement Intl on top of the platform APIs available on iOS and Android, with the aim of minimizing the binary size impact. As we’ve expanded the implementation, we’ve found it very difficult to map Intl onto the available APIs, and encountered significant maintenance overhead when building and testing the separate implementations. Our hope is to tackle these shortcomings and provide a better experience for developers with these changes.

On non-Apple platforms, we intend to implement Intl on top of ICU as is done by other engines. This will allow us to provide a complete and compliant implementation that aligns with other engines. On platforms where ICU4C is not available, this will come at significant binary size cost.

While this means that Android apps using Hermes with Intl will incur a large size penalty, the latest versions of Android do provide ICU4C so we expect that penalty to go away once we advance our minimum supported version of Android past API level 31 (unless we have a hard requirement on APIs that are not exposed). We will also continue to support building Hermes without Intl for applications sensitive to size.

On Apple platforms, ICU4C is not readily available. Our current approach using Foundation has run into limitations with the set of features we can support. We are currently planning to instead migrate that code to internally delegate to JavaScriptCore, which allows us to provide Intl without additional binary size cost.

Please share any bugs and limitations with the current implementation that are blocking you from using Hermes. We will prioritize these as we rework Intl.

[ewlsh]

👋 excited to hear Intl is being prioritized as an area for improvement in Hermes.

A big issue for us with Hermes' Intl currently is the lack of support for formatRange. We do a lot of scheduling of "sessions" and need to display time ranges which are localized. We built out formatRange internally for Android (on iOS we still use JSC for now), on iOS we are exploring Hermes so I've also ported the implementation to it.

The timing on this is not particularly ideal given the potential shift to ICU4C, but I've opened #1219 to share the implementation we have internally :)

While this means that Android apps using Hermes with Intl will incur a large size penalty, the latest versions of Android do provide ICU4C so we expect that penalty to go away once we advance our minimum supported version of Android past API level 31 (unless we have a hard requirement on APIs that are not exposed). We will also continue to support building Hermes without Intl for applications sensitive to size.

This is exciting! I'd be curious to understand how much work has been done on this. I think it should be possible to move more of PlatformIntlApple into shared C++ which can then be augmented by both platforms.

On Apple platforms, ICU4C is not readily available. Our current approach using Foundation has run into limitations with the set of features we can support. We are currently planning to instead migrate that code to internally delegate to JavaScriptCore, which allows us to provide Intl without additional binary size cost.

As an alternative suggestion to explore, I'm wondering if you've considered migrating the implementation to Swift? It seems like Apple has focused on adding new ICU features to their Swift implementations instead of the Objective-C ones.

This would continue to rely on an implementation which maps to the platform on iOS, but this seems like it might be possible to support reasonably with Swift's API improvements such as AttributedString and may be preferable to the performance penalty of calling out to JSC on iOS.

Apple has been working on C++/Swift interop via Cmake so it should be feasible to call into Swift from Hermes' C++ code.

We’re aware that the current implementation has missing functionality and bugs on both Android and iOS, and are working towards addressing these while minimizing the cost and disruption to users.

While working on this space I've noticed that some of the unexpected bugs and issues on iOS, Android, etc. stem from gaps in test262 that are unexpected (e.g. we exclude all tests that use const on iOS). I've opened #1220 to start bringing some of our internal fixes for test262 upstream and improving visibility 😄

[ewlsh]

Apple is worked on a unified internationalization implementation for Swift here based on ICU for reference.

[neildhar]

Thanks for sharing this, glad to hear that the new Intl approach will eliminate some of the problems you're facing.

timing on this is not particularly ideal given the potential shift to ICU4C

We haven't started work on the new Intl implementation, so we would still welcome improvements to the existing implementations.

I think it should be possible to move more of PlatformIntlApple into shared C++

This is a great observation, and was an eventual goal when we started writing PlatformIntlApple.

considered migrating the implementation to Swift

It has come up, since there is certainly functionality that is now available in Swift that we cannot use from Obj-C (e.g. #1035). However, it doesn't offer a complete solution to the problem in the way that ICU or JSC would. We would continue to have to try and map JS APIs to what is available from the platform, and create a lot of sharp edges where they are mismatched. This makes the Intl functionality harder for us to develop, and harder for JS developers to use.

In the longer term, we could consider keeping the using implementation or calling into Swift for simple/common operations, but we would have to be very careful to ensure that the implementation remains internally consistent.

[TiStyle]

I'm very excited to read this and will test out new implementations as soon as possible 🙌🏻. Thank you for the update!

[jonathanj]

This is very exciting news for Intl indeed!

Recently becoming frustrated with the lack of support for UnicodePropertyValueExpression in Hermes' regex implementation (see #1027), I started taking a look at implementing this myself. It's pretty clear that the expectation is that you implement this with ICU, the predefined character sets in CoreFoundation are quite a lot more limited than ICU's character properties and property values.

Do you think it would make sense to also use the approach of delegating to JSC for these tasks, or is extending genUnicodeTable.py to generate the character sets from the UCD a better approach?

And maybe a final, more general question, what do you expect the performance ballpark impact to be for work that is delegated to JSC?

[neildhar]

That's an interesting question. I think the guiding principle here will be whether the binary size cost of including it will be prohibitive, as it is with Intl. If the size hit is small, it is preferable to distribute the data with Hermes, since the functionality will work without needing to take a dependency on ICU/JSC.

what do you expect the performance ballpark impact to be

We don't really know yet. While calling out to JSC certainly adds additional overhead, JSC may also have more aggressive caching of Intl data than our current implementation, which could offset the performance penalty. My expectation is that on balance, there is unlikely to be a meaningful regression for the majority of usage. It is also useful to observe that our current Android implementation calls into Java for every operation.

[billomore]

I'm not sure if it's a right place to share it, but since it states

Opening this discussion to discuss problems with the Intl implementation

I'll try my luck here.

I'm trying to use the Intl.RelativeTimeFormat, and it crashes both iOS and Android apps - see repro (works on web, crashes on native). Is this API is still not implemented or do I need to add some flags somewhere?

Also, i18next complains that it has no pluralization rules: i18next::pluralResolver: Your environment seems not to be Intl API compatible, use an Intl.PluralRules polyfill. Will fallback to the compatibilityJSON v3 format handling, so the same question applies.

[tmikov]

When you say it "crashes" do you actually mean that it crashes, or is it throwing a JS exception?

[billomore]

I'm sorry for my noob terminology, but in my world when the app shows a scary red screen and refuses to do anything beyond it, I call it a crash :) while it's a JS exception indeed. Just launch the repro snack I linked and try to launch it on any native platform (works fine on web ofc)

[tmikov]

No judgement, but accurate terminology saves time. It also helps if you share the actual error message along with the location in the source where it happens. I see your repro, but I can't run it, because as a rule we can't use entire React Native apps as reproducers for problems in Hermes (unless absolutely necessary) - we usually require a minimal reproduction in the CLI tool, so we can easily investigate it.

Looking at the repro, is the error you are seeing "TypeError: Cannot read property 'prototype' of undefined" and is it happening on line 9? I am not an expert in Intl (nobody on our team is, unfortunately), but this likely means that our implementation of Intl doesn't support that class.

[tmikov]

I am seriously considering changing the approach and using a JS polyfill instead. For example Intl.js or FormatJS. If we added type annotations, we could gradually improve the performance.

[tmikov]

My tweet on the topic: https://x.com/tmikov/status/1840574681356898472

[jonathanj]

From my point of view, we already have to use a polyfill (we're using FormatJS) with Hermes for various third-party libraries (such as i18next, luxon, etc.) so this may be viable, but I have some concerns based on issues we've run into with the polyfills that could be addressed because it was within reach of app code.

1. How would the issue of bug fixes and/or new APIs be handled if the polyfills were to exist in Hermes instead of application code?

2. A quirk of the polyfills is instantiation performance, which affects app startup speed quite significantly, in our case patching out the check reduced the app start up time by a few dozen seconds, would these being included in Hermes preclude making app-specific workarounds/optimizations like this?

3. How would app code decide which locale to load (and thus potentially bundle)? FormatJS has static and dynamic usage suggestions.

I'm very appreciative that the Hermes team is trying to tackle Intl concerns, implementing and maintaining Intl support seems nightmare-ish to me.

[tmikov]

@jonathanj all very good questions. Nobody on the Hermes team has any experience with FormatJS or Intl.js. I am just assuming that they can work and that we can speed them up. Any help, suggestions, ideas, etc, is appreciated.

How would the issue of bug fixes and/or new APIs be handled if the polyfills were to exist in Hermes instead of application code?

Good question. I am assuming we would periodically sync with upstream. However this may be become tricky if we have modifications, for example for performance. We may also distribute the Intl implementation as a separate optional binary, which can also be updated independently.

A quirk of the polyfills is formatjs/formatjs#4276, which affects app startup speed quite significantly, in our case patching out the check reduced the app start up time by a few dozen seconds, would these being included in Hermes preclude making app-specific workarounds/optimizations like this?

No idea yet. Clearly we cannot have our Intl implementation taking seconds to load, so one way or another we would have to fix this. Unfortunately this might also mean patching FormatJS more heavily.

How would app code decide which locale to load (and thus potentially bundle)?

Again, no idea yet. My initial assumption is that all locales would be bundled, mimicking the behavior of a "real" Intl implementation. About loading locales, I am assuming they are loaded lazily on demand when they are used?

[jonathanj]

@jonathanj all very good questions. Nobody on the Hermes team has any experience with FormatJS or Intl.js. I am just assuming that they can work and that we can speed them up. Any help, suggestions, ideas, etc, is appreciated.

I think that is a reasonable assumption and viable, it would be great to see SH in action!

No idea yet. Clearly we cannot have our Intl implementation taking seconds to load, so one way or another we would have to fix this. Unfortunately this might also mean patching FormatJS more heavily.

One advantage Hermes probably has here is that most of the shouldPolyfill() probes are unnecessary because what needs to be polyfilled and what doesn't is known in advance, my understanding of the slow startup was that the probes per Intl feature, and how deep each feature goes, were costly.

Again, no idea yet. My initial assumption is that all locales would be bundled, mimicking the behavior of a "real" Intl implementation. About loading locales, I am assuming they are loaded lazily on demand when they are used?

If they're all bundled then I suppose it's a matter of activating them on-demand, I suppose.

[SimpleCreations]

Hi. Have there been any developments? This is the 2nd most upvoted thread here 🙂

[tmikov]

We have a tentative plan to base the Intl implementation on N-API, which is a stable ABI. In this way implementations can be provided or maintained by other OSS partners or the community. But even converting to using N-API is a significant amount of work (plus N-API support hasn't landed yet).

[tmikov]

Latest update on this issue. As of this time, Meta is unfortunately unable invest in improving the Intl implementation, because Intl isn't used internally. This isn't a decision by the Hermes team.

As was explained in the initial post, implementing Intl for a mobile device is challenging for the following reasons:

• The platform APIs provided by Android and iOS are simply inadequate for a complete and correct implementation
• Android and iOS do not provide a public ICU4C API
• ICU4C is tens of megabytes large

Perhaps there are good solutions to these problems, but our hands are tied, plus nobody on the Hermes team is an expert in this field.

The end result is that Hermes team is not really able to meaningfully support and maintain Intl. To address this, in the medium term, our plan is to modify the existing Intl implementation to rely on a public stable API like JSI or N-API and to move it to a separate repository, where it can be maintained by motivated partners, the community, or even the React Foundation.

[ChALkeR]

@tmikov with the extensions introduction at https://github.com/facebook/hermes/tree/static_h/API/hermes/extensions, is the long-term plan for Intl to live there, or out-of-the-repo?

[tmikov]

It will be either https://github.com/facebook/hermes/tree/static_h/API/hermes/extensions/contrib or a separate repo, though the latter seems a bit unlikely at the moment, since it is unclear who would maintain the separate repo.

[magrinj]

Thanks for the transparency here. Since the direction seems to be moving Intl toward a stable public API with community maintainers, I wanted to mention one I just made hermes-intl (https://github.com/magrinj/hermes-intl, MIT) in case it’s relevant to the discussion.

It fills in the Intl constructors Hermes doesn’t currently provide, Intl.PluralRules, Intl.RelativeTimeFormat, Intl.ListFormat, and Intl.Locale, through a JSI TurboModule.
Under the hood, it’s a C++ binding over a Rust core using ICU4X with compiled-in CLDR data, so it doesn’t depend on ICU4C or platform APIs.

It’s also intentionally pretty conservative: each constructor is only installed if Intl[name] is undefined, so if Hermes ships its own implementation later, Hermes automatically takes precedence. NumberFormat, DateTimeFormat, and Collator are left completely untouched.

For context, 838/842 test262 intl402 tests pass for those four APIs. The output is identical on iOS and Android, and the native size overhead is around 1.0–1.7 MB per Android ABI, and ~1.2 MB on iOS arm64, with support for 514 locales.

It doesn’t try to solve the harder part yet, the existing NumberFormat, DateTimeFormat, and Collator implementations.

If a community-maintained package is in the direction you had in mind, I’d be interested to know whether something like extensions/contrib or a separate repo would make more sense, and what would make the project more useful in that context.

Let me know !

[tmikov]

Latest update: agents and Opus 5.5 changed the equation. I was just able to complete a full implementation of Intl: https://github.com/tmikov/hermes/tree/hermes-intl . It is an additional plugin that has to be dropped next to Hermes and is automatically recognized.

I am still testing it and working on some improvements, but it is a complete implementation and fully functional.

[oferRounds]

OMG AMAZINGGG

[magrinj]

So you mean, my small library is not really useful anymore https://github.com/magrinj/hermes-intl 😂
BTW, I'm releasing some stuff in the coming days, like supporting Intl in the worklets
Happy to help on something if you need help

[SimpleCreations]

Will there be prebuilt binaries?

[magrinj]

@SimpleCreations Can't speak for the plugin itself, that's Tzvetan's call. In the meantime, hermes-intl ships prebuilt Android and iOS binaries built in CI, so apps don't need a Rust toolchain. It covers PluralRules, RelativeTimeFormat, ListFormat and Locale on React Native 0.86+, and Intl on react-native-worklets runtimes is landing right now. DisplayNames, DurationFormat, Segmenter, Intl.supportedValuesOf, NumberFormat fixes on iOS and picking which locales you ship are in progress too, will. be released soon.

@tmikov if prebuilt binaries for the plugin are on the table, I'd be glad to help with that part, it's the pipeline I already maintain for hermes-intl. And thanks for the credit in THIRD_PARTY_NOTICES.

[longlho]

Coincidentally we also ported formatjs to support hermes https://formatjs.github.io/docs/guides/hermes-intl
There are some caveats w/ ICU4X behaving differently compared to ICU4C/J are documented as well.
I think hermes can also make the decisions on which locale data to bundle since that's adding a non-trivial amount of weights. ECMA-402 constantly debates on what dataset to ship in browsers itself.