@modern-js/plugin-i18n 2.69.7 → 3.0.0-alpha.1

package/dist/esm-node/runtime/i18n/detection/index.js

@@ -0,0 +1,260 @@
+import { isBrowser } from "@modern-js/runtime";
+import { detectLanguageFromPath } from "../../utils.js";
+import { isI18nWrapperInstance } from "../instance.js";
+import { mergeDetectionOptions } from "./config.js";
+import { cacheUserLanguage, detectLanguage, readLanguageFromStorage, useI18nextLanguageDetector } from "./middleware.js";
+const detectorInstanceCache = new WeakMap();
+const DETECTOR_SAFE_OPTION_KEYS = [
+    'lowerCaseLng',
+    'nonExplicitSupportedLngs',
+    'load',
+    'partialBundledLanguages',
+    'returnNull',
+    'returnEmptyString',
+    'returnObjects',
+    'joinArrays',
+    'keySeparator',
+    'nsSeparator',
+    'pluralSeparator',
+    'contextSeparator',
+    'fallbackNS',
+    'ns',
+    'defaultNS',
+    'debug'
+];
+const stableStringify = (value)=>{
+    if (null == value) return JSON.stringify(value);
+    if ('object' != typeof value) return JSON.stringify(value);
+    if (Array.isArray(value)) return `[${value.map((item)=>stableStringify(item)).join(',')}]`;
+    const sortedKeys = Object.keys(value).sort();
+    const sortedEntries = sortedKeys.map((key)=>{
+        const stringifiedValue = stableStringify(value[key]);
+        return `${JSON.stringify(key)}:${stringifiedValue}`;
+    });
+    return `{${sortedEntries.join(',')}}`;
+};
+const buildDetectorConfigKey = (languages, fallbackLanguage, mergedDetection)=>stableStringify({
+        languages,
+        fallbackLanguage,
+        detection: mergedDetection
+    });
+const pickSafeDetectionOptions = (userInitOptions)=>{
+    if (!userInitOptions) return {};
+    const safeOptions = {};
+    for (const key of DETECTOR_SAFE_OPTION_KEYS){
+        const value = userInitOptions[key];
+        if (void 0 !== value) safeOptions[key] = value;
+    }
+    if (userInitOptions.interpolation) safeOptions.interpolation = {
+        ...userInitOptions.interpolation
+    };
+    return safeOptions;
+};
+const cleanupDetectorCacheEntry = (entry)=>{
+    if (!entry || !entry.isTemporary) return;
+    const instance = entry.instance;
+    try {
+        instance?.removeAllListeners?.();
+    } catch (error) {}
+    try {
+        instance?.off?.('*');
+    } catch (error) {}
+    try {
+        instance?.services?.backendConnector?.backend?.stop?.();
+    } catch (error) {}
+    try {
+        instance?.services?.backendConnector?.backend?.close?.();
+    } catch (error) {}
+};
+function exportServerLngToWindow(context, lng) {
+    context.__i18nData__ = {
+        lng
+    };
+}
+const getLanguageFromSSRData = (window1)=>{
+    try {
+        const ssrData = window1._SSR_DATA;
+        if (!ssrData || !ssrData.data || !ssrData.data.i18nData) return;
+        const lng = ssrData.data.i18nData.lng;
+        return 'string' == typeof lng && '' !== lng.trim() ? lng : void 0;
+    } catch (error) {
+        return;
+    }
+};
+const normalizeLanguageCode = (language)=>{
+    if (!language) return language;
+    const baseLang = language.split('-')[0];
+    return baseLang;
+};
+const isLanguageSupported = (language, supportedLanguages)=>{
+    if (!language) return false;
+    if (0 === supportedLanguages.length) return true;
+    if (supportedLanguages.includes(language)) return true;
+    const baseLang = normalizeLanguageCode(language);
+    if (baseLang !== language && supportedLanguages.includes(baseLang)) return true;
+    return false;
+};
+const getSupportedLanguage = (language, supportedLanguages)=>{
+    if (!language) return;
+    if (0 === supportedLanguages.length) return language;
+    if (supportedLanguages.includes(language)) return language;
+    const baseLang = normalizeLanguageCode(language);
+    if (baseLang !== language && supportedLanguages.includes(baseLang)) return baseLang;
+};
+const detectLanguageFromSSR = (languages)=>{
+    if (!isBrowser()) return;
+    try {
+        const ssrLanguage = getLanguageFromSSRData(window);
+        if (ssrLanguage && isLanguageSupported(ssrLanguage, languages)) return ssrLanguage;
+    } catch (error) {}
+};
+const detectLanguageFromPathPriority = (pathname, languages, localePathRedirect)=>{
+    if (!localePathRedirect) return;
+    if (!languages || 0 === languages.length) return;
+    if (!pathname || '' === pathname.trim()) return;
+    try {
+        const pathDetection = detectLanguageFromPath(pathname, languages, localePathRedirect);
+        if (true === pathDetection.detected && pathDetection.language) return pathDetection.language;
+    } catch (error) {}
+};
+const createDetectorInstance = (baseInstance, configKey)=>{
+    const cached = detectorInstanceCache.get(baseInstance);
+    if (cached && cached.configKey === configKey) return {
+        instance: cached.instance,
+        isTemporary: cached.isTemporary
+    };
+    if (cached) {
+        cleanupDetectorCacheEntry(cached);
+        detectorInstanceCache.delete(baseInstance);
+    }
+    const createNewInstance = ()=>{
+        if ('function' == typeof baseInstance.createInstance) try {
+            const created = baseInstance.createInstance();
+            if (created) return {
+                instance: created,
+                isTemporary: true
+            };
+        } catch (error) {}
+        if ('function' == typeof baseInstance.cloneInstance) try {
+            const cloned = baseInstance.cloneInstance();
+            if (cloned) return {
+                instance: cloned,
+                isTemporary: true
+            };
+        } catch (error) {}
+        return {
+            instance: baseInstance,
+            isTemporary: false
+        };
+    };
+    const created = createNewInstance();
+    if (created.isTemporary) detectorInstanceCache.set(baseInstance, {
+        instance: created.instance,
+        isTemporary: true,
+        configKey
+    });
+    return created;
+};
+const initializeI18nForDetector = async (i18nInstance, options)=>{
+    const mergedDetection = detection_mergeDetectionOptions(options.i18nextDetector, options.detection, options.localePathRedirect, options.userInitOptions);
+    const configKey = buildDetectorConfigKey(options.languages, options.fallbackLanguage, mergedDetection);
+    const { instance, isTemporary } = createDetectorInstance(i18nInstance, configKey);
+    const safeUserOptions = pickSafeDetectionOptions(options.userInitOptions);
+    const initOptions = {
+        ...safeUserOptions,
+        fallbackLng: options.fallbackLanguage,
+        supportedLngs: options.languages,
+        detection: mergedDetection,
+        initImmediate: true,
+        interpolation: {
+            ...safeUserOptions?.interpolation || {},
+            escapeValue: safeUserOptions?.interpolation?.escapeValue ?? false
+        },
+        react: {
+            useSuspense: false
+        }
+    };
+    useI18nextLanguageDetector(instance);
+    if (instance.isInitialized) {
+        if (isTemporary) await instance.init(initOptions);
+    } else await instance.init(initOptions);
+    return {
+        detectorInstance: instance,
+        isTemporary
+    };
+};
+const detectLanguageFromI18nextDetector = async (i18nInstance, options)=>{
+    if (!options.i18nextDetector) return;
+    const mergedDetection = detection_mergeDetectionOptions(options.i18nextDetector, options.detection, options.localePathRedirect, options.userInitOptions);
+    const { detectorInstance, isTemporary } = await initializeI18nForDetector(i18nInstance, options);
+    try {
+        const request = options.ssrContext?.request;
+        if (!isBrowser() && !request) return;
+        const detectorLang = detectLanguage(detectorInstance, request, mergedDetection);
+        if (detectorLang) {
+            const supportedLang = getSupportedLanguage(detectorLang, options.languages);
+            if (supportedLang) return supportedLang;
+        }
+        if (detectorInstance.isInitialized && detectorInstance.language) {
+            const currentLang = detectorInstance.language;
+            if (isLanguageSupported(currentLang, options.languages)) return currentLang;
+        }
+    } catch (error) {} finally{
+        if (isTemporary && detectorInstance !== i18nInstance) detectorInstanceCache.set(i18nInstance, {
+            instance: detectorInstance,
+            isTemporary: true,
+            configKey: buildDetectorConfigKey(options.languages, options.fallbackLanguage, mergedDetection)
+        });
+        else if (detectorInstance === i18nInstance) {
+            i18nInstance.isInitialized = false;
+            delete i18nInstance.language;
+        }
+    }
+};
+const detectLanguageWithPriority = async (i18nInstance, options)=>{
+    const { languages, fallbackLanguage, localePathRedirect, i18nextDetector, detection, userInitOptions, pathname, ssrContext } = options;
+    let detectedLanguage;
+    detectedLanguage = detectLanguageFromSSR(languages);
+    if (!detectedLanguage) detectedLanguage = detectLanguageFromPathPriority(pathname, languages, localePathRedirect);
+    if (!detectedLanguage && i18nextDetector) detectedLanguage = isI18nWrapperInstance(i18nInstance) ? readLanguageFromStorage(detection_mergeDetectionOptions(i18nextDetector, detection, localePathRedirect, userInitOptions)) : await detectLanguageFromI18nextDetector(i18nInstance, {
+        languages,
+        fallbackLanguage,
+        localePathRedirect,
+        i18nextDetector,
+        detection,
+        userInitOptions,
+        mergedBackend: options.mergedBackend,
+        ssrContext
+    });
+    const finalLanguage = detectedLanguage || userInitOptions?.lng || fallbackLanguage;
+    return {
+        detectedLanguage,
+        finalLanguage
+    };
+};
+const buildInitOptions = (params)=>{
+    const { finalLanguage, fallbackLanguage, languages, userInitOptions, mergedDetection, mergeBackend } = params;
+    return {
+        ...userInitOptions || {},
+        lng: finalLanguage,
+        fallbackLng: fallbackLanguage,
+        supportedLngs: languages,
+        detection: mergedDetection,
+        backend: mergeBackend,
+        interpolation: {
+            ...userInitOptions?.interpolation || {},
+            escapeValue: userInitOptions?.interpolation?.escapeValue ?? false
+        },
+        react: {
+            useSuspense: isBrowser()
+        }
+    };
+};
+const detection_mergeDetectionOptions = (i18nextDetector, detection, localePathRedirect, userInitOptions)=>{
+    let mergedDetection;
+    mergedDetection = i18nextDetector ? mergeDetectionOptions(detection, userInitOptions?.detection) : userInitOptions?.detection || {};
+    if (!mergedDetection || 'object' != typeof mergedDetection) mergedDetection = {};
+    if (localePathRedirect && mergedDetection.order) mergedDetection.order = mergedDetection.order.filter((item)=>'path' !== item);
+    return mergedDetection;
+};
+export { buildInitOptions, cacheUserLanguage, detectLanguageWithPriority, exportServerLngToWindow, getLanguageFromSSRData, detection_mergeDetectionOptions as mergeDetectionOptions };

