refactor(framework): Simplify i18nBundle usage (#4128)

docs/2-advanced/06-using-i18n-for-apps.md

@@ -27,7 +27,7 @@ This tutorial will show you how to use the UI5 Web Components `i18n` functionali
 
 ```js
 import parseProperties from "@ui5/webcomponents-base/dist/PropertiesFileFormat.js";
-import { registerI18nLoader, fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { registerI18nLoader, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 ```
 
 The first one provides support for `.properties` files, as used in the example, and the second one - the functions
@@ -51,18 +51,10 @@ The first argument to `registerI18nLoader` is an ID that will be used to referen
 
 *Note:* This step takes care of registering assets only, no data will be fetched at this point.
 
-### 4. Tell the framework to fetch the texts for the current language:
+### 4. Get and use the bundle:
 
 ```js
-await fetchI18nBundle("myApp");
-```
-
-This will fetch the appropriate texts for the currently configured language and store them internally.
-
-### 5. Get and use the bundle:
-
-```js
-const bundle = getI18nBundle("myApp");
+const bundle = await getI18nBundle("myApp");
 const pleaseWait = bundle.getText("PLEASE_WAIT");
 console.log("Please wait in the current language is: ", pleaseWait);
 ```
@@ -81,15 +73,15 @@ which will finally result in
 
 `Item 5 of 20 displayed`.
 
-### 6. Test your page using different languages, e.g. set `?sap-ui-language=de` in the URL or change the configuration.
+### 5. Test your page using different languages, e.g. set `?sap-ui-language=de` in the URL or change the configuration.
 
 ## Summary
 
 The whole code would look like this:
 
 ```js
 import parseProperties from "@ui5/webcomponents-base/dist/PropertiesFileFormat.js";
-import { registerI18nLoader, fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { registerI18nLoader, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 
 const supportedLocales = ["en", "fr", "de", "es"];
 supportedLocales.forEach(localeToRegister => {
@@ -99,9 +91,7 @@ supportedLocales.forEach(localeToRegister => {
 	});
 });
 
-await fetchI18nBundle("myApp");
-
-const bundle = getI18nBundle("myApp");
+const bundle = await getI18nBundle("myApp");
 
 const pleaseWait = bundle.getText("PLEASE_WAIT");
 console.log("Please wait in the current language is: ", pleaseWait);

docs/5-development/02-custom-UI5-Web-Components.md

@@ -11,7 +11,7 @@ The main file representing the Web Component is `Demo.js`.
 ```js
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
-import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 
 // Template
 import DemoTemplate from "./generated/templates/DemoTemplate.lit.js";
@@ -33,16 +33,6 @@ const metadata = {
 };
 
 class Demo extends UI5Element {
-
-	constructor() {
-		super();
-		this.i18nBundle = getI18nBundle("my-ui5-web-components");
-	}
-
-	get pleaseWaitText() {
-		return this.i18nBundle.getText(PLEASE_WAIT);
-	}
-
 	static get metadata() {
 		return metadata;
 	}
@@ -60,7 +50,11 @@ class Demo extends UI5Element {
 	}
 
 	static async onDefine() {
-		await fetchI18nBundle("my-ui5-web-components");
+		Demo.i18nBundle = await getI18nBundle("my-ui5-web-components");
+	}
+
+	get pleaseWaitText() {
+		return Demo.i18nBundle.getText(PLEASE_WAIT);
 	}
 }
 
@@ -308,26 +302,23 @@ export default Demo;
 
 ### Adding i18n support
 
-There are 3 steps to do that:
- 1. Fetch an i18n bundle during component definition
+There are 2 steps to do that:
+ 1. Get and assign an i18n bundle during component definition
  ```js
- await fetchI18nBundle("my-ui5-web-components");
+ await Demo.i18nBundle = getI18nBundle("my-ui5-web-components");
  ```
 
- 2. (optional) Get a reference to the bundle in the constructor for convenience
- `this.i18nBundle = getI18nBundle("my-ui5-web-components");`
-
  3. Get texts from the bundle, according to the currently [configured](../Configuration.md) language
- `return this.i18nBundle.getText(PLEASE_WAIT);`
+ `return Demo.i18nBundle.getText(PLEASE_WAIT);`
 
-The `fetchI18nBundle` and `getI18nBundle` methods are provided by the `i18nBundle.js` module from the `@ui5/webcomponents-base` package.
+The `getI18nBundle` method is provided by the `i18nBundle.js` module from the `@ui5/webcomponents-base` package.
 
 So the final source code is:
 
 ```js
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
-import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 
 // Template
 import DemoTemplate from "./generated/templates/DemoTemplate.lit.js";
@@ -349,16 +340,6 @@ const metadata = {
 };
 
 class Demo extends UI5Element {
-
-	constructor() {
-		super();
-		this.i18nBundle = getI18nBundle("my-ui5-web-components");
-	}
-
-	get pleaseWaitText() {
-		return this.i18nBundle.getText(PLEASE_WAIT);
-	}
-
 	static get metadata() {
 		return metadata;
 	}
@@ -376,7 +357,11 @@ class Demo extends UI5Element {
 	}
 
 	static async onDefine() {
-		await fetchI18nBundle("my-ui5-web-components");
+		Demo.i18nBundle = await getI18nBundle("my-ui5-web-components");
+	}
+
+	get pleaseWaitText() {
+		return Demo.i18nBundle.getText(PLEASE_WAIT);
 	}
 }
 

packages/base/README.md

@@ -23,8 +23,7 @@ Contains the base files for all Web Components, most notably `@ui5/webcomponents
 ### `i18nBundle.js`
 
  - `registerI18nLoader`
- - `fetchI18nBundle`
- - `getI18nBundleData`
+ - `getI18nBundle`
 
 ### `PropertiesFileFormat.js`
 

packages/base/bundle.esm.js

@@ -24,7 +24,7 @@ window.isIE = isIE; // attached to the window object for testing purposes
 window.registerThemePropertiesLoader = registerThemePropertiesLoader;
 
 // i18n
-import { registerI18nLoader, fetchI18nBundle, getI18nBundle } from "./dist/i18nBundle.js";
+import { registerI18nLoader, getI18nBundle } from "./dist/i18nBundle.js";
 
 // Note: keep in sync with rollup.config value for IIFE
 import { getAnimationMode } from "./dist/config/AnimationMode.js";
@@ -51,7 +51,6 @@ window["sap-ui-webcomponents-bundle"] = {
 	},
 	getIconNames,
 	registerI18nLoader,
-	fetchI18nBundle,
 	getI18nBundle,
 	renderFinished,
 	applyDirection,

packages/base/hash.txt

@@ -1 +1 @@
-By5B1K3Pq1rzoc8ZDxA0OLyjqm4=
+EZHFQeI2tQaCSil+FGQpjYk8NzA=

packages/base/src/i18nBundle.js

@@ -39,7 +39,7 @@ class I18nBundle {
 	}
 }
 
