@aidc-toolkit/core 0.9.6-beta → 0.9.8-beta

package/README.md

@@ -5,29 +5,81 @@ any of the functionality of the AIDC Toolkit. It is a required dependency for al
 
 All AIDC Toolkit packages require localization. The localization functionality in this package simplifies initialization
 and allows packages to share a common internationalization engine, whose initialization is the responsibility of the
-client application. Packages install their resources as follows in `i18n.ts` or similar:
+client application. Each package requires its own internationalization object and each is responsible for initializing
+those of its dependencies.
+
+Packages install their resources as follows in `i18n.ts` or similar:
 
 ```typescript
-import { i18nAddResourceBundle, i18next } from "@aidc-toolkit/core";
-import { localeStrings as enLocaleStrings } from "./en/locale_strings.js";
+import { i18nAssertValidResources, i18nCoreInit, type I18NEnvironment } from "@aidc-toolkit/core";
+import { i18nDependency1Init, dependency1Resources } from "@aidc-toolkit/dependency1";
+import { i18nDependency2Init, dependency2Resources } from "@aidc-toolkit/dependency2";
+import i18next from "i18next";
+import { localeStrings as enLocaleStrings } from "./en/locale-strings.js";
+import { localeStrings as frLocaleStrings } from "./fr/locale-strings.js";
 
 export const packageNS = "aidct_package";
 
-i18nAddResourceBundle("en", packageNS, enLocaleStrings);
+/**
+ * Locale strings type is extracted from the English locale strings object.
+ */
+export type PackageLocaleStrings = typeof enLocaleStrings;
+
+i18nAssertValidResources(enLocaleStrings, "fr", frLocaleStrings);
+
+/**
+ * Package resources.
+ */
+export const packageResources = {
+    en: {
+        aidct_package: enLocaleStrings
+    },
+    fr: {
+        aidct_package: frLocaleStrings
+    }
+};
+
+export const i18nextPackage = i18next.createInstance();
 
-export default i18next;
+/**
+ * Initialize internationalization.
+ *
+ * @param environment
+ * Environment in which the application is running.
+ *
+ * @param debug
+ * Debug setting.
+ *
+ * @returns
+ * Void promise.
+ */
+export async function i18nPackageInit(environment: I18NEnvironment, debug = false): Promise<void> {
+    await i18nDependency1Init(environment, debug);
+    await i18nDependency2Init(environment, debug);
+    await i18nCoreInit(i18nextPackage, environment, debug, packageNS, dependency1Resources, dependency2Resources, packageResources);
+}
 ```
 
 The resource types are declared in `i18next.d.ts` or similar:
 
 ```typescript
-import type { localeStrings } from "./en/locale_strings.js";
+import type { Dependency1LocaleStrings } from "@aidc-toolkit/dependency1";
+import type { Dependency2LocaleStrings } from "@aidc-toolkit/dependency2";
+import type { PackageLocaleStrings } from "./i18n.js";
 
+/**
+ * Internationalization module.
+ */
 declare module "i18next" {
+    /**
+     * Custom type options for this package.
+     */
     interface CustomTypeOptions {
+        defaultNS: "aidct_package";
         resources: {
-            // Extract the type from the English locale strings object.
-            aidct_package: typeof localeStrings;
+            aidct_dependency1: Dependency1LocaleStrings;
+            aidct_dependency2: Dependency2LocaleStrings;
+            aidct_package: PackageLocaleStrings;
         };
     }
 }

package/dist/index.cjs

@@ -31,68 +31,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   I18NEnvironment: () => I18NEnvironment,
-  i18nAddResourceBundle: () => i18nAddResourceBundle,
   i18nAssertValidResources: () => i18nAssertValidResources,
-  i18nInit: () => i18nInit,
-  i18next: () => i18n_default
+  i18nCoreInit: () => i18nCoreInit
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/locale/i18n.ts
-var import_i18next = __toESM(require("i18next"), 1);
 var import_i18next_browser_languagedetector = __toESM(require("i18next-browser-languagedetector"), 1);
 var import_i18next_cli_language_detector = __toESM(require("i18next-cli-language-detector"), 1);
-var i18n_default = import_i18next.default;
-var pendingResourceBundles = [];
 var I18NEnvironment = /* @__PURE__ */ ((I18NEnvironment2) => {
   I18NEnvironment2[I18NEnvironment2["CLI"] = 0] = "CLI";
   I18NEnvironment2[I18NEnvironment2["Server"] = 1] = "Server";
   I18NEnvironment2[I18NEnvironment2["Browser"] = 2] = "Browser";
   return I18NEnvironment2;
 })(I18NEnvironment || {});
-async function i18nInit(environment, debug = false) {
-  let initialized;
-  if (pendingResourceBundles !== void 0) {
-    initialized = true;
-    let module2;
-    switch (environment) {
-      case 0 /* CLI */:
-        module2 = import_i18next_cli_language_detector.default;
-        break;
-      case 2 /* Browser */:
-        module2 = import_i18next_browser_languagedetector.default;
-        break;
-      default:
-        throw new Error("Not supported");
-    }
-    const initResourceBundles = pendingResourceBundles;
-    pendingResourceBundles = void 0;
-    await import_i18next.default.use(module2).init({
-      fallbackLng: "en",
-      debug,
-      resources: {}
-    }).then(() => {
-      import_i18next.default.services.formatter?.add("toLowerCase", (value) => typeof value === "string" ? value.toLowerCase() : String(value));
-      for (const initResourceBundle of initResourceBundles) {
-        i18nAddResourceBundle(initResourceBundle.lng, initResourceBundle.ns, initResourceBundle.resources);
-      }
-    });
-  } else {
-    initialized = false;
-  }
-  return initialized;
-}
-function i18nAddResourceBundle(lng, ns, resources) {
-  if (pendingResourceBundles !== void 0) {
-    pendingResourceBundles.push({
-      lng,
-      ns,
-      resources
-    });
-  } else {
-    import_i18next.default.addResourceBundle(lng, ns, resources);
-  }
-}
 function i18nAssertValidResources(enResources, lng, lngResources, parent) {
   const enResourcesMap = new Map(Object.entries(enResources));
   const lngResourcesMap = new Map(Object.entries(lngResources));
@@ -118,11 +70,47 @@ function i18nAssertValidResources(enResources, lng, lngResources, parent) {
     }
   }
 }
+function toLowerCase(s) {
+  return s.split(" ").map((word) => /[a-z]/.test(word) ? word.toLowerCase() : word).join(" ");
+}
+async function i18nCoreInit(i18next, environment, debug, defaultNS, ...resources) {
+  if (!i18next.isInitialized) {
+    const mergedResource = {};
+    for (const resource of resources) {
+      for (const [language, resourceLanguage] of Object.entries(resource)) {
+        if (!(language in mergedResource)) {
+          mergedResource[language] = {};
+        }
+        const mergedResourceLanguage = mergedResource[language];
+        for (const [namespace, resourceKey] of Object.entries(resourceLanguage)) {
+          mergedResourceLanguage[namespace] = resourceKey;
+        }
+      }
+    }
+    let module2;
+    switch (environment) {
+      case 0 /* CLI */:
+        module2 = import_i18next_cli_language_detector.default;
+        break;
+      case 2 /* Browser */:
+        module2 = import_i18next_browser_languagedetector.default;
+        break;
+      default:
+        throw new Error("Not supported");
+    }
+    await i18next.use(module2).init({
+      debug,
+      resources: mergedResource,
+      fallbackLng: "en",
+      defaultNS
+    }).then(() => {
+      i18next.services.formatter?.add("toLowerCase", (value) => typeof value === "string" ? toLowerCase(value) : String(value));
+    });
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   I18NEnvironment,
-  i18nAddResourceBundle,
   i18nAssertValidResources,
-  i18nInit,
-  i18next
+  i18nCoreInit
 });

package/dist/index.d.cts

@@ -1,5 +1,4 @@
-import i18next from 'i18next';
-export { default as i18next } from 'i18next';
+import { i18n, Resource } from 'i18next';
 
 /**
  * Internationalization operating environment.
@@ -18,32 +17,6 @@ declare enum I18NEnvironment {
      */
     Browser = 2
 }
-/**
- * Initialize internationalization.
- *
- * @param environment
- * Environment in which the application is running.
- *
- * @param debug
- * Debug setting.
- *
- * @returns
- * True if initialization was completed, false if skipped (already initialized).
- */
-declare function i18nInit(environment: I18NEnvironment, debug?: boolean): Promise<boolean>;
-/**
- * Add a resource bundle.
- *
- * @param lng
- * Language.
- *
- * @param ns
- * Namespace.
- *
- * @param resources
- * Resources.
- */
-declare function i18nAddResourceBundle(lng: string, ns: string, resources: object): void;
 /**
  * Assert that language resources are a type match for English (default) resources.
  *
@@ -60,5 +33,28 @@ declare function i18nAddResourceBundle(lng: string, ns: string, resources: objec
  * Parent key name (set recursively).
  */
 declare function i18nAssertValidResources(enResources: object, lng: string, lngResources: object, parent?: string): void;
+/**
+ * Initialize internationalization.
+ *
+ * @param i18next
+ * Internationalization object. As multiple objects exists, this parameter represents the one for the module for which
+ * internationalization is being initialized.
+ *
+ * @param environment
+ * Environment in which the application is running.
+ *
+ * @param debug
+ * Debug setting.
+ *
+ * @param defaultNS
+ * Default namespace.
+ *
+ * @param resources
+ * Resources.
+ *
+ * @returns
+ * Void promise.
+ */
+declare function i18nCoreInit(i18next: i18n, environment: I18NEnvironment, debug: boolean, defaultNS: string, ...resources: Resource[]): Promise<void>;
 
-export { I18NEnvironment, i18nAddResourceBundle, i18nAssertValidResources, i18nInit };
+export { I18NEnvironment, i18nAssertValidResources, i18nCoreInit };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import i18next from 'i18next';
-export { default as i18next } from 'i18next';
+import { i18n, Resource } from 'i18next';
 
 /**
  * Internationalization operating environment.
@@ -18,32 +17,6 @@ declare enum I18NEnvironment {
      */
     Browser = 2
 }
-/**
- * Initialize internationalization.
- *
- * @param environment
- * Environment in which the application is running.
- *
- * @param debug
- * Debug setting.
- *
- * @returns
- * True if initialization was completed, false if skipped (already initialized).
- */
-declare function i18nInit(environment: I18NEnvironment, debug?: boolean): Promise<boolean>;
-/**
- * Add a resource bundle.
- *
- * @param lng
- * Language.
- *
- * @param ns
- * Namespace.
- *
- * @param resources
- * Resources.
- */
-declare function i18nAddResourceBundle(lng: string, ns: string, resources: object): void;
 /**
  * Assert that language resources are a type match for English (default) resources.
  *
@@ -60,5 +33,28 @@ declare function i18nAddResourceBundle(lng: string, ns: string, resources: objec
  * Parent key name (set recursively).
  */
 declare function i18nAssertValidResources(enResources: object, lng: string, lngResources: object, parent?: string): void;
+/**
+ * Initialize internationalization.
+ *
+ * @param i18next
+ * Internationalization object. As multiple objects exists, this parameter represents the one for the module for which
+ * internationalization is being initialized.
+ *
+ * @param environment
+ * Environment in which the application is running.
+ *
+ * @param debug
+ * Debug setting.
+ *
+ * @param defaultNS
+ * Default namespace.
+ *
+ * @param resources
+ * Resources.
+ *
+ * @returns
+ * Void promise.
+ */
+declare function i18nCoreInit(i18next: i18n, environment: I18NEnvironment, debug: boolean, defaultNS: string, ...resources: Resource[]): Promise<void>;
 
-export { I18NEnvironment, i18nAddResourceBundle, i18nAssertValidResources, i18nInit };
+export { I18NEnvironment, i18nAssertValidResources, i18nCoreInit };

package/dist/index.js

@@ -1,58 +1,12 @@
 // src/locale/i18n.ts
-import i18next from "i18next";
 import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
 import I18nextCLILanguageDetector from "i18next-cli-language-detector";
-var i18n_default = i18next;
-var pendingResourceBundles = [];
 var I18NEnvironment = /* @__PURE__ */ ((I18NEnvironment2) => {
   I18NEnvironment2[I18NEnvironment2["CLI"] = 0] = "CLI";
   I18NEnvironment2[I18NEnvironment2["Server"] = 1] = "Server";
   I18NEnvironment2[I18NEnvironment2["Browser"] = 2] = "Browser";
   return I18NEnvironment2;
 })(I18NEnvironment || {});
-async function i18nInit(environment, debug = false) {
-  let initialized;
-  if (pendingResourceBundles !== void 0) {
-    initialized = true;
-    let module;
-    switch (environment) {
-      case 0 /* CLI */:
-        module = I18nextCLILanguageDetector;
-        break;
-      case 2 /* Browser */:
-        module = I18nextBrowserLanguageDetector;
-        break;
-      default:
-        throw new Error("Not supported");
-    }
-    const initResourceBundles = pendingResourceBundles;
-    pendingResourceBundles = void 0;
-    await i18next.use(module).init({
-      fallbackLng: "en",
-      debug,
-      resources: {}
-    }).then(() => {
-      i18next.services.formatter?.add("toLowerCase", (value) => typeof value === "string" ? value.toLowerCase() : String(value));
-      for (const initResourceBundle of initResourceBundles) {
-        i18nAddResourceBundle(initResourceBundle.lng, initResourceBundle.ns, initResourceBundle.resources);
-      }
-    });
-  } else {
-    initialized = false;
-  }
-  return initialized;
-}
-function i18nAddResourceBundle(lng, ns, resources) {
-  if (pendingResourceBundles !== void 0) {
-    pendingResourceBundles.push({
-      lng,
-      ns,
-      resources
-    });
-  } else {
-    i18next.addResourceBundle(lng, ns, resources);
-  }
-}
 function i18nAssertValidResources(enResources, lng, lngResources, parent) {
   const enResourcesMap = new Map(Object.entries(enResources));
   const lngResourcesMap = new Map(Object.entries(lngResources));
@@ -78,10 +32,46 @@ function i18nAssertValidResources(enResources, lng, lngResources, parent) {
     }
   }
 }
+function toLowerCase(s) {
+  return s.split(" ").map((word) => /[a-z]/.test(word) ? word.toLowerCase() : word).join(" ");
+}
+async function i18nCoreInit(i18next, environment, debug, defaultNS, ...resources) {
+  if (!i18next.isInitialized) {
+    const mergedResource = {};
+    for (const resource of resources) {
+      for (const [language, resourceLanguage] of Object.entries(resource)) {
+        if (!(language in mergedResource)) {
+          mergedResource[language] = {};
+        }
+        const mergedResourceLanguage = mergedResource[language];
+        for (const [namespace, resourceKey] of Object.entries(resourceLanguage)) {
+          mergedResourceLanguage[namespace] = resourceKey;
+        }
+      }
+    }
+    let module;
+    switch (environment) {
+      case 0 /* CLI */:
+        module = I18nextCLILanguageDetector;
+        break;
+      case 2 /* Browser */:
+        module = I18nextBrowserLanguageDetector;
+        break;
+      default:
+        throw new Error("Not supported");
+    }
+    await i18next.use(module).init({
+      debug,
+      resources: mergedResource,
+      fallbackLng: "en",
+      defaultNS
+    }).then(() => {
+      i18next.services.formatter?.add("toLowerCase", (value) => typeof value === "string" ? toLowerCase(value) : String(value));
+    });
+  }
+}
 export {
   I18NEnvironment,
-  i18nAddResourceBundle,
   i18nAssertValidResources,
-  i18nInit,
-  i18n_default as i18next
+  i18nCoreInit
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/core",
-  "version": "0.9.6-beta",
+  "version": "0.9.8-beta",
   "description": "Core functionality for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -24,16 +24,16 @@
     "build-doc": "npm run build && tsc src/index.ts --outDir dist --target esnext --moduleResolution nodenext --module nodenext --emitDeclarationOnly --declaration --declarationMap"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "^0.9.6-beta",
+    "@aidc-toolkit/dev": "^0.9.8-beta",
     "eslint": "^9.16.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2"
   },
   "dependencies": {
-    "@rollup/rollup-linux-x64-gnu": "^4.28.0",
-    "i18next": "^24.0.5",
-    "i18next-browser-languagedetector": "^8.0.0",
+    "@rollup/rollup-linux-x64-gnu": "^4.28.1",
+    "i18next": "^24.1.0",
+    "i18next-browser-languagedetector": "^8.0.2",
     "i18next-cli-language-detector": "^1.1.8"
   }
 }

package/src/index.ts

@@ -1,2 +1 @@
 export * from "./locale/i18n.js";
-export { default as i18next } from "./locale/i18n.js";

package/src/locale/i18n.ts

@@ -1,23 +1,7 @@
-import i18next, { type LanguageDetectorModule } from "i18next";
+import type { i18n, LanguageDetectorModule, Resource } from "i18next";
 import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
 import I18nextCLILanguageDetector from "i18next-cli-language-detector";
 
-export default i18next;
-
-/**
- * Internal type to maintain resource bundles added before initialization.
- */
-interface ResourceBundle {
-    lng: string;
-    ns: string;
-    resources: object;
-}
-
-/**
- * Internal array to maintain resource bundles added before initialization.
- */
-let pendingResourceBundles: ResourceBundle[] | undefined = [];
-
 /**
  * Internationalization operating environment.
  */
@@ -38,91 +22,6 @@ export enum I18NEnvironment {
     Browser
 }
 
-/**
- * Initialize internationalization.
- *
- * @param environment
- * Environment in which the application is running.
- *
- * @param debug
- * Debug setting.
- *
- * @returns
- * True if initialization was completed, false if skipped (already initialized).
- */
-export async function i18nInit(environment: I18NEnvironment, debug = false): Promise<boolean> {
-    let initialized: boolean;
-
-    // Skip if initialization is not pending.
-    if (pendingResourceBundles !== undefined) {
-        initialized = true;
-        
-        let module: Parameters<typeof i18next.use>[0];
-
-        switch (environment) {
-            case I18NEnvironment.CLI:
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Pending resolution of https://github.com/neet/i18next-cli-language-detector/issues/281.
-                module = I18nextCLILanguageDetector as unknown as LanguageDetectorModule;
-                break;
-
-            case I18NEnvironment.Browser:
-                module = I18nextBrowserLanguageDetector;
-                break;
-
-            default:
-                throw new Error("Not supported");
-        }
-
-        const initResourceBundles = pendingResourceBundles;
-
-        // No need to manage pending resource bundles past this point.
-        pendingResourceBundles = undefined;
-
-        await i18next.use(module).init({
-            fallbackLng: "en",
-            debug,
-            resources: {}
-        }).then(() => {
-            // Add toLowerCase function.
-            i18next.services.formatter?.add("toLowerCase", value => typeof value === "string" ? value.toLowerCase() : String(value));
-
-            // Add pending resource bundles.
-            for (const initResourceBundle of initResourceBundles) {
-                i18nAddResourceBundle(initResourceBundle.lng, initResourceBundle.ns, initResourceBundle.resources);
-            }
-        });
-    } else {
-        initialized = false;
-    }
-
-    return initialized;
-}
-
-/**
- * Add a resource bundle.
- *
- * @param lng
- * Language.
- *
- * @param ns
- * Namespace.
- *
- * @param resources
- * Resources.
- */
-export function i18nAddResourceBundle(lng: string, ns: string, resources: object): void {
-    if (pendingResourceBundles !== undefined) {
-        pendingResourceBundles.push({
-            lng,
-            ns,
-            resources
-        });
-    } else {
-        // Already initialized; add resource bundle directly.
-        i18next.addResourceBundle(lng, ns, resources);
-    }
-}
-
 /**
  * Assert that language resources are a type match for English (default) resources.
  *
@@ -158,7 +57,7 @@ export function i18nAssertValidResources(enResources: object, lng: string, lngRe
             if (enValueType === "object") {
                 i18nAssertValidResources(enValue, lng, lngValue, `${parent === undefined ? "" : `${parent}.`}${enKey}`);
             }
-        // Locale falls back to raw language so ignore if missing.
+            // Locale falls back to raw language so ignore if missing.
         } else if (!isLocale) {
             throw new Error(`Missing key ${parent === undefined ? "" : `${parent}.`}${enKey} from ${lng} resources`);
         }
@@ -170,3 +69,90 @@ export function i18nAssertValidResources(enResources: object, lng: string, lngRe
         }
     }
 }
+
+/**
+ * Convert a string to lower case, skipping words that are all upper case.
+ *
+ * @param s
+ * String.
+ *
+ * @returns
+ * Lower case string.
+ */
+function toLowerCase(s: string): string {
+    // Words with no lower case letters are preserved as they are likely mnemonics.
+    return s.split(" ").map(word => /[a-z]/.test(word) ? word.toLowerCase() : word).join(" ");
+}
+
+/**
+ * Initialize internationalization.
+ *
+ * @param i18next
+ * Internationalization object. As multiple objects exists, this parameter represents the one for the module for which
+ * internationalization is being initialized.
+ *
+ * @param environment
+ * Environment in which the application is running.
+ *
+ * @param debug
+ * Debug setting.
+ *
+ * @param defaultNS
+ * Default namespace.
+ *
+ * @param resources
+ * Resources.
+ *
+ * @returns
+ * Void promise.
+ */
+export async function i18nCoreInit(i18next: i18n, environment: I18NEnvironment, debug: boolean, defaultNS: string, ...resources: Resource[]): Promise<void> {
+    // Initialization may be called more than once.
+    if (!i18next.isInitialized) {
+        const mergedResource: Resource = {};
+
+        // Merge resources.
+        for (const resource of resources) {
+            // Merge languages.
+            for (const [language, resourceLanguage] of Object.entries(resource)) {
+                if (!(language in mergedResource)) {
+                    mergedResource[language] = {};
+                }
+
+                const mergedResourceLanguage = mergedResource[language];
+
+                // Merge namespaces.
+                for (const [namespace, resourceKey] of Object.entries(resourceLanguage)) {
+                    mergedResourceLanguage[namespace] = resourceKey;
+                }
+            }
+        }
+
+        let module: Parameters<typeof i18next.use>[0];
+
+        switch (environment) {
+            case I18NEnvironment.CLI:
+                // TODO Refactor when https://github.com/neet/i18next-cli-language-detector/issues/281 resolved.
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Per above.
+                module = I18nextCLILanguageDetector as unknown as LanguageDetectorModule;
+                break;
+
+            case I18NEnvironment.Browser:
+                module = I18nextBrowserLanguageDetector;
+                break;
+
+            default:
+                throw new Error("Not supported");
+        }
+
+        await i18next.use(module).init({
+            debug,
+            resources: mergedResource,
+            fallbackLng: "en",
+            defaultNS
+        }).then(() => {
+            // Add toLowerCase function.
+            i18next.services.formatter?.add("toLowerCase", value => typeof value === "string" ? toLowerCase(value) : String(value));
+        });
+    }
+}