chore: Allow dynamic deferred loading of internationalization

build-tools/tasks/generate-i18n-messages.js

@@ -53,7 +53,7 @@ module.exports = function generateI18nMessages() {
   const dynamicFile = [
     `import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
 import { isDevelopment } from '../internal/is-development';
-import { getMatchableLocales } from './get-matchable-locales';
+import { getMatchableLocales } from './utils/locales';
 
 export function importMessages(locale) {
   for (const matchableLocale of getMatchableLocales(locale)) {

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

@@ -26,3 +26,4 @@ export const AppLayoutBottomContentSlot = createWidgetizedAppLayoutBottomContent
 export const AppLayoutWidgetizedState = createWidgetizedAppLayoutState(
   createLoadableComponent(AppLayoutStateImplementation)
 );
+export const loadFormatter = () => Promise.resolve(null);

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

@@ -7,6 +7,7 @@ import { getAnalyticsMetadataAttribute } from '@cloudscape-design/component-tool
 
 import { GeneratedAnalyticsMetadataAppLayoutToolbarComponent } from '../../../app-layout-toolbar/analytics-metadata/interfaces';
 import { BuiltInErrorBoundary } from '../../../error-boundary/internal';
+import RemoteI18nProvider from '../../../i18n/providers/remote-provider';
 import VisualContext from '../../../internal/components/visual-context';
 import customCssProps from '../../../internal/generated/custom-css-properties';
 import { AppLayoutInternalProps, AppLayoutPendingState } from '../interfaces';
@@ -15,6 +16,7 @@ import {
   AppLayoutBeforeMainSlot,
   AppLayoutBottomContentSlot,
   AppLayoutTopContentSlot,
+  loadFormatter,
 } from '../internal';
 import { isWidgetReady } from '../state/invariants';
 import { ToolbarProps } from '../toolbar';
@@ -64,39 +66,41 @@ export const SkeletonLayout = ({
 
   return (
     <VisualContext contextName="app-layout-toolbar">
-      <div
-        {...getAnalyticsMetadataAttribute({ component: componentAnalyticsMetadata })}
-        ref={appLayoutState.rootRef as React.Ref<HTMLDivElement>}
-        data-awsui-app-layout-widget-loaded={isWidgetLoaded}
-        {...wrapperElAttributes}
-        className={wrapperElAttributes?.className ?? clsx(styles.root, testutilStyles.root)}
-        style={
-          wrapperElAttributes?.style ?? {
-            blockSize: `calc(100vh - ${appLayoutProps.placement.insetBlockStart + appLayoutProps.placement.insetBlockEnd}px)`,
-            [customCssProps.navigationWidth]: `${navigationWidth}px`,
-          }
-        }
-      >
-        <AppLayoutBeforeMainSlot {...mergedProps} />
-        <main {...mainElAttributes} className={mainElAttributes?.className ?? styles['main-landmark']}>
-          <AppLayoutTopContentSlot {...mergedProps} />
-          <div
-            {...contentWrapperElAttributes}
-            className={
-              contentWrapperElAttributes?.className ??
-              clsx(styles.main, { [styles['main-disable-paddings']]: appLayoutProps.disableContentPaddings })
+      <RemoteI18nProvider loadFormatter={loadFormatter}>
+        <div
+          {...getAnalyticsMetadataAttribute({ component: componentAnalyticsMetadata })}
+          ref={appLayoutState.rootRef as React.Ref<HTMLDivElement>}
+          data-awsui-app-layout-widget-loaded={isWidgetLoaded}
+          {...wrapperElAttributes}
+          className={wrapperElAttributes?.className ?? clsx(styles.root, testutilStyles.root)}
+          style={
+            wrapperElAttributes?.style ?? {
+              blockSize: `calc(100vh - ${appLayoutProps.placement.insetBlockStart + appLayoutProps.placement.insetBlockEnd}px)`,
+              [customCssProps.navigationWidth]: `${navigationWidth}px`,
             }
-          >
-            {contentHeader && <div {...contentHeaderElAttributes}>{contentHeader}</div>}
-            {/*delay rendering the content until registration of this instance is complete*/}
-            <div {...contentElAttributes} className={contentElAttributes?.className ?? testutilStyles.content}>
-              {registered ? <BuiltInErrorBoundary>{content}</BuiltInErrorBoundary> : null}
+          }
+        >
+          <AppLayoutBeforeMainSlot {...mergedProps} />
+          <main {...mainElAttributes} className={mainElAttributes?.className ?? styles['main-landmark']}>
+            <AppLayoutTopContentSlot {...mergedProps} />
+            <div
+              {...contentWrapperElAttributes}
+              className={
+                contentWrapperElAttributes?.className ??
+                clsx(styles.main, { [styles['main-disable-paddings']]: appLayoutProps.disableContentPaddings })
+              }
+            >
+              {contentHeader && <div {...contentHeaderElAttributes}>{contentHeader}</div>}
+              {/* delay rendering the content until registration of this instance is complete */}
+              <div {...contentElAttributes} className={contentElAttributes?.className ?? testutilStyles.content}>
+                {registered ? <BuiltInErrorBoundary>{content}</BuiltInErrorBoundary> : null}
+              </div>
             </div>
-          </div>
-          <AppLayoutBottomContentSlot {...mergedProps} />
-        </main>
-        <AppLayoutAfterMainSlot {...mergedProps} />
-      </div>
+            <AppLayoutBottomContentSlot {...mergedProps} />
+          </main>
+          <AppLayoutAfterMainSlot {...mergedProps} />
+        </div>
+      </RemoteI18nProvider>
     </VisualContext>
   );
 };

src/i18n/provider.tsx

@@ -1,158 +1,30 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-
-import React, { useContext } from 'react';
-import { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
-import IntlMessageFormat from 'intl-messageformat';
-
-import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
+import React from 'react';
 
 import useBaseComponent from '../internal/hooks/use-base-component';
 import { applyDisplayName } from '../internal/utils/apply-display-name';
-import { CustomHandler, FormatFunction, InternalI18nContext } from './context';
-import { getMatchableLocales } from './get-matchable-locales';
+import { LocalI18nProvider } from './providers/local-provider';
+import { I18nMessages } from './utils/i18n-formatter';
 
 export interface I18nProviderProps {
-  messages: ReadonlyArray<I18nProviderProps.Messages>;
   locale?: string;
+  messages: ReadonlyArray<I18nMessages>;
   children: React.ReactNode;
 }
 
 export namespace I18nProviderProps {
-  export interface Messages {
-    [namespace: string]: {
-      [locale: string]: {
-        [component: string]: {
-          [key: string]: string | MessageFormatElement[];
-        };
-      };
-    };
-  }
+  export type Messages = I18nMessages;
 }
 
-/**
- * Context to send parent messages down to child I18nProviders. This isn't
- * included in the InternalI18nContext to avoid components from depending on
- * MessageFormatElement types.
- */
-const I18nMessagesContext = React.createContext<I18nProviderProps.Messages>({});
-
-export function I18nProvider({ messages: messagesArray, locale: providedLocale, children }: I18nProviderProps) {
+export function I18nProvider({ locale, messages, children }: I18nProviderProps) {
   useBaseComponent('I18nProvider');
 
-  if (typeof document === 'undefined' && !providedLocale) {
-    warnOnce(
-      'I18nProvider',
-      'An explicit locale was not provided during server rendering. This can lead to a hydration mismatch on the client.'
-    );
-  }
-
-  // The provider accepts an array of configs. We merge parent messages and
-  // flatten the tree early on so that accesses by key are simpler and faster.
-  const parentMessages = useContext(I18nMessagesContext);
-  const messages = mergeMessages([parentMessages, ...messagesArray]);
-
-  let locale: string;
-  if (providedLocale) {
-    // If a locale is explicitly provided, use the string directly.
-    // Locales have a recommended case, but are matched case-insensitively,
-    // so we lowercase it internally.
-    locale = providedLocale.toLowerCase();
-  } else if (typeof document !== 'undefined' && document.documentElement.lang) {
-    // Otherwise, use the value provided in the HTML tag.
-    locale = document.documentElement.lang.toLowerCase();
-  } else {
-    // Lastly, fall back to English.
-    locale = 'en';
-  }
-
-  // Create a per-render cache of messages and IntlMessageFormat instances.
-  // Not memoizing it allows us to reset the cache when the component rerenders
-  // with potentially different locale or messages. We expect this component to
-  // be placed above AppLayout and therefore rerender very infrequently.
-  const localeFormatterCache = new Map<string, IntlMessageFormat>();
-
-  const format: FormatFunction = <ReturnValue, FormatFnArgs extends Record<string, string | number>>(
-    namespace: string,
-    component: string,
-    key: string,
-    provided: ReturnValue,
-    customHandler?: CustomHandler<ReturnValue, FormatFnArgs>
-  ): ReturnValue => {
-    // A general rule in this library is that undefined is basically
-    // treated as "not provided". So even if a user explicitly provides an
-    // undefined value, it will default to i18n provider values.
-    if (provided !== undefined) {
-      return provided;
-    }
-
-    const cacheKey = `${namespace}.${component}.${key}`;
-    let intlMessageFormat: IntlMessageFormat;
-
-    const cachedFormatter = localeFormatterCache.get(cacheKey);
-    if (cachedFormatter) {
-      // If an IntlMessageFormat instance was cached for this locale, just use that.
-      intlMessageFormat = cachedFormatter;
-    } else {
-      // Widen the locale string (e.g. en-GB -> en) until we find a locale
-      // that contains the message we need.
-      let message: string | MessageFormatElement[] | undefined;
-      const matchableLocales = getMatchableLocales(locale);
-      for (const matchableLocale of matchableLocales) {
-        message = messages?.[namespace]?.[matchableLocale]?.[component]?.[key];
-        if (message !== undefined) {
-          break;
-        }
-      }
-
-      // If a message wasn't found, exit early.
-      if (message === undefined) {
-        return provided;
-      }
-
-      // Lazily create an IntlMessageFormat object for this key.
-      intlMessageFormat = new IntlMessageFormat(message, locale);
-      localeFormatterCache.set(cacheKey, intlMessageFormat);
-    }
-
-    if (customHandler) {
-      return customHandler(args => intlMessageFormat.format(args) as string);
-    }
-    // Assuming `T extends string` since a customHandler wasn't provided.
-    return intlMessageFormat.format() as ReturnValue;
-  };
-
   return (
-    <InternalI18nContext.Provider value={{ locale, format }}>
-      <I18nMessagesContext.Provider value={messages}>{children}</I18nMessagesContext.Provider>
-    </InternalI18nContext.Provider>
+    <LocalI18nProvider locale={locale} messages={messages}>
+      {children}
+    </LocalI18nProvider>
   );
 }
 
 applyDisplayName(I18nProvider, 'I18nProvider');
-
-function mergeMessages(sources: ReadonlyArray<I18nProviderProps.Messages>): I18nProviderProps.Messages {
-  const result: I18nProviderProps.Messages = {};
-  for (const messages of sources) {
-    for (const namespace in messages) {
-      if (!(namespace in result)) {
-        result[namespace] = {};
-      }
-      for (const casedLocale in messages[namespace]) {
-        const locale = casedLocale.toLowerCase();
-        if (!(locale in result[namespace])) {
-          result[namespace][locale] = {};
-        }
-        for (const component in messages[namespace][casedLocale]) {
-          if (!(component in result[namespace][locale])) {
-            result[namespace][locale][component] = {};
-          }
-          for (const key in messages[namespace][casedLocale][component]) {
-            result[namespace][locale][component][key] = messages[namespace][casedLocale][component][key];
-          }
-        }
-      }
-    }
-  }
-  return result;
-}

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

@@ -0,0 +1,109 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import React, { useContext } from 'react';
+import { render, waitFor } from '@testing-library/react';
+
+import { I18nProvider } from '../../../../lib/components/i18n';
+import { FormatFunction, InternalI18nContext } from '../../../../lib/components/i18n/context';
+import RemoteI18nProvider from '../../../../lib/components/i18n/providers/remote-provider';
+
+afterEach(() => {
+  jest.restoreAllMocks();
+  document.documentElement.lang = '';
+});
+
+const createMockFormatter = () => {
+  const format: FormatFunction = (_ns: string, _component: string, _key: string, provided: any) => {
+    if (provided !== undefined) {
+      return provided;
+    }
+    return 'mocked string';
+  };
+
+  return { format };
+};
+
+function TestConsumer() {
+  const context = useContext(InternalI18nContext);
+  return <div data-testid="locale">{context?.locale || 'no-context'}</div>;
+}
+
+describe('RemoteI18nProvider', () => {
+  it('loads the formatter and provides the context to the children', async () => {
+    document.documentElement.lang = 'es';
+
+    const loadFormatter = jest.fn().mockResolvedValue(createMockFormatter());
+
+    const { getByTestId } = render(
+      <RemoteI18nProvider loadFormatter={loadFormatter}>
+        <TestConsumer />
+      </RemoteI18nProvider>
+    );
+
+    await waitFor(() => {
+      expect(getByTestId('locale')).toHaveTextContent('es');
+    });
+    expect(loadFormatter).toHaveBeenCalledWith({ locale: 'es' });
+  });
+
+  it('falls back to "en" if a lang isn\'t set on the <html>', async () => {
+    const loadFormatter = jest.fn().mockResolvedValue(createMockFormatter());
+
+    const { getByTestId } = render(
+      <RemoteI18nProvider loadFormatter={loadFormatter}>
+        <TestConsumer />
+      </RemoteI18nProvider>
+    );
+
+    await waitFor(() => {
+      expect(getByTestId('locale')).toHaveTextContent('en');
+    });
+    expect(loadFormatter).toHaveBeenCalledWith({ locale: 'en' });
+  });
+
+  it('does nothing when formatter returns null', async () => {
+    const loadFormatter = jest.fn().mockResolvedValue(null);
+
+    const { getByTestId } = render(
+      <RemoteI18nProvider loadFormatter={loadFormatter}>
+        <TestConsumer />
+      </RemoteI18nProvider>
+    );
+
+    await waitFor(() => {
+      expect(loadFormatter).toHaveBeenCalled();
+    });
+    expect(getByTestId('locale')).toHaveTextContent('no-context');
+  });
+
+  it('handles formatter loading errors gracefully', async () => {
+    const loadFormatter = jest.fn().mockRejectedValue(new Error('Network error'));
+
+    const { getByTestId } = render(
+      <RemoteI18nProvider loadFormatter={loadFormatter}>
+        <TestConsumer />
+      </RemoteI18nProvider>
+    );
+
+    await waitFor(() => {
+      expect(loadFormatter).toHaveBeenCalled();
+    });
+    expect(getByTestId('locale')).toHaveTextContent('no-context');
+  });
+
+  it('does not load formatter when wrapped by LocalI18nProvider', () => {
+    const loadFormatter = jest.fn().mockResolvedValue(createMockFormatter());
+
+    const { getByTestId } = render(
+      <I18nProvider messages={[]} locale="en">
+        <RemoteI18nProvider loadFormatter={loadFormatter}>
+          <TestConsumer />
+        </RemoteI18nProvider>
+      </I18nProvider>
+    );
+
+    expect(getByTestId('locale')).toHaveTextContent('en');
+    expect(loadFormatter).not.toHaveBeenCalled();
+  });
+});