@itwin/core-i18n 4.0.0-dev.7 → 4.0.0-dev.72

package/lib/esm/ITwinLocalization.js

@@ -1,225 +1,223 @@
-/*---------------------------------------------------------------------------------------------
-* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
-* See LICENSE.md in the project root for license terms and full copyright notice.
-*--------------------------------------------------------------------------------------------*/
-/** @packageDocumentation
- * @module Localization
- */
-import i18next from "i18next";
-import i18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
-import Backend from "i18next-http-backend";
-import { Logger } from "@itwin/core-bentley";
-const DEFAULT_MAX_RETRIES = 1; // a low number prevents wasted time and potential timeouts when requesting localization files throws an error
-/** Supplies localizations for iTwin.js
- * @note this class uses the [i18next](https://www.i18next.com/) package.
- * @public
- */
-export class ITwinLocalization {
-    constructor(options) {
-        var _a, _b, _c;
-        this._namespaces = new Map();
-        this.i18next = i18next.createInstance();
-        this._backendOptions = {
-            loadPath: (_a = options === null || options === void 0 ? void 0 : options.urlTemplate) !== null && _a !== void 0 ? _a : "locales/{{lng}}/{{ns}}.json",
-            crossDomain: true,
-            ...options === null || options === void 0 ? void 0 : options.backendHttpOptions,
-        };
-        this._detectionOptions = {
-            order: ["querystring", "navigator", "htmlTag"],
-            lookupQuerystring: "lng",
-            caches: [],
-            ...options === null || options === void 0 ? void 0 : options.detectorOptions,
-        };
-        this._initOptions = {
-            interpolation: { escapeValue: true },
-            fallbackLng: "en",
-            maxRetries: DEFAULT_MAX_RETRIES,
-            backend: this._backendOptions,
-            detection: this._detectionOptions,
-            ...options === null || options === void 0 ? void 0 : options.initOptions,
-        };
-        this.i18next
-            .use((_b = options === null || options === void 0 ? void 0 : options.detectorPlugin) !== null && _b !== void 0 ? _b : i18nextBrowserLanguageDetector)
-            .use((_c = options === null || options === void 0 ? void 0 : options.backendPlugin) !== null && _c !== void 0 ? _c : Backend)
-            .use(TranslationLogger);
-    }
-    async initialize(namespaces) {
-        var _a;
-        // Also consider namespaces passed into constructor
-        const initNamespaces = [this._initOptions.ns || []].flat();
-        const combinedNamespaces = new Set([...namespaces, ...initNamespaces]); // without duplicates
-        const defaultNamespace = (_a = this._initOptions.defaultNS) !== null && _a !== void 0 ? _a : namespaces[0];
-        if (defaultNamespace)
-            combinedNamespaces.add(defaultNamespace); // Make sure default namespace is in namespaces list
-        const initOptions = {
-            ...this._initOptions,
-            defaultNS: defaultNamespace,
-            ns: [...combinedNamespaces],
-        };
-        // if in a development environment, set debugging
-        if (process.env.NODE_ENV === "development")
-            initOptions.debug = true;
-        const initPromise = this.i18next.init(initOptions);
-        for (const ns of namespaces)
-            this._namespaces.set(ns, initPromise);
-        return initPromise;
-    }
-    /** Replace all instances of `%{key}` within a string with the translations of those keys.
-     * For example:
-     * ``` ts
-     * "MyKeys": {
-     *   "Key1": "First value",
-     *   "Key2": "Second value"
-     *  }
-     * ```
-     *
-     * ``` ts
-     * i18.translateKeys("string with %{MyKeys.Key1} followed by %{MyKeys.Key2}!"") // returns "string with First Value followed by Second Value!"
-     * ```
-     * @param line The input line, potentially containing %{keys}.
-     * @returns The line with all %{keys} translated
-     * @public
-     */
-    getLocalizedKeys(line) {
-        return line.replace(/\%\{(.+?)\}/g, (_match, tag) => this.getLocalizedString(tag));
-    }
-    /** Return the translated value of a key.
-     * @param key - the key that matches a property in the JSON localization file.
-     * @note The key includes the namespace, which identifies the particular localization file that contains the property,
-     * followed by a colon, followed by the property in the JSON file.
-     * For example:
-     * ``` ts
-     * const dataString: string = IModelApp.localization.getLocalizedString("iModelJs:BackgroundMap.BingDataAttribution");
-     *  ```
-     * assigns to dataString the string with property BackgroundMap.BingDataAttribution from the iModelJs.json localization file.
-     * @returns The string corresponding to the first key that resolves.
-     * @throws Error if no keys resolve to a string.
-     * @public
-     */
-    getLocalizedString(key, options) {
-        if ((options === null || options === void 0 ? void 0 : options.returnDetails) || (options === null || options === void 0 ? void 0 : options.returnObjects)) {
-            throw new Error("Translation key must map to a string, but the given options will result in an object");
-        }
-        const value = this.i18next.t(key, options);
-        if (typeof value !== "string") {
-            throw new Error("Translation key(s) string not found");
-        }
-        return value;
-    }
-    /** Similar to `getLocalizedString` but the default namespace is a separate parameter and the key does not need
-     * to include a namespace. If a key includes a namespace, that namespace will be used for interpolating that key.
-     * @param namespace - the namespace that identifies the particular localization file that contains the property.
-     * @param key - the key that matches a property in the JSON localization file.
-     * @returns The string corresponding to the first key that resolves.
-     * @throws Error if no keys resolve to a string.
-     * @internal
-     */
-    getLocalizedStringWithNamespace(namespace, key, options) {
-        let fullKey = "";
-        if (typeof key === "string") {
-            fullKey = `${namespace}:${key}`;
-        }
-        else {
-            fullKey = key.map((subKey) => {
-                return `${namespace}:${subKey}`;
-            });
-        }
-        return this.getLocalizedString(fullKey, options);
-    }
-    /** Gets the English translation.
-     * @param namespace - the namespace that identifies the particular localization file that contains the property.
-     * @param key - the key that matches a property in the JSON localization file.
-     * @returns The string corresponding to the first key that resolves.
-     * @throws Error if no keys resolve to a string.
-     * @internal
-     */
-    getEnglishString(namespace, key, options) {
-        if ((options === null || options === void 0 ? void 0 : options.returnDetails) || (options === null || options === void 0 ? void 0 : options.returnObjects)) {
-            throw new Error("Translation key must map to a string, but the given options will result in an object");
-        }
-        options = {
-            ...options,
-            ns: namespace, // ensure namespace argument is used
-        };
-        const en = this.i18next.getFixedT("en", namespace);
-        const str = en(key, options);
-        if (typeof str !== "string")
-            throw new Error("Translation key(s) not found");
-        return str;
-    }
-    /** Get the promise for an already registered Namespace.
-     * @param name - the name of the namespace
-     * @public
-     */
-    getNamespacePromise(name) {
-        return this._namespaces.get(name);
-    }
-    /** @internal */
-    getLanguageList() {
-        return this.i18next.languages;
-    }
-    /** override the language detected in the browser  */
-    async changeLanguage(language) {
-        return this.i18next.changeLanguage(language);
-    }
-    /** Register a new Namespace and return it. If the namespace is already registered, it will be returned.
-     * @param name - the name of the namespace, which is the base name of the JSON file that contains the localization properties.
-     * @note - The registerNamespace method starts fetching the appropriate version of the JSON localization file from the server,
-     * based on the current locale. To make sure that fetch is complete before performing translations from this namespace, await
-     * fulfillment of the readPromise Promise property of the returned LocalizationNamespace.
-     * @see [Localization in iTwin.js]($docs/learning/frontend/Localization.md)
-     * @public
-     */
-    async registerNamespace(name) {
-        const existing = this._namespaces.get(name);
-        if (existing !== undefined)
-            return existing;
-        const theReadPromise = new Promise((resolve) => {
-            // eslint-disable-next-line @typescript-eslint/no-floating-promises
-            this.i18next.loadNamespaces(name, (err) => {
-                if (!err)
-                    return resolve();
-                // Here we got a non-null err object.
-                // This method is called when the system has attempted to load the resources for the namespaces for each possible locale.
-                // For example 'fr-ca' might be the most specific locale, in which case 'fr' and 'en' are fallback locales.
-                // Using Backend from i18next-http-backend, err will be an array of strings of each namespace it tried to read and its locale.
-                // There might be errs for some other namespaces as well as this one. We resolve the promise unless there's an error for each possible locale.
-                let locales = this.getLanguageList().map((thisLocale) => `/${thisLocale}/`);
-                try {
-                    for (const thisError of err) {
-                        if (typeof thisError === "string")
-                            locales = locales.filter((thisLocale) => !thisError.includes(thisLocale));
-                    }
-                }
-                catch (e) {
-                    locales = [];
-                }
-                // if we removed every locale from the array, it wasn't loaded.
-                if (locales.length === 0)
-                    Logger.logError("i18n", `No resources for namespace ${name} could be loaded`);
-                resolve();
-            });
-        });
-        this._namespaces.set(name, theReadPromise);
-        return theReadPromise;
-    }
-    /** @internal */
-    unregisterNamespace(name) {
-        this._namespaces.delete(name);
-    }
-}
-class TranslationLogger {
-    log(args) { Logger.logInfo("i18n", this.createLogMessage(args)); }
-    warn(args) { Logger.logWarning("i18n", this.createLogMessage(args)); }
-    error(args) { Logger.logError("i18n", this.createLogMessage(args)); }
-    createLogMessage(args) {
-        let message = args[0];
-        for (let i = 1; i < args.length; ++i) {
-            if (typeof args[i] === "string")
-                message += `\n  ${args[i]}`;
-        }
-        return message;
-    }
-}
-TranslationLogger.type = "logger";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Localization
+ */
+import i18next from "i18next";
+import i18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
+import Backend from "i18next-http-backend";
+import { Logger } from "@itwin/core-bentley";
+const DEFAULT_MAX_RETRIES = 1; // a low number prevents wasted time and potential timeouts when requesting localization files throws an error
+/** Supplies localizations for iTwin.js
+ * @note this class uses the [i18next](https://www.i18next.com/) package.
+ * @public
+ */
+export class ITwinLocalization {
+    constructor(options) {
+        this._namespaces = new Map();
+        this.i18next = i18next.createInstance();
+        this._backendOptions = {
+            loadPath: options?.urlTemplate ?? "locales/{{lng}}/{{ns}}.json",
+            crossDomain: true,
+            ...options?.backendHttpOptions,
+        };
+        this._detectionOptions = {
+            order: ["querystring", "navigator", "htmlTag"],
+            lookupQuerystring: "lng",
+            caches: [],
+            ...options?.detectorOptions,
+        };
+        this._initOptions = {
+            interpolation: { escapeValue: true },
+            fallbackLng: "en",
+            maxRetries: DEFAULT_MAX_RETRIES,
+            backend: this._backendOptions,
+            detection: this._detectionOptions,
+            ...options?.initOptions,
+        };
+        this.i18next
+            .use(options?.detectorPlugin ?? i18nextBrowserLanguageDetector)
+            .use(options?.backendPlugin ?? Backend)
+            .use(TranslationLogger);
+    }
+    async initialize(namespaces) {
+        // Also consider namespaces passed into constructor
+        const initNamespaces = [this._initOptions.ns || []].flat();
+        const combinedNamespaces = new Set([...namespaces, ...initNamespaces]); // without duplicates
+        const defaultNamespace = this._initOptions.defaultNS ?? namespaces[0];
+        if (defaultNamespace)
+            combinedNamespaces.add(defaultNamespace); // Make sure default namespace is in namespaces list
+        const initOptions = {
+            ...this._initOptions,
+            defaultNS: defaultNamespace,
+            ns: [...combinedNamespaces],
+        };
+        // if in a development environment, set debugging
+        if (process.env.NODE_ENV === "development")
+            initOptions.debug = true;
+        const initPromise = this.i18next.init(initOptions);
+        for (const ns of namespaces)
+            this._namespaces.set(ns, initPromise);
+        return initPromise;
+    }
+    /** Replace all instances of `%{key}` within a string with the translations of those keys.
+     * For example:
+     * ``` ts
+     * "MyKeys": {
+     *   "Key1": "First value",
+     *   "Key2": "Second value"
+     *  }
+     * ```
+     *
+     * ``` ts
+     * i18.translateKeys("string with %{MyKeys.Key1} followed by %{MyKeys.Key2}!"") // returns "string with First Value followed by Second Value!"
+     * ```
+     * @param line The input line, potentially containing %{keys}.
+     * @returns The line with all %{keys} translated
+     * @public
+     */
+    getLocalizedKeys(line) {
+        return line.replace(/\%\{(.+?)\}/g, (_match, tag) => this.getLocalizedString(tag));
+    }
+    /** Return the translated value of a key.
+     * @param key - the key that matches a property in the JSON localization file.
+     * @note The key includes the namespace, which identifies the particular localization file that contains the property,
+     * followed by a colon, followed by the property in the JSON file.
+     * For example:
+     * ``` ts
+     * const dataString: string = IModelApp.localization.getLocalizedString("iModelJs:BackgroundMap.BingDataAttribution");
+     *  ```
+     * assigns to dataString the string with property BackgroundMap.BingDataAttribution from the iModelJs.json localization file.
+     * @returns The string corresponding to the first key that resolves.
+     * @throws Error if no keys resolve to a string.
+     * @public
+     */
+    getLocalizedString(key, options) {
+        if (options?.returnDetails || options?.returnObjects) {
+            throw new Error("Translation key must map to a string, but the given options will result in an object");
+        }
+        const value = this.i18next.t(key, options);
+        if (typeof value !== "string") {
+            throw new Error("Translation key(s) string not found");
+        }
+        return value;
+    }
+    /** Similar to `getLocalizedString` but the default namespace is a separate parameter and the key does not need
+     * to include a namespace. If a key includes a namespace, that namespace will be used for interpolating that key.
+     * @param namespace - the namespace that identifies the particular localization file that contains the property.
+     * @param key - the key that matches a property in the JSON localization file.
+     * @returns The string corresponding to the first key that resolves.
+     * @throws Error if no keys resolve to a string.
+     * @internal
+     */
+    getLocalizedStringWithNamespace(namespace, key, options) {
+        let fullKey = "";
+        if (typeof key === "string") {
+            fullKey = `${namespace}:${key}`;
+        }
+        else {
+            fullKey = key.map((subKey) => {
+                return `${namespace}:${subKey}`;
+            });
+        }
+        return this.getLocalizedString(fullKey, options);
+    }
+    /** Gets the English translation.
+     * @param namespace - the namespace that identifies the particular localization file that contains the property.
+     * @param key - the key that matches a property in the JSON localization file.
+     * @returns The string corresponding to the first key that resolves.
+     * @throws Error if no keys resolve to a string.
+     * @internal
+     */
+    getEnglishString(namespace, key, options) {
+        if (options?.returnDetails || options?.returnObjects) {
+            throw new Error("Translation key must map to a string, but the given options will result in an object");
+        }
+        options = {
+            ...options,
+            ns: namespace, // ensure namespace argument is used
+        };
+        const en = this.i18next.getFixedT("en", namespace);
+        const str = en(key, options);
+        if (typeof str !== "string")
+            throw new Error("Translation key(s) not found");
+        return str;
+    }
+    /** Get the promise for an already registered Namespace.
+     * @param name - the name of the namespace
+     * @public
+     */
+    getNamespacePromise(name) {
+        return this._namespaces.get(name);
+    }
+    /** @internal */
+    getLanguageList() {
+        return this.i18next.languages;
+    }
+    /** override the language detected in the browser  */
+    async changeLanguage(language) {
+        return this.i18next.changeLanguage(language);
+    }
+    /** Register a new Namespace and return it. If the namespace is already registered, it will be returned.
+     * @param name - the name of the namespace, which is the base name of the JSON file that contains the localization properties.
+     * @note - The registerNamespace method starts fetching the appropriate version of the JSON localization file from the server,
+     * based on the current locale. To make sure that fetch is complete before performing translations from this namespace, await
+     * fulfillment of the readPromise Promise property of the returned LocalizationNamespace.
+     * @see [Localization in iTwin.js]($docs/learning/frontend/Localization.md)
+     * @public
+     */
+    async registerNamespace(name) {
+        const existing = this._namespaces.get(name);
+        if (existing !== undefined)
+            return existing;
+        const theReadPromise = new Promise((resolve) => {
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            this.i18next.loadNamespaces(name, (err) => {
+                if (!err)
+                    return resolve();
+                // Here we got a non-null err object.
+                // This method is called when the system has attempted to load the resources for the namespaces for each possible locale.
+                // For example 'fr-ca' might be the most specific locale, in which case 'fr' and 'en' are fallback locales.
+                // Using Backend from i18next-http-backend, err will be an array of strings of each namespace it tried to read and its locale.
+                // There might be errs for some other namespaces as well as this one. We resolve the promise unless there's an error for each possible locale.
+                let locales = this.getLanguageList().map((thisLocale) => `/${thisLocale}/`);
+                try {
+                    for (const thisError of err) {
+                        if (typeof thisError === "string")
+                            locales = locales.filter((thisLocale) => !thisError.includes(thisLocale));
+                    }
+                }
+                catch (e) {
+                    locales = [];
+                }
+                // if we removed every locale from the array, it wasn't loaded.
+                if (locales.length === 0)
+                    Logger.logError("i18n", `No resources for namespace ${name} could be loaded`);
+                resolve();
+            });
+        });
+        this._namespaces.set(name, theReadPromise);
+        return theReadPromise;
+    }
+    /** @internal */
+    unregisterNamespace(name) {
+        this._namespaces.delete(name);
+    }
+}
+class TranslationLogger {
+    log(args) { Logger.logInfo("i18n", this.createLogMessage(args)); }
+    warn(args) { Logger.logWarning("i18n", this.createLogMessage(args)); }
+    error(args) { Logger.logError("i18n", this.createLogMessage(args)); }
+    createLogMessage(args) {
+        let message = args[0];
+        for (let i = 1; i < args.length; ++i) {
+            if (typeof args[i] === "string")
+                message += `\n  ${args[i]}`;
+        }
+        return message;
+    }
+}
+TranslationLogger.type = "logger";
 //# sourceMappingURL=ITwinLocalization.js.map

