chore: Allow dynamic deferred loading of internationalization by avinashbot · Pull Request #4237 · cloudscape-design/components

avinashbot · 2026-02-10T12:33:16Z

Description

Partial implementation of dynamically loaded internationalization. This lets us more readily embed the I18nProvider into performance-sensitive parts of the code (like the app layout toolbar) without worrying so much about added bundle size of the intl library, intl-messageformat (34.3 kB, 9.83 kB gzip) and the locale files (465kB, 68kB gzip). This also avoids dealing with any additional build-time considerations (intl-messageformat raises our bare minimum TypeScript version requirement, which we don't document publicly, though we do call out the raised minimum in our documentation).

The added cost is one asynchronously triggered full-application rerender.

components/LocalI18nProvider  <- The application may provide this already (this is fine)
↳ components/AppLayout
  ↳ components/AppLayout/skeleton
    ↳ components/RemoteI18nProvider <-------+
      ↳ application code                    | 
      ↳ widgetized/AppLayout/toolbar        | --- Once messages and formatter are loaded,
      ↳ widgetized/AppLayout/drawers        |     the content is re-rendered.
    ↳ widgetized/loadRemoteI18nMessages() --+

"Dynamic loading" of the internationalization bundle isn't all that complicated, it's just a runtime import of I18nFormatter (which this PR refactors out) preloaded with the appropriate locale file (which are already exposed under /messages/all.<locale>.js).

Possible optimizations (either later in this PR or after release):

~~Wrapping the app rerender in a React transition: For React versions that support it, it avoids our rerender from blocking user actions and affecting web vitals.~~
Removing ICU parser from the remote bundle (reference): If we can safely guarantee that the remote provider only accepts and handles pre-parsed AST-only strings, we can remove the parser from the dynamically loaded bundle and reduce the dynamic bundle's file size by 26.34 kB (7.1 kB gzip). But this is a non-blocking network request, so it's not high priority. See CR-253557644.

Related links, issue #, if available: AWSUI-61508

How has this been tested?

Existing tests for locally (i.e. application) provided strings, additional tests for remote inclusion of logic will follow.

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

Changes include appropriate documentation updates.
Changes are backward-compatible if not indicated, see CONTRIBUTING.md.
Changes do not include unsupported browser features, see CONTRIBUTING.md.
Changes were manually tested for accessibility, see accessibility guidelines.

Security

If the code handles URLs: all URLs are validated through the checkSafeUrl function.

Testing

Changes are covered with new/existing unit tests?
Changes are covered with new/existing integration tests?

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

codecov · 2026-02-10T17:09:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.43%. Comparing base (69d131d) to head (e999602).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4237   +/-   ##
=======================================
  Coverage   97.43%   97.43%           
=======================================
  Files         897      901    +4     
  Lines       26325    26359   +34     
  Branches     9514     9508    -6     
=======================================
+ Hits        25650    25684   +34     
- Misses        632      669   +37     
+ Partials       43        6   -37

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

georgylobko · 2026-03-03T17:40:16Z

src/app-layout/visual-refresh-toolbar/index.tsx

-      <>
-        <AppLayoutStateProvider
-          forceDeduplicationType={forceDeduplicationType}
+      <RemoteI18nProvider loadFormatter={loadFormatter}>


Why do you need to wrap the whole thing with this provider? We can only wrap SkeletonLayout and call useAriaLabels inside

It seemed cleaner and safer this way. I wasn't sure if the weird "hidden copy of breadcrumbs" thing should also be wrapped by the provider or if it's safe for its strings to not match the skeleton's strings, and if the deduplication breadcrumbs are included, the wrapped component ends up requiring passing along a lot of internal props and state tracking, which seemed unmaintainable to me.

If the breadcrumbs are 100% safe to exclude, I can go for this approach.

georgylobko · 2026-03-03T18:24:28Z

src/i18n/providers/__tests__/remote-provider.test.tsx

+  it('loads the formatter and provides the context to the children', async () => {
+    document.documentElement.lang = 'es';
+
+    const loadFormatter = jest.fn().mockResolvedValue(createMockFormatter());


Why do you provide this function as a prop? Could it be an internal value in the provider?

Not sure what you mean, could you expand? The loadFormatter function is a widget export — locally it just returns null; in production, it would return a promise with a formatter.

I mean, why do you provide this function as a prop for the RemoteI18nProvider? It could be a part of its implementation

It can, but this is better for bundle size (because intl-messageformat is not in the bundle):

RemoteI18nProvider is loaded by the application

loadFormatter is part of the loader (in the application but not this package)

loadFormatter then fetches I18nFormatter from the widget

georgylobko · 2026-03-03T18:32:08Z

src/i18n/providers/__tests__/remote-provider.test.tsx

+  return <div data-testid="locale">{context?.locale || 'no-context'}</div>;
+}
+
+describe('RemoteI18nProvider', () => {


Let's add more realistic scenarios:

what happens with provider's children i18n strings until loadFormatter is loaded?

let's test it with our AppLayout component, especially with dynamically injected content

let's make sure it works correctly if consumers wrap the content area with our i18nprovider

Added some more tests!

georgylobko · 2026-03-03T18:34:26Z

src/i18n/providers/__tests__/remote-provider.test.tsx

+      </RemoteI18nProvider>
+    );
+
+    await waitFor(() => {


[non-blocking] Let's make it more explicit: await jest.runAllTimersAsync() waits until the async function is resolved

georgylobko · 2026-03-03T18:43:22Z

src/i18n/providers/remote-provider.tsx

+        // If formatter isn't available, do nothing.
+      })
+      .catch(() => {
+        // Do nothing. Failure in fetching the formatter should not be fatal.


Do we want to send an operational metric here? same as here: https://github.com/cloudscape-design/components/blob/main/src/app-layout/visual-refresh-toolbar/state/use-app-layout.tsx#L227

Oh absolutely, thanks for the callout; was wishing there was a way we could send a metric with included data. Let me see what the limits are, maybe I can include the error message.

georgylobko · 2026-03-03T18:46:16Z

src/i18n/utils/i18n-formatter.ts

+ * where possible; a new instance must be created if locale or messages may
+ * have changed.
+ */
+export class I18nFormatter {


Should we name it more explicitly like RemoveI18nFormatter and put to the same folder as other widget parts?

It's the common formatting logic — it's imported by both the local provider and the widget (which passes it to remote provider). So it's not specific to either scenario.

avinashbot force-pushed the feat/remote-provider-poc branch 4 times, most recently from 6af9e51 to 65f497e Compare February 10, 2026 16:58

avinashbot deployed to dev-pages-react18 February 10, 2026 17:08 — with GitHub Actions View deployment

avinashbot deployed to dev-pages-react16 February 10, 2026 17:08 — with GitHub Actions View deployment

avinashbot force-pushed the feat/remote-provider-poc branch 2 times, most recently from b380ceb to 107d893 Compare February 12, 2026 10:07

avinashbot deployed to dev-pages-react18 February 12, 2026 10:17 — with GitHub Actions View deployment

avinashbot deployed to dev-pages-react16 February 12, 2026 10:17 — with GitHub Actions View deployment

avinashbot force-pushed the feat/remote-provider-poc branch from 107d893 to a270b41 Compare February 13, 2026 09:05

avinashbot deployed to dev-pages-react18 February 13, 2026 09:15 — with GitHub Actions View deployment

avinashbot deployed to dev-pages-react16 February 13, 2026 09:15 — with GitHub Actions View deployment

avinashbot force-pushed the feat/remote-provider-poc branch from a270b41 to afd8f0a Compare February 17, 2026 16:50

avinashbot deployed to dev-pages-react18 February 17, 2026 17:00 — with GitHub Actions View deployment

avinashbot deployed to dev-pages-react16 February 17, 2026 17:00 — with GitHub Actions View deployment

avinashbot force-pushed the feat/remote-provider-poc branch 2 times, most recently from 91e62bb to 16f6b31 Compare February 27, 2026 13:17

avinashbot deployed to dev-pages-react16 February 27, 2026 13:27 — with GitHub Actions View deployment

avinashbot deployed to dev-pages-react18 February 27, 2026 13:27 — with GitHub Actions View deployment

avinashbot force-pushed the feat/remote-provider-poc branch from 16f6b31 to 3c12e2e Compare February 27, 2026 13:55

avinashbot deployed to dev-pages-react16 February 27, 2026 14:05 — with GitHub Actions View deployment

avinashbot deployed to dev-pages-react18 February 27, 2026 14:05 — with GitHub Actions View deployment

avinashbot marked this pull request as ready for review March 2, 2026 15:17

avinashbot requested a review from a team as a code owner March 2, 2026 15:17

avinashbot requested review from georgylobko and taheramr and removed request for a team March 2, 2026 15:17

georgylobko reviewed Mar 3, 2026

View reviewed changes

avinashbot added 3 commits March 4, 2026 17:10

chore: Allow dynamic deferred loading of internationalization

9836fa9

Ensure AppLayout also receives remote aria labels.

0820977

Add tests that integrate with app layout toolbar.

e999602

avinashbot force-pushed the feat/remote-provider-poc branch from 3c12e2e to e999602 Compare March 4, 2026 17:33

avinashbot requested a review from georgylobko March 4, 2026 17:33

avinashbot deployed to dev-pages-react18 March 4, 2026 17:43 — with GitHub Actions View deployment

avinashbot deployed to dev-pages-react16 March 4, 2026 17:43 — with GitHub Actions View deployment

georgylobko approved these changes Mar 4, 2026

View reviewed changes

Conversation

avinashbot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How has this been tested?

Correctness

Security

Testing

Uh oh!

codecov bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

avinashbot commented Feb 10, 2026 •

edited

Loading

codecov bot commented Feb 10, 2026 •

edited

Loading