package/dist/esm-node/runtime/i18n/detection/middleware.js

@@ -0,0 +1,132 @@
+import { isBrowser } from "@modern-js/runtime";
+import i18next_browser_languagedetector from "i18next-browser-languagedetector";
+import { getActualI18nextInstance, isI18nWrapperInstance } from "../instance.js";
+const useI18nextLanguageDetector = (i18nInstance)=>{
+    if (!i18nInstance.isInitialized) {
+        if (isI18nWrapperInstance(i18nInstance)) {
+            const actualInstance = getActualI18nextInstance(i18nInstance);
+            if (actualInstance && !actualInstance.isInitialized) actualInstance.use(i18next_browser_languagedetector);
+        }
+        return i18nInstance.use(i18next_browser_languagedetector);
+    }
+    return i18nInstance;
+};
+const readLanguageFromStorage = (detectionOptions)=>{
+    try {
+        const options = detectionOptions || {};
+        const order = options.order || [
+            'querystring',
+            'cookie',
+            'localStorage',
+            'navigator',
+            'htmlTag',
+            'path',
+            'subdomain'
+        ];
+        for (const method of order)switch(method){
+            case 'querystring':
+                {
+                    const lookupKey = options.lookupQuerystring || 'lng';
+                    const urlParams = new URLSearchParams(window.location.search);
+                    const lang = urlParams.get(lookupKey);
+                    if (lang) return lang;
+                    break;
+                }
+            case 'cookie':
+                {
+                    const lookupKey = options.lookupCookie || 'i18next';
+                    const cookies = document.cookie.split(';').reduce((acc, item)=>{
+                        const [key, value] = item.trim().split('=');
+                        if (key && value) acc[key] = decodeURIComponent(value);
+                        return acc;
+                    }, {});
+                    if (cookies[lookupKey]) return cookies[lookupKey];
+                    break;
+                }
+            case 'localStorage':
+                {
+                    const lookupKey = options.lookupLocalStorage || 'i18nextLng';
+                    const keysToCheck = [
+                        lookupKey
+                    ];
+                    if ('i18nextLng' === lookupKey) keysToCheck.push('i18next');
+                    for (const key of keysToCheck){
+                        const stored = localStorage.getItem(key);
+                        if (stored) return stored;
+                    }
+                    break;
+                }
+            case 'navigator':
+                if (navigator.language) return navigator.language.split('-')[0];
+                break;
+            case 'htmlTag':
+                {
+                    const htmlLang = document.documentElement.lang;
+                    if (htmlLang) return htmlLang.split('-')[0];
+                    break;
+                }
+        }
+    } catch (error) {}
+};
+const detectLanguage = (i18nInstance, _request, detectionOptions)=>{
+    try {
+        const actualInstance = isI18nWrapperInstance(i18nInstance) ? getActualI18nextInstance(i18nInstance) : i18nInstance;
+        const isInitialized = i18nInstance.isInitialized || actualInstance?.isInitialized;
+        const detector = actualInstance?.services?.languageDetector || i18nInstance.services?.languageDetector;
+        if (detector && 'function' == typeof detector.detect) {
+            const result = detector.detect();
+            if ('string' == typeof result) return result;
+            if (Array.isArray(result) && result.length > 0) return result[0];
+        }
+        if (isBrowser()) {
+            const directRead = readLanguageFromStorage(detectionOptions);
+            if (directRead) return directRead;
+        }
+        if (isInitialized) {
+            const servicesToUse = actualInstance?.services || i18nInstance.services;
+            const optionsToUse = actualInstance?.options || i18nInstance.options;
+            if (servicesToUse && optionsToUse) {
+                const manualDetector = new i18next_browser_languagedetector();
+                const mergedOptions = detectionOptions ? {
+                    ...optionsToUse,
+                    detection: detectionOptions
+                } : optionsToUse;
+                manualDetector.init(servicesToUse, mergedOptions);
+                const result = manualDetector.detect();
+                if ('string' == typeof result) return result;
+                if (Array.isArray(result) && result.length > 0) return result[0];
+            }
+        }
+    } catch (error) {}
+};
+const cacheUserLanguage = (i18nInstance, language, detectionOptions)=>{
+    if ("u" < typeof window) return;
+    try {
+        const actualInstance = isI18nWrapperInstance(i18nInstance) ? getActualI18nextInstance(i18nInstance) : i18nInstance;
+        const detector = actualInstance?.services?.languageDetector || i18nInstance.services?.languageDetector;
+        if (detector && 'function' == typeof detector.cacheUserLanguage) try {
+            detector.cacheUserLanguage(language);
+            return;
+        } catch (error) {
+            if ('development' === process.env.NODE_ENV) console.warn('[i18n] Failed to cache via detector, falling back to manual cache:', error);
+        }
+        const isInitialized = i18nInstance.isInitialized || actualInstance?.isInitialized;
+        const servicesToUse = actualInstance?.services || i18nInstance.services;
+        const optionsToUse = actualInstance?.options || i18nInstance.options;
+        if (isInitialized && servicesToUse && optionsToUse) try {
+            const userOptions = detectionOptions || optionsToUse?.detection;
+            const mergedOptions = userOptions ? {
+                ...optionsToUse,
+                detection: userOptions
+            } : optionsToUse;
+            const manualDetector = new i18next_browser_languagedetector();
+            manualDetector.init(servicesToUse, mergedOptions);
+            if ('function' == typeof manualDetector.cacheUserLanguage) return void manualDetector.cacheUserLanguage(language);
+        } catch (error) {
+            if ('development' === process.env.NODE_ENV) console.warn('[i18n] Failed to create manual detector:', error);
+        }
+    } catch (error) {
+        if ('development' === process.env.NODE_ENV) console.error('Failed to cache user language:', error);
+    }
+};
+export { cacheUserLanguage, detectLanguage, readLanguageFromStorage, useI18nextLanguageDetector };

