feat(framework): allow using a custom i18n library (#4119)

packages/base/hash.txt

@@ -1 +1 @@
-e4x+vuGaRUwBlCgujSarJaLpsDk=
+nonWS/k2fnX+vVo1+Pr6wnqqGJk=

packages/base/src/i18nBundle.js

@@ -3,6 +3,8 @@ import formatMessage from "./util/formatMessage.js";
 
 const I18nBundleInstances = new Map();
 
+let customGetI18nBundle;
+
 /**
  * @class
  * @public
@@ -49,6 +51,18 @@ const getI18nBundleSync = packageName => {
 	return i18nBundle;
 };
 
+/**
+ * Allows developers to provide a custom getI18nBundle implementation
+ * If this function is called, the custom implementation will be used for all components and will completely
+ * replace the default implementation.
+ *
+ * @public
+ * @param customGet the function to use instead of the standard getI18nBundle implementation
+ */
+const registerCustomI18nBundleGetter = customGet => {
+	customGetI18nBundle = customGet;
+};
+
 /**
  * Fetches and returns the I18nBundle instance for the given package
  *
@@ -57,11 +71,16 @@ const getI18nBundleSync = packageName => {
  * @returns {Promise<I18nBundle>}
  */
 const getI18nBundle = async packageName => {
+	if (customGetI18nBundle) {
+		return customGetI18nBundle(packageName);
+	}
+
 	await fetchI18nBundle(packageName);
 	return getI18nBundleSync(packageName);
 };
 
 export {
 	registerI18nLoader,
 	getI18nBundle,
+	registerCustomI18nBundleGetter,
 };

packages/main/bundle.common.js

@@ -1,5 +1,5 @@
 import { addCustomCSS, attachThemeLoaded, detachThemeLoaded } from "@ui5/webcomponents-base/dist/Theming.js";
-
+// import "./customI18n.js";
 
 // Calendars
 import "@ui5/webcomponents-localization/dist/features/calendar/Buddhist.js";

packages/main/customI18n.js

@@ -0,0 +1,50 @@
+import { registerCustomI18nBundleGetter } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+
+// Third-party i18n library that has an async "load" function that fetches the i18n bundle and returns an object with a "get" method
+const i18n = {
+	load: async () => {
+		await Promise.resolve(); // fetch the data here
+		return {
+			get: (key, paramsArr, defaultText) => `key: ${key}, params: ${paramsArr.join(", ")}, defaultText: ${defaultText}`,
+		};
+	},
+};
+
+let bundle;
+registerCustomI18nBundleGetter(async packageName => {
+	if (!bundle) {
+		bundle = await i18n.load(); // potentially use the packageName parameter too
+	}
+	return {
+		getText: (keyObj, ...params) => {
+			const key = typeof keyObj === "string" ? keyObj : keyObj.key;
+			return bundle.get(key, params, keyObj.defaultText);
+		},
+	};
+});
+
+/*
+// Example with the i18next library
+
+import i18next from "i18next";
+registerCustomI18nBundleGetter(async packageName => {
+	await i18next.init({
+		lng: "en", // pass the desired language
+		debug: true,
+		resources: { // potentially use packageName to determine which translations to load - hardcoded for this example
+			en: {
+				translation: {
+					"key": "hello world",
+				},
+			},
+		},
+	});
+	return {
+		getText: (keyObj, ...params) => {
+			let key = typeof keyObj === "string" ? keyObj : keyObj.key;
+			key = key.replace(/{{/g, "{").replace(/}}/g, "}"); // the key will be with {{0}}, {{1}}, etc. placeholders
+			return i18next.t(key); // also pass the parameters, with keys "0", "1", etc.
+		},
+	};
+});
+*/