-const getI18nBundle = packageName => {
+const getI18nBundleSync = packageName => {
 	if (I18nBundleInstances.has(packageName)) {
 		return I18nBundleInstances.get(packageName);
 	}
@@ -49,8 +49,19 @@ const getI18nBundle = packageName => {
 	return i18nBundle;
 };
 
+/**
+ * Fetches and returns the I18nBundle instance for the given package
+ *
+ * @public
+ * @param packageName
+ * @returns {Promise<I18nBundle>}
+ */
+const getI18nBundle = async packageName => {
+	await fetchI18nBundle(packageName);
+	return getI18nBundleSync(packageName);
+};
+
 export {
 	registerI18nLoader,
-	fetchI18nBundle,
 	getI18nBundle,
 };

packages/base/test/pages/i18n.html

@@ -17,9 +17,7 @@
 		const demo = async () => {
 			["de", "es", "fr", "en"].forEach(localeId => registerI18nLoader("myApp", localeId, () => `./assets/messagebundle_${localeId}.properties`));
 
-			await fetchI18nBundle("myApp");
-
-			const bundle = getI18nBundle("myApp");
+			const bundle = await getI18nBundle("myApp");
 
 			const pleaseWait = bundle.getText("PLEASE_WAIT");
 			console.log("Please wait in the current language is: ", pleaseWait);

packages/create-package/template/src/MyFirstComponent.js

@@ -1,6 +1,6 @@
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
-import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 
 // Template
 import INIT_PACKAGE_VAR_CLASS_NAMETemplate from "./generated/templates/INIT_PACKAGE_VAR_CLASS_NAMETemplate.lit.js";
@@ -21,15 +21,6 @@ const metadata = {
 };
 
 class INIT_PACKAGE_VAR_CLASS_NAME extends UI5Element {
-	constructor() {
-		super();
-		this.i18nBundle = getI18nBundle("INIT_PACKAGE_VAR_NAME");
-	}
-
-	get pleaseWaitText() {
-		return this.i18nBundle.getText(PLEASE_WAIT);
-	}
-
 	static get metadata() {
 		return metadata;
 	}
@@ -47,7 +38,11 @@ class INIT_PACKAGE_VAR_CLASS_NAME extends UI5Element {
 	}
 
 	static async onDefine() {
-		await fetchI18nBundle("INIT_PACKAGE_VAR_NAME");
+		INIT_PACKAGE_VAR_CLASS_NAME.i18nBundle = await getI18nBundle("INIT_PACKAGE_VAR_NAME");
+	}
+
+	get pleaseWaitText() {
+		return INIT_PACKAGE_VAR_CLASS_NAME.i18nBundle.getText(PLEASE_WAIT);
 	}
 }
 

packages/fiori/src/BarcodeScannerDialog.js

@@ -1,6 +1,6 @@
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
-import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import Dialog from "@ui5/webcomponents/dist/Dialog.js";
 import Button from "@ui5/webcomponents/dist/Button.js";
 import BusyIndicator from "@ui5/webcomponents/dist/BusyIndicator.js";
@@ -110,7 +110,6 @@ const metadata = {
 class BarcodeScannerDialog extends UI5Element {
 	constructor() {
 		super();
-		this.i18nBundle = getI18nBundle("@ui5/webcomponents-fiori");
 		this._codeReader = new BrowserMultiFormatReader();
 	}
 
@@ -139,7 +138,7 @@ class BarcodeScannerDialog extends UI5Element {
 	}
 
 	static async onDefine() {
-		await fetchI18nBundle("@ui5/webcomponents-fiori");
+		BarcodeScannerDialog.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori");
 	}
 
 	/**
@@ -242,11 +241,11 @@ class BarcodeScannerDialog extends UI5Element {
 	}
 
 	get _cancelButtonText() {
-		return this.i18nBundle.getText(BARCODE_SCANNER_DIALOG_CANCEL_BUTTON_TXT);
+		return BarcodeScannerDialog.i18nBundle.getText(BARCODE_SCANNER_DIALOG_CANCEL_BUTTON_TXT);
 	}
 
 	get _busyIndicatorText() {
-		return this.i18nBundle.getText(BARCODE_SCANNER_DIALOG_LOADING_TXT);
+		return BarcodeScannerDialog.i18nBundle.getText(BARCODE_SCANNER_DIALOG_LOADING_TXT);
 	}
 
 	static get dependencies() {

packages/fiori/src/FlexibleColumnLayout.js

@@ -3,7 +3,7 @@ import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
 import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
 import Float from "@ui5/webcomponents-base/dist/types/Float.js";
 import Integer from "@ui5/webcomponents-base/dist/types/Integer.js";
-import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import AnimationMode from "@ui5/webcomponents-base/dist/types/AnimationMode.js";
 import { getAnimationMode } from "@ui5/webcomponents-base/dist/config/AnimationMode.js";
 import { isIE } from "@ui5/webcomponents-base/dist/Device.js";
@@ -259,7 +259,6 @@ class FlexibleColumnLayout extends UI5Element {
 		this._prevLayout = null;
 		this.initialRendering = true;
 		this._handleResize = this.handleResize.bind(this);
-		this.i18nBundle = getI18nBundle("@ui5/webcomponents-fiori");
 	}
 
 	static get metadata() {
@@ -283,7 +282,7 @@ class FlexibleColumnLayout extends UI5Element {
 	}
 
 	static async onDefine() {
-		await fetchI18nBundle("@ui5/webcomponents-fiori");
+		FlexibleColumnLayout.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori");
 	}
 
 	static get BREAKPOINTS() {
@@ -656,15 +655,15 @@ class FlexibleColumnLayout extends UI5Element {
 	}
 
 	get accStartColumnText() {
-		return this.accessibilityTexts.startColumnAccessibleName || this.i18nBundle.getText(FCL_START_COLUMN_TXT);
+		return this.accessibilityTexts.startColumnAccessibleName || FlexibleColumnLayout.i18nBundle.getText(FCL_START_COLUMN_TXT);
 	}
 
 	get accMiddleColumnText() {
-		return this.accessibilityTexts.midColumnAccessibleName || this.i18nBundle.getText(FCL_MIDDLE_COLUMN_TXT);
+		return this.accessibilityTexts.midColumnAccessibleName || FlexibleColumnLayout.i18nBundle.getText(FCL_MIDDLE_COLUMN_TXT);
 	}
 
 	get accEndColumnText() {
-		return this.accessibilityTexts.endColumnAccessibleName || this.i18nBundle.getText(FCL_END_COLUMN_TXT);
+		return this.accessibilityTexts.endColumnAccessibleName || FlexibleColumnLayout.i18nBundle.getText(FCL_END_COLUMN_TXT);
 	}
 
 	get _effectiveLayoutsByMedia() {
@@ -675,20 +674,20 @@ class FlexibleColumnLayout extends UI5Element {
 		const customTexts = this.accessibilityTexts;
 
 		if (this.startArrowDirection === "mirror") {
-			return customTexts.startArrowLeftText || this.i18nBundle.getText(FCL_START_COLUMN_COLLAPSE_BUTTON_TOOLTIP);
+			return customTexts.startArrowLeftText || FlexibleColumnLayout.i18nBundle.getText(FCL_START_COLUMN_COLLAPSE_BUTTON_TOOLTIP);
 		}
 
-		return customTexts.startArrowRightText || this.i18nBundle.getText(FCL_START_COLUMN_EXPAND_BUTTON_TOOLTIP);
+		return customTexts.startArrowRightText || FlexibleColumnLayout.i18nBundle.getText(FCL_START_COLUMN_EXPAND_BUTTON_TOOLTIP);
 	}
 
 	get accEndArrowText() {
 		const customTexts = this.accessibilityTexts;
 
 		if (this.endArrowDirection === "mirror") {
-			return customTexts.endArrowRightText || this.i18nBundle.getText(FCL_END_COLUMN_COLLAPSE_BUTTON_TOOLTIP);
+			return customTexts.endArrowRightText || FlexibleColumnLayout.i18nBundle.getText(FCL_END_COLUMN_COLLAPSE_BUTTON_TOOLTIP);
 		}
 
-		return customTexts.endArrowLeftText || this.i18nBundle.getText(FCL_END_COLUMN_EXPAND_BUTTON_TOOLTIP);
+		return customTexts.endArrowLeftText || FlexibleColumnLayout.i18nBundle.getText(FCL_END_COLUMN_EXPAND_BUTTON_TOOLTIP);
 	}
 }