package/dist/esm-node/runtime/i18n/detection/middleware.node.js

@@ -0,0 +1,31 @@
+import { LanguageDetector } from "i18next-http-middleware";
+const cacheUserLanguage = (_i18nInstance, _language, _detectionOptions)=>{};
+const readLanguageFromStorage = (_detectionOptions)=>{};
+const useI18nextLanguageDetector = (i18nInstance)=>{
+    if (!i18nInstance.isInitialized) return i18nInstance.use(LanguageDetector);
+    return i18nInstance;
+};
+const detectLanguage = (i18nInstance, request, detectionOptions)=>{
+    if (!request) return;
+    try {
+        const detector = i18nInstance.services?.languageDetector;
+        if (detector && 'function' == typeof detector.detect) {
+            const result = detector.detect(request, {});
+            if ('string' == typeof result) return result;
+            if (Array.isArray(result) && result.length > 0) return result[0];
+            return;
+        }
+        if (i18nInstance.isInitialized && i18nInstance.services && i18nInstance.options) {
+            const manualDetector = new LanguageDetector();
+            const optionsToUse = detectionOptions ? {
+                ...i18nInstance.options,
+                detection: detectionOptions
+            } : i18nInstance.options;
+            manualDetector.init(i18nInstance.services, optionsToUse);
+            const result = manualDetector.detect(request, {}, void 0);
+            if ('string' == typeof result) return result;
+            if (Array.isArray(result) && result.length > 0) return result[0];
+        }
+    } catch (error) {}
+};
+export { cacheUserLanguage, detectLanguage, readLanguageFromStorage, useI18nextLanguageDetector };