package/lib/esm/ITwinLocalization.js.map

@@ -1 +1 @@
-{"version":3,"file":"ITwinLocalization.js","sourceRoot":"","sources":["../../src/ITwinLocalization.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Localization\r\n */\r\n\r\nimport i18next, { i18n, InitOptions, Module, TOptionsBase } from \"i18next\";\r\nimport i18nextBrowserLanguageDetector, { DetectorOptions } from \"i18next-browser-languagedetector\";\r\nimport Backend, { BackendOptions } from \"i18next-http-backend\";\r\nimport { Logger } from \"@itwin/core-bentley\";\r\nimport type { Localization } from \"@itwin/core-common\";\r\n\r\nconst DEFAULT_MAX_RETRIES: number = 1; // a low number prevents wasted time and potential timeouts when requesting localization files throws an error\r\n\r\n/** Options for ITwinLocalization\r\n *  @public\r\n */\r\nexport interface LocalizationOptions {\r\n  urlTemplate?: string;\r\n  backendPlugin?: Module;\r\n  detectorPlugin?: Module;\r\n  initOptions?: InitOptions;\r\n  backendHttpOptions?: BackendOptions;\r\n  detectorOptions?: DetectorOptions;\r\n}\r\n\r\n/** Supplies localizations for iTwin.js\r\n * @note this class uses the [i18next](https://www.i18next.com/) package.\r\n * @public\r\n */\r\nexport class ITwinLocalization implements Localization {\r\n  public i18next: i18n;\r\n  private readonly _initOptions: InitOptions;\r\n  private readonly _backendOptions: BackendOptions;\r\n  private readonly _detectionOptions: DetectorOptions;\r\n  private readonly _namespaces = new Map<string, Promise<void>>();\r\n\r\n  public constructor(options?: LocalizationOptions) {\r\n    this.i18next = i18next.createInstance();\r\n\r\n    this._backendOptions = {\r\n      loadPath: options?.urlTemplate ?? \"locales/{{lng}}/{{ns}}.json\",\r\n      crossDomain: true,\r\n      ...options?.backendHttpOptions,\r\n    };\r\n\r\n    this._detectionOptions = {\r\n      order: [\"querystring\", \"navigator\", \"htmlTag\"],\r\n      lookupQuerystring: \"lng\",\r\n      caches: [],\r\n      ...options?.detectorOptions,\r\n    };\r\n\r\n    this._initOptions = {\r\n      interpolation: { escapeValue: true },\r\n      fallbackLng: \"en\",\r\n      maxRetries: DEFAULT_MAX_RETRIES,\r\n      backend: this._backendOptions,\r\n      detection: this._detectionOptions,\r\n      ...options?.initOptions,\r\n    };\r\n\r\n    this.i18next\r\n      .use(options?.detectorPlugin ?? i18nextBrowserLanguageDetector)\r\n      .use(options?.backendPlugin ?? Backend)\r\n      .use(TranslationLogger);\r\n  }\r\n\r\n  public async initialize(namespaces: string[]): Promise<void> {\r\n\r\n    // Also consider namespaces passed into constructor\r\n    const initNamespaces: string[] = [this._initOptions.ns || []].flat();\r\n    const combinedNamespaces: Set<string> = new Set([...namespaces, ...initNamespaces]); // without duplicates\r\n\r\n    const defaultNamespace: string | false | readonly string[] = this._initOptions.defaultNS ?? namespaces[0];\r\n    if (defaultNamespace)\r\n      combinedNamespaces.add(defaultNamespace as string); // Make sure default namespace is in namespaces list\r\n\r\n    const initOptions: InitOptions = {\r\n      ...this._initOptions,\r\n      defaultNS: defaultNamespace,\r\n      ns: [...combinedNamespaces],\r\n    };\r\n\r\n    // if in a development environment, set debugging\r\n    if (process.env.NODE_ENV === \"development\")\r\n      initOptions.debug = true;\r\n\r\n    const initPromise = this.i18next.init(initOptions) as unknown as Promise<void>;\r\n\r\n    for (const ns of namespaces)\r\n      this._namespaces.set(ns, initPromise);\r\n\r\n    return initPromise;\r\n  }\r\n\r\n  /** Replace all instances of `%{key}` within a string with the translations of those keys.\r\n   * For example:\r\n   * ``` ts\r\n   * \"MyKeys\": {\r\n   *   \"Key1\": \"First value\",\r\n   *   \"Key2\": \"Second value\"\r\n   *  }\r\n   * ```\r\n   *\r\n   * ``` ts\r\n   * i18.translateKeys(\"string with %{MyKeys.Key1} followed by %{MyKeys.Key2}!\"\") // returns \"string with First Value followed by Second Value!\"\r\n   * ```\r\n   * @param line The input line, potentially containing %{keys}.\r\n   * @returns The line with all %{keys} translated\r\n   * @public\r\n   */\r\n  public getLocalizedKeys(line: string): string {\r\n    return line.replace(/\\%\\{(.+?)\\}/g, (_match, tag) => this.getLocalizedString(tag));\r\n  }\r\n\r\n  /** Return the translated value of a key.\r\n   * @param key - the key that matches a property in the JSON localization file.\r\n   * @note The key includes the namespace, which identifies the particular localization file that contains the property,\r\n   * followed by a colon, followed by the property in the JSON file.\r\n   * For example:\r\n   * ``` ts\r\n   * const dataString: string = IModelApp.localization.getLocalizedString(\"iModelJs:BackgroundMap.BingDataAttribution\");\r\n   *  ```\r\n   * assigns to dataString the string with property BackgroundMap.BingDataAttribution from the iModelJs.json localization file.\r\n   * @returns The string corresponding to the first key that resolves.\r\n   * @throws Error if no keys resolve to a string.\r\n   * @public\r\n   */\r\n  public getLocalizedString(key: string | string[], options?: TOptionsBase): string {\r\n    if (options?.returnDetails || options?.returnObjects) {\r\n      throw new Error(\"Translation key must map to a string, but the given options will result in an object\");\r\n    }\r\n\r\n    const value = this.i18next.t(key, options);\r\n\r\n    if (typeof value !== \"string\") {\r\n      throw new Error(\"Translation key(s) string not found\");\r\n    }\r\n\r\n    return value;\r\n  }\r\n\r\n  /** Similar to `getLocalizedString` but the default namespace is a separate parameter and the key does not need\r\n   * to include a namespace. If a key includes a namespace, that namespace will be used for interpolating that key.\r\n   * @param namespace - the namespace that identifies the particular localization file that contains the property.\r\n   * @param key - the key that matches a property in the JSON localization file.\r\n   * @returns The string corresponding to the first key that resolves.\r\n   * @throws Error if no keys resolve to a string.\r\n   * @internal\r\n   */\r\n  public getLocalizedStringWithNamespace(namespace: string, key: string | string[], options?: TOptionsBase): string {\r\n    let fullKey: string | string[] = \"\";\r\n\r\n    if (typeof key === \"string\") {\r\n      fullKey = `${namespace}:${key}`;\r\n    } else {\r\n      fullKey = key.map((subKey: string) => {\r\n        return `${namespace}:${subKey}`;\r\n      });\r\n    }\r\n\r\n    return this.getLocalizedString(fullKey, options);\r\n  }\r\n\r\n  /** Gets the English translation.\r\n   * @param namespace - the namespace that identifies the particular localization file that contains the property.\r\n   * @param key - the key that matches a property in the JSON localization file.\r\n   * @returns The string corresponding to the first key that resolves.\r\n   * @throws Error if no keys resolve to a string.\r\n   * @internal\r\n   */\r\n  public getEnglishString(namespace: string, key: string | string[], options?: TOptionsBase): string {\r\n    if (options?.returnDetails || options?.returnObjects) {\r\n      throw new Error(\"Translation key must map to a string, but the given options will result in an object\");\r\n    }\r\n\r\n    options = {\r\n      ...options,\r\n      ns: namespace, // ensure namespace argument is used\r\n    };\r\n\r\n    const en = this.i18next.getFixedT(\"en\", namespace);\r\n    const str = en(key, options);\r\n    if (typeof str !== \"string\")\r\n      throw new Error(\"Translation key(s) not found\");\r\n\r\n    return str;\r\n  }\r\n\r\n  /** Get the promise for an already registered Namespace.\r\n   * @param name - the name of the namespace\r\n   * @public\r\n   */\r\n  public getNamespacePromise(name: string): Promise<void> | undefined {\r\n    return this._namespaces.get(name);\r\n  }\r\n\r\n  /** @internal */\r\n  public getLanguageList(): readonly string[] {\r\n    return this.i18next.languages;\r\n  }\r\n\r\n  /** override the language detected in the browser  */\r\n  public async changeLanguage(language: string) {\r\n    return this.i18next.changeLanguage(language) as unknown as Promise<void>;\r\n  }\r\n\r\n  /** Register a new Namespace and return it. If the namespace is already registered, it will be returned.\r\n   * @param name - the name of the namespace, which is the base name of the JSON file that contains the localization properties.\r\n   * @note - The registerNamespace method starts fetching the appropriate version of the JSON localization file from the server,\r\n   * based on the current locale. To make sure that fetch is complete before performing translations from this namespace, await\r\n   * fulfillment of the readPromise Promise property of the returned LocalizationNamespace.\r\n   * @see [Localization in iTwin.js]($docs/learning/frontend/Localization.md)\r\n   * @public\r\n   */\r\n  public async registerNamespace(name: string): Promise<void> {\r\n    const existing = this._namespaces.get(name);\r\n    if (existing !== undefined)\r\n      return existing;\r\n\r\n    const theReadPromise = new Promise<void>((resolve) => {\r\n      // eslint-disable-next-line @typescript-eslint/no-floating-promises\r\n      this.i18next.loadNamespaces(name, (err) => {\r\n        if (!err)\r\n          return resolve();\r\n\r\n        // Here we got a non-null err object.\r\n        // This method is called when the system has attempted to load the resources for the namespaces for each possible locale.\r\n        // For example 'fr-ca' might be the most specific locale, in which case 'fr' and 'en' are fallback locales.\r\n        // Using Backend from i18next-http-backend, err will be an array of strings of each namespace it tried to read and its locale.\r\n        // There might be errs for some other namespaces as well as this one. We resolve the promise unless there's an error for each possible locale.\r\n        let locales = this.getLanguageList().map((thisLocale: any) => `/${thisLocale}/`);\r\n\r\n        try {\r\n          for (const thisError of err) {\r\n            if (typeof thisError === \"string\")\r\n              locales = locales.filter((thisLocale) => !thisError.includes(thisLocale));\r\n          }\r\n        } catch (e) {\r\n          locales = [];\r\n        }\r\n        // if we removed every locale from the array, it wasn't loaded.\r\n        if (locales.length === 0)\r\n          Logger.logError(\"i18n\", `No resources for namespace ${name} could be loaded`);\r\n\r\n        resolve();\r\n      });\r\n    });\r\n    this._namespaces.set(name, theReadPromise);\r\n    return theReadPromise;\r\n  }\r\n\r\n  /** @internal */\r\n  public unregisterNamespace(name: string): void {\r\n    this._namespaces.delete(name);\r\n  }\r\n}\r\n\r\nclass TranslationLogger {\r\n  public static readonly type = \"logger\";\r\n  public log(args: string[]) { Logger.logInfo(\"i18n\", this.createLogMessage(args)); }\r\n  public warn(args: string[]) { Logger.logWarning(\"i18n\", this.createLogMessage(args)); }\r\n  public error(args: string[]) { Logger.logError(\"i18n\", this.createLogMessage(args)); }\r\n  private createLogMessage(args: string[]) {\r\n    let message = args[0];\r\n    for (let i = 1; i < args.length; ++i) {\r\n      if (typeof args[i] === \"string\")\r\n        message += `\\n  ${args[i]}`;\r\n    }\r\n    return message;\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"ITwinLocalization.js","sourceRoot":"","sources":["../../src/ITwinLocalization.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Localization\r\n */\r\n\r\nimport i18next, { i18n, InitOptions, Module, TOptionsBase } from \"i18next\";\r\nimport i18nextBrowserLanguageDetector, { DetectorOptions } from \"i18next-browser-languagedetector\";\r\nimport Backend, { BackendOptions } from \"i18next-http-backend\";\r\nimport { Logger } from \"@itwin/core-bentley\";\r\nimport type { Localization } from \"@itwin/core-common\";\r\n\r\nconst DEFAULT_MAX_RETRIES: number = 1; // a low number prevents wasted time and potential timeouts when requesting localization files throws an error\r\n\r\n/** Options for ITwinLocalization\r\n *  @public\r\n */\r\nexport interface LocalizationOptions {\r\n  urlTemplate?: string;\r\n  backendPlugin?: Module;\r\n  detectorPlugin?: Module;\r\n  initOptions?: InitOptions;\r\n  backendHttpOptions?: BackendOptions;\r\n  detectorOptions?: DetectorOptions;\r\n}\r\n\r\n/** Supplies localizations for iTwin.js\r\n * @note this class uses the [i18next](https://www.i18next.com/) package.\r\n * @public\r\n */\r\nexport class ITwinLocalization implements Localization {\r\n  public i18next: i18n;\r\n  private readonly _initOptions: InitOptions;\r\n  private readonly _backendOptions: BackendOptions;\r\n  private readonly _detectionOptions: DetectorOptions;\r\n  private readonly _namespaces = new Map<string, Promise<void>>();\r\n\r\n  public constructor(options?: LocalizationOptions) {\r\n    this.i18next = i18next.createInstance();\r\n\r\n    this._backendOptions = {\r\n      loadPath: options?.urlTemplate ?? \"locales/{{lng}}/{{ns}}.json\",\r\n      crossDomain: true,\r\n      ...options?.backendHttpOptions,\r\n    };\r\n\r\n    this._detectionOptions = {\r\n      order: [\"querystring\", \"navigator\", \"htmlTag\"],\r\n      lookupQuerystring: \"lng\",\r\n      caches: [],\r\n      ...options?.detectorOptions,\r\n    };\r\n\r\n    this._initOptions = {\r\n      interpolation: { escapeValue: true },\r\n      fallbackLng: \"en\",\r\n      maxRetries: DEFAULT_MAX_RETRIES,\r\n      backend: this._backendOptions,\r\n      detection: this._detectionOptions,\r\n      ...options?.initOptions,\r\n    };\r\n\r\n    this.i18next\r\n      .use(options?.detectorPlugin ?? i18nextBrowserLanguageDetector)\r\n      .use(options?.backendPlugin ?? Backend)\r\n      .use(TranslationLogger);\r\n  }\r\n\r\n  public async initialize(namespaces: string[]): Promise<void> {\r\n\r\n    // Also consider namespaces passed into constructor\r\n    const initNamespaces: string[] = [this._initOptions.ns || []].flat();\r\n    const combinedNamespaces: Set<string> = new Set([...namespaces, ...initNamespaces]); // without duplicates\r\n\r\n    const defaultNamespace: string | false | readonly string[] = this._initOptions.defaultNS ?? namespaces[0];\r\n    if (defaultNamespace)\r\n      combinedNamespaces.add(defaultNamespace as string); // Make sure default namespace is in namespaces list\r\n\r\n    const initOptions: InitOptions = {\r\n      ...this._initOptions,\r\n      defaultNS: defaultNamespace,\r\n      ns: [...combinedNamespaces],\r\n    };\r\n\r\n    // if in a development environment, set debugging\r\n    if (process.env.NODE_ENV === \"development\")\r\n      initOptions.debug = true;\r\n\r\n    const initPromise = this.i18next.init(initOptions) as unknown as Promise<void>;\r\n\r\n    for (const ns of namespaces)\r\n      this._namespaces.set(ns, initPromise);\r\n\r\n    return initPromise;\r\n  }\r\n\r\n  /** Replace all instances of `%{key}` within a string with the translations of those keys.\r\n   * For example:\r\n   * ``` ts\r\n   * \"MyKeys\": {\r\n   *   \"Key1\": \"First value\",\r\n   *   \"Key2\": \"Second value\"\r\n   *  }\r\n   * ```\r\n   *\r\n   * ``` ts\r\n   * i18.translateKeys(\"string with %{MyKeys.Key1} followed by %{MyKeys.Key2}!\"\") // returns \"string with First Value followed by Second Value!\"\r\n   * ```\r\n   * @param line The input line, potentially containing %{keys}.\r\n   * @returns The line with all %{keys} translated\r\n   * @public\r\n   */\r\n  public getLocalizedKeys(line: string): string {\r\n    return line.replace(/\\%\\{(.+?)\\}/g, (_match, tag) => this.getLocalizedString(tag));\r\n  }\r\n\r\n  /** Return the translated value of a key.\r\n   * @param key - the key that matches a property in the JSON localization file.\r\n   * @note The key includes the namespace, which identifies the particular localization file that contains the property,\r\n   * followed by a colon, followed by the property in the JSON file.\r\n   * For example:\r\n   * ``` ts\r\n   * const dataString: string = IModelApp.localization.getLocalizedString(\"iModelJs:BackgroundMap.BingDataAttribution\");\r\n   *  ```\r\n   * assigns to dataString the string with property BackgroundMap.BingDataAttribution from the iModelJs.json localization file.\r\n   * @returns The string corresponding to the first key that resolves.\r\n   * @throws Error if no keys resolve to a string.\r\n   * @public\r\n   */\r\n  public getLocalizedString(key: string | string[], options?: TOptionsBase): string {\r\n    if (options?.returnDetails || options?.returnObjects) {\r\n      throw new Error(\"Translation key must map to a string, but the given options will result in an object\");\r\n    }\r\n\r\n    const value = this.i18next.t(key, options);\r\n\r\n    if (typeof value !== \"string\") {\r\n      throw new Error(\"Translation key(s) string not found\");\r\n    }\r\n\r\n    return value;\r\n  }\r\n\r\n  /** Similar to `getLocalizedString` but the default namespace is a separate parameter and the key does not need\r\n   * to include a namespace. If a key includes a namespace, that namespace will be used for interpolating that key.\r\n   * @param namespace - the namespace that identifies the particular localization file that contains the property.\r\n   * @param key - the key that matches a property in the JSON localization file.\r\n   * @returns The string corresponding to the first key that resolves.\r\n   * @throws Error if no keys resolve to a string.\r\n   * @internal\r\n   */\r\n  public getLocalizedStringWithNamespace(namespace: string, key: string | string[], options?: TOptionsBase): string {\r\n    let fullKey: string | string[] = \"\";\r\n\r\n    if (typeof key === \"string\") {\r\n      fullKey = `${namespace}:${key}`;\r\n    } else {\r\n      fullKey = key.map((subKey: string) => {\r\n        return `${namespace}:${subKey}`;\r\n      });\r\n    }\r\n\r\n    return this.getLocalizedString(fullKey, options);\r\n  }\r\n\r\n  /** Gets the English translation.\r\n   * @param namespace - the namespace that identifies the particular localization file that contains the property.\r\n   * @param key - the key that matches a property in the JSON localization file.\r\n   * @returns The string corresponding to the first key that resolves.\r\n   * @throws Error if no keys resolve to a string.\r\n   * @internal\r\n   */\r\n  public getEnglishString(namespace: string, key: string | string[], options?: TOptionsBase): string {\r\n    if (options?.returnDetails || options?.returnObjects) {\r\n      throw new Error(\"Translation key must map to a string, but the given options will result in an object\");\r\n    }\r\n\r\n    options = {\r\n      ...options,\r\n      ns: namespace, // ensure namespace argument is used\r\n    };\r\n\r\n    const en = this.i18next.getFixedT(\"en\", namespace);\r\n    const str = en(key, options);\r\n    if (typeof str !== \"string\")\r\n      throw new Error(\"Translation key(s) not found\");\r\n\r\n    return str;\r\n  }\r\n\r\n  /** Get the promise for an already registered Namespace.\r\n   * @param name - the name of the namespace\r\n   * @public\r\n   */\r\n  public getNamespacePromise(name: string): Promise<void> | undefined {\r\n    return this._namespaces.get(name);\r\n  }\r\n\r\n  /** @internal */\r\n  public getLanguageList(): readonly string[] {\r\n    return this.i18next.languages;\r\n  }\r\n\r\n  /** override the language detected in the browser  */\r\n  public async changeLanguage(language: string) {\r\n    return this.i18next.changeLanguage(language) as unknown as Promise<void>;\r\n  }\r\n\r\n  /** Register a new Namespace and return it. If the namespace is already registered, it will be returned.\r\n   * @param name - the name of the namespace, which is the base name of the JSON file that contains the localization properties.\r\n   * @note - The registerNamespace method starts fetching the appropriate version of the JSON localization file from the server,\r\n   * based on the current locale. To make sure that fetch is complete before performing translations from this namespace, await\r\n   * fulfillment of the readPromise Promise property of the returned LocalizationNamespace.\r\n   * @see [Localization in iTwin.js]($docs/learning/frontend/Localization.md)\r\n   * @public\r\n   */\r\n  public async registerNamespace(name: string): Promise<void> {\r\n    const existing = this._namespaces.get(name);\r\n    if (existing !== undefined)\r\n      return existing;\r\n\r\n    const theReadPromise = new Promise<void>((resolve) => {\r\n      // eslint-disable-next-line @typescript-eslint/no-floating-promises\r\n      this.i18next.loadNamespaces(name, (err) => {\r\n        if (!err)\r\n          return resolve();\r\n\r\n        // Here we got a non-null err object.\r\n        // This method is called when the system has attempted to load the resources for the namespaces for each possible locale.\r\n        // For example 'fr-ca' might be the most specific locale, in which case 'fr' and 'en' are fallback locales.\r\n        // Using Backend from i18next-http-backend, err will be an array of strings of each namespace it tried to read and its locale.\r\n        // There might be errs for some other namespaces as well as this one. We resolve the promise unless there's an error for each possible locale.\r\n        let locales = this.getLanguageList().map((thisLocale: any) => `/${thisLocale}/`);\r\n\r\n        try {\r\n          for (const thisError of err) {\r\n            if (typeof thisError === \"string\")\r\n              locales = locales.filter((thisLocale) => !thisError.includes(thisLocale));\r\n          }\r\n        } catch (e) {\r\n          locales = [];\r\n        }\r\n        // if we removed every locale from the array, it wasn't loaded.\r\n        if (locales.length === 0)\r\n          Logger.logError(\"i18n\", `No resources for namespace ${name} could be loaded`);\r\n\r\n        resolve();\r\n      });\r\n    });\r\n    this._namespaces.set(name, theReadPromise);\r\n    return theReadPromise;\r\n  }\r\n\r\n  /** @internal */\r\n  public unregisterNamespace(name: string): void {\r\n    this._namespaces.delete(name);\r\n  }\r\n}\r\n\r\nclass TranslationLogger {\r\n  public static readonly type = \"logger\";\r\n  public log(args: string[]) { Logger.logInfo(\"i18n\", this.createLogMessage(args)); }\r\n  public warn(args: string[]) { Logger.logWarning(\"i18n\", this.createLogMessage(args)); }\r\n  public error(args: string[]) { Logger.logError(\"i18n\", this.createLogMessage(args)); }\r\n  private createLogMessage(args: string[]) {\r\n    let message = args[0];\r\n    for (let i = 1; i < args.length; ++i) {\r\n      if (typeof args[i] === \"string\")\r\n        message += `\\n  ${args[i]}`;\r\n    }\r\n    return message;\r\n  }\r\n}\r\n"]}

