feat(useI18nBundle): add new hook to retrieve current i18n bundle (#1104)

* chore(useI18nBundle): add useI18nBundle

* deprecate old hook, update docs & add migration guide

* add test for i18n hook

* early exit test when running in react 16.8.0

Author: MarcusNotheis

docs/2-MigrationGuide.stories.mdx

@@ -14,12 +14,36 @@ or the [changelog](https://github.com/SAP/ui5-webcomponents-react/blob/master/CH
 
 ## Table of Contents
 
+- [0.13.x to 0.14.0](#migrating-from-013x-to-0140)
 - [0.12.x to 0.13.0](#migrating-from-012x-to-0130)
 - [0.11.x to 0.12.0](#migrating-from-011x-to-0120)
 - [0.10.x to 0.11.0](#migrating-from-010x-to-0110)
 - [0.9.x to 0.10.0](#migrating-from-09x-to-0100)
 - [0.8.x to 0.9.0](#migrating-from-08x-to-090)
 
+## Migrating from 0.13.x to 0.14.0
+
+<br />
+
+### Deleted Hooks
+
+The `useI18nText` hook has been removed and replaced by the `useI18nBundle` hook. <br />
+Migration Path:
+
+```js
+import { useI18nText } from '@ui5/webcomponents-react-base/lib/hooks';
+// ...
+const [pleaseWaitText, withParameters] = useI18nText('myApp', 'PLEASE_WAIT', ['CAROUSEL_DOT_TEXT', 5, 20]);
+
+// becomes
+
+import { useI18nBundle } from '@ui5/webcomponents-react-base/lib/hooks';
+// ...
+const i18nBundle = useI18nBundle('myApp');
+const pleaseWaitText = i18nBundle.getText('PLEASE_WAIT');
+const withParameters = i18nBundle.getText('CAROUSEL_DOT_TEXT', 5, 20);
+```
+
 ## Migrating from 0.12.x to 0.13.0
 
 <br />

docs/5-Internationalization.stories.mdx

@@ -67,43 +67,39 @@ _Note:_ This is just asset registration, no data will be fetched at that point.
 Add the following import statement to the component where you want to use translated texts:
 
 ```js
-import { useI18nText } from '@ui5/webcomponents-react-base/lib/hooks';
+import { useI18nBundle } from '@ui5/webcomponents-react-base/lib/hooks';
 ```
 
-Now, you can use the `useI18nText` hook in your functional components in order to get your translated texts.
+Now, you can use the `useI18nBundle` hook in your functional components in order to access the i18nBundle and get your
+translated texts from there.
 
 The hook has the following signature:
 
-```js
-const translatedTextsArray = useI18nText((messageBundleId: string), (...textsToTranslate: (string | string[])[]));
+```ts
+const i18nBundle = useI18nBundle(messageBundleId: string): I18nBundle;
 ```
 
-In case you have texts without placeholder values you can use the simple `string` arguments, but if you have parameters
-in your message bundle you will have to use the `array` notation (_please see step 6_).
-You can mix `string` and `array` arguments in the same call.
-
-Each parameter will be translated one by one and returned in an array in the same order.
+The `i18nBundle` is offering one public method `getText` which accepts a string as first parameter, followed by optional replacement parameters for your translation.
 
 **Example:**
 
 ```jsx
 const MyTranslatedTextComponent = () => {
-  const [pleaseWaitText, anotherText] = useI18nText('myApp', 'PLEASE_WAIT', 'ANOTHER_TEXT_TO_TRANSLATE');
+  const i18nBundle = useI18nBundle('myApp');
 
   return (
     <div>
-      <span>{pleaseWaitText}</span>
-      <p>{anotherText}</p>
+      <span>{i18nBundle.getText('PLEASE_WAIT')}</span>
+      <p>{i18nBundle.getText('ANOTHER_TEXT_TO_TRANSLATE')}</p>
     </div>
   );
 };
 ```
 
 **5. Use texts with placeholder values**
 
-In case you have texts with placeholders in your message bundle, you can pass an array as text parameter to receive
-translated text with parameters. In this case, the first entry in the array is the translation key, followed by an
-arbitrary number of parameters which should be inserted into the translation.
+You can pass multiple additional values to `getText` for texts with placeholders.
+In this case, the first parameter is the translation key, followed by an arbitrary number of parameters which should be inserted into the translation.
 
 **Example:**
 
@@ -116,7 +112,8 @@ CAROUSEL_DOT_TEXT=Item {0} of {1} displayed
 Your hook call would now look like this:
 
 ```js
-const [carouselText, pleaseWaitText] = useI18nText('myApp', ['CAROUSEL_DOT_TEXT', 5, 20], 'PLEASE_WAIT');
+const i18nBundle = useI18nBundle('myApp');
+const carouselText = i18nBundle.getText('CAROUSEL_DOT_TEXT', 5, 20);
 ```
 
 This would resolve this text:<br />

package.json

@@ -57,6 +57,7 @@
     "@storybook/storybook-deployer": "^2.8.6",
     "@testing-library/jest-dom": "^5.11.4",
     "@testing-library/react": "^11.0.2",
+    "@testing-library/react-hooks": "^3.7.0",
     "@types/jest": "^26.0.8",
     "@types/react": "^17.0.0",
     "@types/react-dom": "^17.0.0",
@@ -88,6 +89,7 @@
     "npm-run-all": "^4.1.5",
     "prettier": "^2.0.4",
     "react-app-polyfill": "^2.0.0",
+    "react-test-renderer": "17.0.1",
     "rimraf": "^3.0.1",
     "rollup": "^2.23.0",
     "rollup-plugin-terser": "^7.0.2",

packages/base/src/hooks/use18nBundle.test.ts

@@ -0,0 +1,34 @@
+import { act, renderHook } from '@testing-library/react-hooks';
+import { useI18nBundle } from './useI18nBundle';
+import { setLanguage } from '@ui5/webcomponents-base/dist/config/Language.js';
+import { version as reactVersion } from 'react/package.json';
+
+describe('useI18nBundle', () => {
+  test('Should load message bundle and update', async () => {
+    if (reactVersion === '16.8.0') {
+      // not testable with 16.8.0
+      return;
+    }
+    const { result } = renderHook(() => useI18nBundle('@ui5/webcomponents-react'));
+
+    expect(result.current.getText('PLEASE_WAIT')).toBe('Please wait');
+  });
+
+  test('Should update after changing the language', async () => {
+    if (reactVersion === '16.8.0') {
+      // not testable with 16.8.0
+      return;
+    }
+    const { result, waitForNextUpdate } = renderHook(() => useI18nBundle('@ui5/webcomponents-react'));
+    expect(result.current.getText('PLEASE_WAIT')).toBe('Please wait');
+
+    act(() => {
+      setLanguage('de');
+    });
+
+    await waitForNextUpdate();
+    expect(result.current.getText('PLEASE_WAIT')).toBe('Bitte warten');
+
+    expect(result.all).toHaveLength(2);
+  });
+});

packages/base/src/hooks/useI18nBundle.ts

@@ -1,11 +1,15 @@
+import { getI18nBundleData } from '@ui5/webcomponents-base/dist/asset-registries/i18n';
 import { fetchI18nBundle, getI18nBundle } from '@ui5/webcomponents-base/dist/i18nBundle';
+import { attachLanguageChange, detachLanguageChange } from '@ui5/webcomponents-base/dist/locale/languageChange';
+import { useIsomorphicLayoutEffect } from '@ui5/webcomponents-react-base/lib/hooks';
 import { useEffect, useState } from 'react';
+import { deprecationNotice } from '@ui5/webcomponents-react-base/lib/Utils';
 
-type TextWithDefault = { key: string; defaultText: string };
+type TextWithDefault = { key: string; defaultText: string } | string;
 type TextWithPlaceholders = [TextWithDefault, ...string[]];
 
 interface I18nBundle {
-  getText: (textObj: TextWithDefault, ...args: any) => string;
+  getText: (textObj: TextWithDefault, ...args: any[]) => string;
 }
 
 const resolveTranslations = (bundle, texts) => {
@@ -22,6 +26,14 @@ export const useI18nText = (bundleName: string, ...texts: (TextWithDefault | Tex
   const i18nBundle: I18nBundle = getI18nBundle(bundleName);
   const [translations, setTranslations] = useState(resolveTranslations(i18nBundle, texts));
 
+  useEffect(() => {
+    deprecationNotice(
+      'useI18nText',
+      `'useI18nText' is deprecated and will be removed in the next release. Please use 'useI18nBundle' instead.
+A Migration Guide can be found here: https://sap.github.io/ui5-webcomponents-react/?path=/docs/migration-guide--page#migrating-from-013x-to-0140`
+    );
+  }, []);
+
   useEffect(() => {
     let didCancel = false;
     const fetchAndLoadBundle = async () => {
@@ -40,7 +52,44 @@ export const useI18nText = (bundleName: string, ...texts: (TextWithDefault | Tex
     return () => {
       didCancel = true;
     };
-  }, [fetchI18nBundle, bundleName, texts]);
+  }, [fetchI18nBundle, bundleName, ...texts]);
 
   return translations;
 };
+
+export const useI18nBundle = (bundleName: string): I18nBundle => {
+  const [_, setUpdater] = useState(0);
+
+  useIsomorphicLayoutEffect(() => {
+    let isMounted = true;
+    const i18nBundleData = getI18nBundleData('@ui5/webcomponents-react');
+    if (!i18nBundleData) {
+      fetchI18nBundle(`${bundleName}`).then(() => {
+        if (isMounted) {
+          setUpdater((old) => old + 1);
+        }
+      });
+    }
+    return () => {
+      isMounted = false;
+    };
+  }, [bundleName]);
+
+  useEffect(() => {
+    let isMounted = true;
+    const handler = () => {
+      fetchI18nBundle(`${bundleName}`).then(() => {
+        if (isMounted) {
+          setUpdater((old) => old + 1);
+        }
+      });
+    };
+    attachLanguageChange(handler);
+    return () => {
+      isMounted = false;
+      detachLanguageChange(handler);
+    };
+  }, []);
+
+  return getI18nBundle(bundleName);
+};

packages/base/src/lib/hooks.ts

@@ -1,7 +1,14 @@
 import { useConsolidatedRef } from '../hooks/useConsolidatedRef';
-import { useI18nText } from '../hooks/useI18nBundle';
+import { useI18nBundle, useI18nText } from '../hooks/useI18nBundle';
 import { useIsomorphicLayoutEffect } from '../hooks/useIsomorphicLayoutEffect';
 import { usePassThroughHtmlProps } from '../hooks/usePassThroughHtmlProps';
 import { useViewportRange } from '../hooks/useViewportRange';
 
-export { useConsolidatedRef, usePassThroughHtmlProps, useViewportRange, useI18nText, useIsomorphicLayoutEffect };
+export {
+  useConsolidatedRef,
+  usePassThroughHtmlProps,
+  useViewportRange,
+  useI18nText,
+  useIsomorphicLayoutEffect,
+  useI18nBundle
+};

packages/main/src/components/AnalyticalCardHeader/index.tsx

@@ -1,5 +1,5 @@
 import { createComponentStyles } from '@ui5/webcomponents-react-base/lib/createComponentStyles';
-import { useI18nText, usePassThroughHtmlProps } from '@ui5/webcomponents-react-base/lib/hooks';
+import { useI18nBundle, usePassThroughHtmlProps } from '@ui5/webcomponents-react-base/lib/hooks';
 import { StyleClassHelper } from '@ui5/webcomponents-react-base/lib/StyleClassHelper';
 import { enrichEventWithDetails } from '@ui5/webcomponents-react-base/lib/Utils';
 import { DEVIATION, TARGET } from '@ui5/webcomponents-react/dist/assets/i18n/i18n-defaults';
@@ -171,7 +171,7 @@ export const AnalyticalCardHeader: FC<AnalyticalCardHeaderPropTypes> = forwardRe
 
     const passThroughProps = usePassThroughHtmlProps(props, ['onHeaderPress']);
 
-    const [targetText, deviationText] = useI18nText('@ui5/webcomponents-react', TARGET, DEVIATION);
+    const i18nBundle = useI18nBundle('@ui5/webcomponents-react');
 
     return (
       <div
@@ -217,7 +217,7 @@ export const AnalyticalCardHeader: FC<AnalyticalCardHeaderPropTypes> = forwardRe
                     className={classes.targetAndDeviationColumn}
                     wrap={FlexBoxWrap.NoWrap}
                   >
-                    <span>{targetText}</span>
+                    <span>{i18nBundle.getText(TARGET)}</span>
                     <span className={classes.targetAndDeviationValue}>{target}</span>
                   </FlexBox>
                 )}
@@ -227,7 +227,7 @@ export const AnalyticalCardHeader: FC<AnalyticalCardHeaderPropTypes> = forwardRe
                     className={classes.targetAndDeviationColumn}
                     wrap={FlexBoxWrap.NoWrap}
                   >
-                    <span>{deviationText}</span>
+                    <span>{i18nBundle.getText(DEVIATION)}</span>
                     <span className={classes.targetAndDeviationValue}>{deviation}</span>
                   </FlexBox>
                 )}

packages/main/src/components/AnalyticalTable/ColumnHeader/ColumnHeaderModal.tsx

@@ -1,5 +1,5 @@
 import '@ui5/webcomponents-icons/dist/decline';
-import { useI18nText } from '@ui5/webcomponents-react-base/lib/hooks';
+import { useI18nBundle } from '@ui5/webcomponents-react-base/lib/hooks';
 import { ThemingParameters } from '@ui5/webcomponents-react-base/lib/ThemingParameters';
 import { enrichEventWithDetails } from '@ui5/webcomponents-react-base/lib/Utils';
 import {
@@ -45,14 +45,13 @@ export const ColumnHeaderModal = (props: ColumnHeaderModalProperties) => {
 
   const { Filter } = column;
 
-  const [clearSortingText, sortAscendingText, sortDescendingText, groupText, ungroupText] = useI18nText(
-    '@ui5/webcomponents-react',
-    CLEAR_SORTING,
-    SORT_ASCENDING,
-    SORT_DESCENDING,
-    GROUP,
-    UNGROUP
-  );
+  const i18nBundle = useI18nBundle('@ui5/webcomponents-react');
+
+  const clearSortingText = i18nBundle.getText(CLEAR_SORTING);
+  const sortAscendingText = i18nBundle.getText(SORT_ASCENDING);
+  const sortDescendingText = i18nBundle.getText(SORT_DESCENDING);
+  const groupText = i18nBundle.getText(GROUP);
+  const ungroupText = i18nBundle.getText(UNGROUP);
 
   const handleSort = useCallback(
     (e) => {

packages/main/src/components/AnalyticalTable/VerticalResizer.tsx

@@ -1,4 +1,4 @@
-import { useI18nText } from '@ui5/webcomponents-react-base/lib/hooks';
+import { useI18nBundle } from '@ui5/webcomponents-react-base/lib/hooks';
 import { ThemingParameters } from '@ui5/webcomponents-react-base/lib/ThemingParameters';
 import { DRAG_TO_RESIZE } from '@ui5/webcomponents-react/dist/assets/i18n/i18n-defaults';
 import React, { MutableRefObject, useCallback, useEffect, useRef, useState } from 'react';
@@ -62,7 +62,7 @@ export const VerticalResizer = (props: VerticalResizerProps) => {
   const [isDragging, setIsDragging] = useState(false);
   const [mountTouchEvents, setMountTouchEvents] = useState(false);
 
-  const [dragToResizeText] = useI18nText('@ui5/webcomponents-react', DRAG_TO_RESIZE);
+  const i18nBundle = useI18nBundle('@ui5/webcomponents-react');
 
   const handleResizeStart = useCallback(
     (e) => {
@@ -153,7 +153,7 @@ export const VerticalResizer = (props: VerticalResizerProps) => {
       onMouseDown={handleResizeStart}
       onTouchStart={handleResizeStart}
       role="separator"
-      title={dragToResizeText}
+      title={i18nBundle.getText(DRAG_TO_RESIZE)}
     >
       {resizerPosition &&
         isDragging &&

packages/main/src/components/FilterBar/FilterDialog.tsx

@@ -1,6 +1,6 @@
 import '@ui5/webcomponents-icons/dist/search';
 import { createComponentStyles } from '@ui5/webcomponents-react-base/lib/createComponentStyles';
-import { useI18nText } from '@ui5/webcomponents-react-base/lib/hooks';
+import { useI18nBundle } from '@ui5/webcomponents-react-base/lib/hooks';
 import { enrichEventWithDetails } from '@ui5/webcomponents-react-base/lib/Utils';
 import {
   BASIC,
@@ -62,24 +62,15 @@ export const FilterDialog = (props) => {
   const dialogRefs = useRef({});
   const dialogRef = useRef<Ui5DialogDomRef>();
 
-  const [
-    basicText,
-    cancelText,
-    clearText,
-    restoreText,
-    saveText,
-    searchForFiltersText,
-    showOnFilterBarText
-  ] = useI18nText(
-    '@ui5/webcomponents-react',
-    BASIC,
-    CANCEL,
-    CLEAR,
-    RESTORE,
-    SAVE,
-    SEARCH_FOR_FILTERS,
-    SHOW_ON_FILTER_BAR
-  );
+  const i18nBundle = useI18nBundle('@ui5/webcomponents-react');
+
+  const basicText = i18nBundle.getText(BASIC);
+  const cancelText = i18nBundle.getText(CANCEL);
+  const clearText = i18nBundle.getText(CLEAR);
+  const restoreText = i18nBundle.getText(RESTORE);
+  const saveText = i18nBundle.getText(SAVE);
+  const searchForFiltersText = i18nBundle.getText(SEARCH_FOR_FILTERS);
+  const showOnFilterBarText = i18nBundle.getText(SHOW_ON_FILTER_BAR);
 
   useEffect(() => {
     if (open) {