package/dist/esm-node/runtime/i18n/index.js

@@ -0,0 +1,3 @@
+import { getI18nInstance, isI18nInstance } from "./instance.js";
+import { assertI18nInstance } from "./utils.js";
+export { assertI18nInstance, getI18nInstance, isI18nInstance };

package/dist/esm-node/runtime/i18n/instance.js

@@ -0,0 +1,77 @@
+function isI18nWrapperInstance(obj) {
+    if (!obj || 'object' != typeof obj) return false;
+    if (!obj.i18nInstance || 'object' != typeof obj.i18nInstance) return false;
+    if (!obj.i18nInstance.instance) return false;
+    if ('function' != typeof obj.init || 'function' != typeof obj.use) return false;
+    return true;
+}
+function getI18nWrapperI18nextInstance(wrapperInstance) {
+    if (isI18nWrapperInstance(wrapperInstance)) return wrapperInstance.i18nInstance?.instance;
+    return null;
+}
+function getActualI18nextInstance(instance) {
+    if (isI18nWrapperInstance(instance)) {
+        const i18nextInstance = getI18nWrapperI18nextInstance(instance);
+        return i18nextInstance || instance;
+    }
+    return instance;
+}
+function isI18nInstance(obj) {
+    if (!obj || 'object' != typeof obj) return false;
+    if (isI18nWrapperInstance(obj)) return true;
+    return 'function' == typeof obj.init && 'function' == typeof obj.use;
+}
+async function tryImportI18next() {
+    try {
+        const i18next = await import("i18next");
+        return i18next.default;
+    } catch (error) {
+        return null;
+    }
+}
+async function createI18nextInstance() {
+    try {
+        const i18next = await tryImportI18next();
+        if (!i18next) return null;
+        return i18next.createInstance({
+            initImmediate: false
+        });
+    } catch (error) {
+        return null;
+    }
+}
+async function tryImportReactI18next() {
+    try {
+        const reactI18next = await import("react-i18next");
+        return reactI18next;
+    } catch (error) {
+        return null;
+    }
+}
+function getI18nextInstanceForProvider(instance) {
+    if (isI18nWrapperInstance(instance)) {
+        const i18nextInstance = getI18nWrapperI18nextInstance(instance);
+        if (i18nextInstance) return i18nextInstance;
+    }
+    return instance;
+}
+async function getI18nInstance(userInstance) {
+    if (userInstance) {
+        if (isI18nWrapperInstance(userInstance)) return userInstance;
+        if (isI18nInstance(userInstance)) return userInstance;
+    }
+    const i18nextInstance = await createI18nextInstance();
+    if (i18nextInstance) return i18nextInstance;
+    throw new Error('No i18n instance found');
+}
+async function getInitReactI18next() {
+    const reactI18nextModule = await tryImportReactI18next();
+    if (reactI18nextModule) return reactI18nextModule.initReactI18next;
+    return null;
+}
+async function getI18nextProvider() {
+    const reactI18nextModule = await tryImportReactI18next();
+    if (reactI18nextModule) return reactI18nextModule.I18nextProvider;
+    return null;
+}
+export { getActualI18nextInstance, getI18nInstance, getI18nWrapperI18nextInstance, getI18nextInstanceForProvider, getI18nextProvider, getInitReactI18next, isI18nInstance, isI18nWrapperInstance };

