Upgrade react-intl to v5 in frontend-platform

[davidjoy]

We use the react-intl project for internationalization. [https://github.com/formatjs/react-intl|https://github.com/formatjs/react-intl]

It's had a few major releases lately and has a new maintainer - we're currently on ~v2.9 and they recently released v5. I'm a bit concerned about falling much further behind, especially as the new maintainer seems to be actively developing the library and improving it. I think it'd be worth our while to keep up to date, as with most any library that we use (think of the pain around upgrading python and Django, although clearly less intense than that).

I'd like to move forward by updating frontend-platform's implementation to use 5.x, and then releasing it as a breaking change to our library that we can then consume in our MFEs.

I've started attempting to upgrade react-intl on a branch in frontend-platform.

Work is here: [https://github.com/edx/frontend-platform/tree/djoy/react-intl-v5|https://github.com/edx/frontend-platform/tree/djoy/react-intl-v5|smart-link]

There’s a modest set of breaking changes in consuming apps that we’ll have to coordinate fixing. The list was evident from reading react-intl’s upgrade guide; it hasn’t been re-written down anywhere, we’ll have to go familiarize ourselves with it again.

[adamstankiewicz]

A short description of each major, breaking release since the version @edx/frontend-platform is currently on:

3.0.0

Migrating from v2 -> v3 Release notes

• addLocaleData is removed. We'll need to rely on native Intl APIs instead.
• intlShape was removed with the added TypeScript support, where IntlShape is now an interface, since prop-types is no longer used. intlShape is exported by @edx/frontend-platform and used by consumers.
• Change default textComponent in IntlProvider to React.Fragment. In order to keep the old behavior, you can explicitly set textComponent to span.
• FormattedRelative renamed to FormattedRelativeTime, and its API "has been changed significantly". See this documentation for more details.
• formatRelative renamed to formatRelativeTime, and its API "has been changed significantly". See this documentation for more details.
• Message Format syntax changes. See Message Format Syntax Changes for more details.

4.0.0

Migrating from v3 -> v4 Release notes

• All tags must have corresponding values, and will throw error if it's missing, e.g. new IntlMessage("a<b>strong</b>".format({ b: (...chunks) => <strong>chunks</strong> })
• Formatting self-closing tags is not supported.
• XML/HTML tags are escaped using apostrophe just like other ICU constructs.
• Remove dependency on DOMParser and restrictions on void element like <link>. This effectively means you don't need to polyfill DOMParser in Node anymore.
• FormattedHTMLMessage and intl.formatHTMLMessage removed since FormattedMessage now fully supports embedded HTML tag.

5.0.0

Migrating from v4 -> v5 Release notes

• react-intl
  • Fail fast when intl Provider is missing (FormattedMessage has a default English renderer that masks Provider setup issues.
• intl-messageformat
  • Make FormatXMLElementFn non-variadic (function signature changed).

---

My initial reflections on each breaking version.

• 3.0.0:
  • We will need to address the function/Component name changes and removals during the migration.
  • We may need to create our own intlShape export for consumers that rely on it, since we don't use TypeScript.
  • Consumers should adhere to Message Format Syntax Changes.
• 4.0.0
  • New error(s) may be thrown if not all tags have corresponding values.
  • Consumers should verify any escaping behavior on XML/HTML tags.
  • ~Update any usages of FormattedHTMLMessage and intl.formatHTMLMessage.~ The use of these was discouraged by OEP-31 and the Open edX documentation previously, so fortunately it doesn't seem these are actually used anywhere in our platform.
  • Even so, here is the recommended migration guide.
• 5.0.0
  • If react-intl isn't properly configured for an application, previously unseen/masked errors may begin appearing that will need to be addressed. I don't believe this should have much impact for Open edX's existing use of react-intl throughout the platform, though.
  • Consumers may need to address the function signature change, depending on their usage of react-intl.

Examples

Before

new IntlMessageFormat('a<b>strong</b>').format({
  b: (...chunks) => <strong>{chunks}</strong>,
})

<FormattedMessage defaultMessage="a<b>strong</b>">
  {(...chunks) => <b>{chunks}</b>}
</FormattedMessage>

After

new IntlMessageFormat('a<b>strong</b>').format({
  b: chunks => <strong>{chunks}</strong>,
})

<FormattedMessage defaultMessage="a<b>strong</b>">
  {chunks => <b>{chunks}</b>}
</FormattedMessage>

While there will definitely should be some validation done by consumers of @edx/frontend-platform when we complete its upgrade to react-intl@5, it doesn't seem like the breaking changes are too bad.

[adamstankiewicz]

Another thing to check here is on bundle size in @edx/frontend-platform to ensure locales, etc. don't add unnecessary bloat.

[adamstankiewicz]

@edx/frontend-platform has been upgraded to react-intl v5. See release notes.