package/lib/esm/core-i18n.d.ts

@@ -1,8 +1,8 @@
-export * from "./ITwinLocalization";
-/** @docs-package-description
- * The core-i18n package contains classes related to internationalization and localization.
- */
-/** @docs-group-description Localization
- * Classes for internationalization and localization of your app.
- */
+export * from "./ITwinLocalization";
+/** @docs-package-description
+ * The core-i18n package contains classes related to internationalization and localization.
+ */
+/** @docs-group-description Localization
+ * Classes for internationalization and localization of your app.
+ */
 //# sourceMappingURL=core-i18n.d.ts.map

package/lib/esm/core-i18n.js

@@ -1,12 +1,12 @@
-/*---------------------------------------------------------------------------------------------
-* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
-* See LICENSE.md in the project root for license terms and full copyright notice.
-*--------------------------------------------------------------------------------------------*/
-export * from "./ITwinLocalization";
-/** @docs-package-description
- * The core-i18n package contains classes related to internationalization and localization.
- */
-/** @docs-group-description Localization
- * Classes for internationalization and localization of your app.
- */
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+export * from "./ITwinLocalization";
+/** @docs-package-description
+ * The core-i18n package contains classes related to internationalization and localization.
+ */
+/** @docs-group-description Localization
+ * Classes for internationalization and localization of your app.
+ */
 //# sourceMappingURL=core-i18n.js.map

package/lib/esm/test/ITwinLocalization.test.d.ts

@@ -1,2 +1,2 @@
-export {};
+export {};
 //# sourceMappingURL=ITwinLocalization.test.d.ts.map