package/dist/esm-node/runtime/i18n/utils.js

@@ -0,0 +1,136 @@
+import { isBrowser } from "@modern-js/runtime";
+import { mergeBackendOptions } from "./backend/index.js";
+import { HttpBackendWithSave, useI18nextBackend } from "./backend/middleware.js";
+import { SdkBackend } from "./backend/sdk-backend.js";
+import { cacheUserLanguage, mergeDetectionOptions } from "./detection/index.js";
+import { getActualI18nextInstance, isI18nInstance, isI18nWrapperInstance } from "./instance.js";
+function assertI18nInstance(obj) {
+    if (!isI18nInstance(obj)) throw new Error('Object does not implement I18nInstance interface');
+}
+const buildInitOptions = async (finalLanguage, fallbackLanguage, languages, mergedDetection, mergedBackend, userInitOptions, useSuspense, i18nInstance)=>{
+    const defaultUseSuspense = void 0 !== useSuspense ? useSuspense : isBrowser() ? userInitOptions?.react?.useSuspense ?? true : false;
+    const isChainedBackend = !!mergedBackend?._useChainedBackend;
+    const sanitizedUserInitOptions = userInitOptions ? {
+        ...userInitOptions,
+        backend: void 0
+    } : void 0;
+    const { backend: _removedBackend, ...userOptionsWithoutBackend } = sanitizedUserInitOptions || {};
+    const initOptions = {
+        lng: finalLanguage,
+        fallbackLng: fallbackLanguage,
+        supportedLngs: languages,
+        detection: mergedDetection,
+        initImmediate: sanitizedUserInitOptions?.initImmediate ?? true,
+        interpolation: {
+            ...sanitizedUserInitOptions?.interpolation || {},
+            escapeValue: sanitizedUserInitOptions?.interpolation?.escapeValue ?? false
+        },
+        react: {
+            ...sanitizedUserInitOptions?.react || {},
+            useSuspense: defaultUseSuspense
+        },
+        ...userOptionsWithoutBackend
+    };
+    if (mergedBackend) if (isChainedBackend && mergedBackend._chainedBackendConfig) {
+        let HttpBackend;
+        let SdkBackendClass;
+        if (i18nInstance?.options?.backend?.backends && Array.isArray(i18nInstance.options.backend.backends) && i18nInstance.options.backend.backends.length >= 2) {
+            HttpBackend = i18nInstance.options.backend.backends[0];
+            SdkBackendClass = i18nInstance.options.backend.backends[1];
+        } else {
+            HttpBackend = HttpBackendWithSave;
+            SdkBackendClass = SdkBackend;
+        }
+        initOptions.backend = {
+            backends: [
+                HttpBackend,
+                SdkBackendClass
+            ],
+            backendOptions: mergedBackend._chainedBackendConfig.backendOptions,
+            cacheHitMode: mergedBackend.cacheHitMode || 'refreshAndUpdateStore'
+        };
+    } else {
+        const { _useChainedBackend, _chainedBackendConfig, ...cleanBackend } = mergedBackend || {};
+        initOptions.backend = cleanBackend;
+    }
+    return initOptions;
+};
+const ensureLanguageMatch = async (i18nInstance, finalLanguage)=>{
+    if (i18nInstance.language !== finalLanguage) {
+        await i18nInstance.setLang?.(finalLanguage);
+        await i18nInstance.changeLanguage?.(finalLanguage);
+    }
+};
+const changeI18nLanguage = async (i18nInstance, newLang, options)=>{
+    if (!newLang || 'string' != typeof newLang) throw new Error('Language must be a non-empty string');
+    if (!i18nInstance) throw new Error('i18nInstance is required');
+    await i18nInstance.setLang?.(newLang);
+    await i18nInstance.changeLanguage?.(newLang);
+    if (isBrowser()) {
+        const detectionOptions = options?.detectionOptions || i18nInstance.options?.detection;
+        cacheUserLanguage(i18nInstance, newLang, detectionOptions);
+    }
+};
+const initializeI18nInstance = async (i18nInstance, finalLanguage, fallbackLanguage, languages, mergedDetection, mergedBackend, userInitOptions, useSuspense)=>{
+    if (!i18nInstance.isInitialized) {
+        const initOptions = await buildInitOptions(finalLanguage, fallbackLanguage, languages, mergedDetection, mergedBackend, userInitOptions, useSuspense, i18nInstance);
+        const actualInstance = getActualI18nextInstance(i18nInstance);
+        const savedBackendConfig = actualInstance?.options?.backend || i18nInstance.options?.backend;
+        const isChainedBackendFromSaved = savedBackendConfig?.backends && Array.isArray(savedBackendConfig.backends);
+        await i18nInstance.init(initOptions);
+        if (mergedBackend) {
+            if (isI18nWrapperInstance(i18nInstance) && actualInstance?.options) {
+                if (isChainedBackendFromSaved && initOptions.backend) actualInstance.options.backend = {
+                    ...initOptions.backend,
+                    backends: savedBackendConfig.backends
+                };
+                else if (initOptions.backend) actualInstance.options.backend = {
+                    ...actualInstance.options.backend,
+                    ...initOptions.backend
+                };
+            }
+            if (hasOptions(i18nInstance)) {
+                if (isChainedBackendFromSaved && initOptions.backend) i18nInstance.options.backend = {
+                    ...initOptions.backend,
+                    backends: savedBackendConfig.backends
+                };
+                else if (initOptions.backend) i18nInstance.options.backend = {
+                    ...i18nInstance.options.backend,
+                    ...initOptions.backend
+                };
+            }
+        }
+        if (mergedBackend && hasOptions(i18nInstance)) {
+            const defaultNS = initOptions.defaultNS || initOptions.ns || 'translation';
+            const ns = Array.isArray(defaultNS) ? defaultNS[0] : defaultNS;
+            let retries = 20;
+            while(retries > 0){
+                const actualInstance = getActualI18nextInstance(i18nInstance);
+                const store = actualInstance.store;
+                if (store?.data?.[finalLanguage]?.[ns]) break;
+                await new Promise((resolve)=>setTimeout(resolve, 100));
+                retries--;
+            }
+        }
+    }
+};
+function hasOptions(instance) {
+    return void 0 !== instance.options && null !== instance.options;
+}
+const setupClonedInstance = async (i18nInstance, finalLanguage, fallbackLanguage, languages, backendEnabled, backend, i18nextDetector, detection, localePathRedirect, userInitOptions)=>{
+    const mergedBackend = mergeBackendOptions(backend, userInitOptions);
+    const hasSdkConfig = 'function' == typeof userInitOptions?.backend?.sdk || mergedBackend?.sdk && 'function' == typeof mergedBackend.sdk;
+    if (backendEnabled || hasSdkConfig) {
+        useI18nextBackend(i18nInstance, mergedBackend);
+        if (mergedBackend && hasOptions(i18nInstance)) i18nInstance.options.backend = {
+            ...i18nInstance.options.backend,
+            ...mergedBackend
+        };
+        if (i18nInstance.isInitialized) await ensureLanguageMatch(i18nInstance, finalLanguage);
+        else {
+            const mergedDetection = mergeDetectionOptions(i18nextDetector, detection, localePathRedirect, userInitOptions);
+            await initializeI18nInstance(i18nInstance, finalLanguage, fallbackLanguage, languages, mergedDetection, mergedBackend, userInitOptions, false);
+        }
+    } else await ensureLanguageMatch(i18nInstance, finalLanguage);
+};
+export { assertI18nInstance, buildInitOptions, changeI18nLanguage, ensureLanguageMatch, initializeI18nInstance, setupClonedInstance };