@modern-js/plugin-i18n 2.69.5 → 3.0.0-alpha.0

package/src/runtime/i18n/backend/index.ts

@@ -0,0 +1,181 @@
+import type {
+  BaseBackendOptions,
+  ChainedBackendConfig,
+} from '../../../shared/type';
+import type { BackendOptions, I18nInitOptions } from '../instance';
+import { mergeBackendOptions as baseMergeBackendOptions } from './config';
+import {
+  DEFAULT_I18NEXT_BACKEND_OPTIONS,
+  convertBackendOptions,
+} from './defaults';
+
+function hasSdkFunction(
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): boolean {
+  return (
+    typeof userInitOptions?.backend?.sdk === 'function' ||
+    (!!backend?.enabled && !!backend?.sdk && typeof backend.sdk === 'function')
+  );
+}
+
+/**
+ * Checks if loadPath is configured.
+ * If backend.enabled is true and user didn't explicitly configure loadPath,
+ * we will use default loadPath, so consider it as having loadPath.
+ */
+function hasLoadPath(
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): { hasPath: boolean; isExplicit: boolean } {
+  const userLoadPath = userInitOptions?.backend?.loadPath ?? backend?.loadPath;
+  const isExplicit: boolean = !!userLoadPath && userLoadPath !== '';
+  const hasPath =
+    isExplicit || (!!backend?.enabled && userLoadPath === undefined);
+
+  return { hasPath, isExplicit };
+}
+
+function ensureDefaultLoadPath(
+  merged: BackendOptions,
+  backend?: BaseBackendOptions,
+  isExplicitLoadPath = false,
+): void {
+  if (backend?.enabled && !isExplicitLoadPath && !merged.loadPath) {
+    merged.loadPath = DEFAULT_I18NEXT_BACKEND_OPTIONS.loadPath;
+    merged.addPath = DEFAULT_I18NEXT_BACKEND_OPTIONS.addPath;
+  }
+}
+
+function getFinalLoadPath(
+  mergedOptions?: BackendOptions,
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): string | undefined {
+  return (
+    mergedOptions?.loadPath ||
+    userInitOptions?.backend?.loadPath ||
+    (backend?.enabled ? DEFAULT_I18NEXT_BACKEND_OPTIONS.loadPath : undefined)
+  );
+}
+
+function getFinalSdk(
+  mergedOptions?: BackendOptions,
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): any {
+  return (
+    mergedOptions?.sdk ||
+    userInitOptions?.backend?.sdk ||
+    (backend?.sdk && typeof backend.sdk === 'function'
+      ? backend.sdk
+      : undefined)
+  );
+}
+
+function buildChainedBackendConfig(
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): ChainedBackendConfig & BaseBackendOptions {
+  const merged = baseMergeBackendOptions(
+    DEFAULT_I18NEXT_BACKEND_OPTIONS,
+    backend as BackendOptions,
+    userInitOptions?.backend,
+  );
+
+  const { isExplicit } = hasLoadPath(backend, userInitOptions);
+  ensureDefaultLoadPath(merged, backend, isExplicit);
+
+  const mergedOptions = convertBackendOptions(merged);
+  const finalLoadPath = getFinalLoadPath(
+    mergedOptions,
+    backend,
+    userInitOptions,
+  );
+  const finalSdk = getFinalSdk(mergedOptions, backend, userInitOptions);
+
+  const chainedBackendOptions = [
+    {
+      loadPath: finalLoadPath,
+      addPath:
+        mergedOptions?.addPath || DEFAULT_I18NEXT_BACKEND_OPTIONS.addPath,
+    },
+    {
+      sdk: finalSdk,
+    },
+  ];
+
+  return {
+    ...mergedOptions,
+    loadPath: finalLoadPath,
+    sdk: finalSdk,
+    cacheHitMode:
+      mergedOptions?.cacheHitMode ||
+      (backend as BackendOptions)?.cacheHitMode ||
+      userInitOptions?.backend?.cacheHitMode ||
+      'refreshAndUpdateStore',
+    _useChainedBackend: true,
+    _chainedBackendConfig: {
+      backendOptions: chainedBackendOptions,
+    },
+  };
+}
+
+function buildSdkOnlyBackendConfig(
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): BackendOptions {
+  const merged = baseMergeBackendOptions(
+    {} as BackendOptions,
+    backend as BackendOptions,
+    userInitOptions?.backend,
+  );
+  return convertBackendOptions(merged) || ({} as BackendOptions);
+}
+
+function buildHttpFsBackendConfig(
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): BackendOptions | undefined {
+  // If backend.enabled is false and no userInitOptions.backend, return undefined
+  // to avoid registering backend plugin unnecessarily
+  if (!backend?.enabled && !userInitOptions?.backend) {
+    return undefined;
+  }
+
+  const mergedBackend = backend?.enabled
+    ? baseMergeBackendOptions(
+        DEFAULT_I18NEXT_BACKEND_OPTIONS,
+        backend as BackendOptions,
+        userInitOptions?.backend,
+      )
+    : userInitOptions?.backend;
+
+  if (mergedBackend) {
+    const { isExplicit } = hasLoadPath(backend, userInitOptions);
+    ensureDefaultLoadPath(mergedBackend, backend, isExplicit);
+  }
+
+  return (
+    convertBackendOptions(mergedBackend as BackendOptions) ||
+    ({} as BackendOptions)
+  );
+}
+
+export const mergeBackendOptions = (
+  backend?: BaseBackendOptions,
+  userInitOptions?: I18nInitOptions,
+): BackendOptions | undefined => {
+  const sdkFunction = hasSdkFunction(backend, userInitOptions);
+  const { hasPath } = hasLoadPath(backend, userInitOptions);
+
+  if (hasPath && sdkFunction) {
+    return buildChainedBackendConfig(backend, userInitOptions);
+  }
+
+  if (sdkFunction) {
+    return buildSdkOnlyBackendConfig(backend, userInitOptions);
+  }
+
+  return buildHttpFsBackendConfig(backend, userInitOptions);
+};

package/src/runtime/i18n/backend/middleware.common.ts

@@ -0,0 +1,116 @@
+import ChainedBackend from 'i18next-chained-backend';
+import type {
+  BaseBackendOptions,
+  ChainedBackendConfig,
+} from '../../../shared/type';
+import type { I18nInstance } from '../instance';
+import { getActualI18nextInstance } from '../instance';
+import { SdkBackend } from './sdk-backend';
+
+type BackendConfigWithChained = BaseBackendOptions &
+  Partial<ChainedBackendConfig>;
+
+function checkBackendConfig(backend?: BackendConfigWithChained) {
+  const hasSdk = backend?.sdk && typeof backend.sdk === 'function';
+  const hasLoadPath = !!backend?.loadPath;
+  const useChained = backend?._useChainedBackend;
+
+  return { hasSdk, hasLoadPath, useChained };
+}
+
+function buildChainedBackendConfig(
+  backend: BackendConfigWithChained,
+  BackendWithSave: new (...args: any[]) => any,
+) {
+  const cacheHitMode = backend.cacheHitMode || 'refreshAndUpdateStore';
+
+  if (backend._chainedBackendConfig) {
+    return {
+      backends: [BackendWithSave, SdkBackend],
+      backendOptions: backend._chainedBackendConfig.backendOptions,
+      cacheHitMode,
+    };
+  }
+
+  // Legacy: build chained backend config from backend options
+  return {
+    backends: [BackendWithSave, SdkBackend],
+    backendOptions: [
+      {
+        loadPath: backend.loadPath,
+        addPath: backend.addPath,
+      },
+      {
+        sdk: backend.sdk,
+      },
+    ],
+    cacheHitMode,
+  };
+}
+
+function setupChainedBackend(
+  i18nInstance: I18nInstance,
+  backend: BackendConfigWithChained,
+  BackendWithSave: new (...args: any[]) => any,
+) {
+  i18nInstance.use(ChainedBackend);
+  const actualInstance = getActualI18nextInstance(i18nInstance);
+  if (actualInstance?.options) {
+    actualInstance.options.backend = buildChainedBackendConfig(
+      backend,
+      BackendWithSave,
+    );
+  }
+  if (i18nInstance.options) {
+    i18nInstance.options.backend = buildChainedBackendConfig(
+      backend,
+      BackendWithSave,
+    );
+  }
+}
+
+function cleanBackendConfig(backend: BackendConfigWithChained) {
+  const { _useChainedBackend, _chainedBackendConfig, ...cleanBackend } =
+    backend;
+  return cleanBackend;
+}
+
+/**
+ * Common logic for using i18next backend
+ * This function handles the backend selection and chained backend configuration
+ *
+ * @param i18nInstance - The i18n instance to configure
+ * @param BackendWithSave - The wrapped backend class with save method (required for chained backend refresh logic)
+ * @param BackendBase - The base backend class (for non-chained use)
+ * @param backend - Optional backend configuration
+ */
+export function useI18nextBackendCommon(
+  i18nInstance: I18nInstance,
+  BackendWithSave: new (...args: any[]) => any,
+  BackendBase: new (...args: any[]) => any,
+  backend?: BackendConfigWithChained,
+) {
+  if (!backend) {
+    return i18nInstance.use(BackendBase);
+  }
+
+  const { hasSdk, hasLoadPath, useChained } = checkBackendConfig(backend);
+
+  if (useChained || (hasLoadPath && hasSdk)) {
+    setupChainedBackend(i18nInstance, backend, BackendWithSave);
+    return;
+  }
+
+  if (hasSdk) {
+    return i18nInstance.use(SdkBackend);
+  }
+
+  const actualInstance = getActualI18nextInstance(i18nInstance);
+  if (actualInstance?.options) {
+    actualInstance.options.backend = cleanBackendConfig(backend);
+  }
+  if (i18nInstance.options) {
+    i18nInstance.options.backend = cleanBackendConfig(backend);
+  }
+  return i18nInstance.use(BackendBase);
+}

package/src/runtime/i18n/backend/middleware.node.ts

@@ -0,0 +1,32 @@
+import Backend from 'i18next-fs-backend';
+import type { ExtendedBackendOptions } from '../../../shared/type';
+import type { I18nInstance } from '../instance';
+import { useI18nextBackendCommon } from './middleware.common';
+
+/**
+ * Wrapper for FS backend to add a no-op save method
+ * This is required for i18next-chained-backend to trigger refresh logic
+ * when cacheHitMode is 'refresh' or 'refreshAndUpdateStore'
+ */
+export class FsBackendWithSave extends Backend {
+  save(_language: string, _namespace: string, _data: unknown): void {
+    // No-op: FS backend doesn't need to save in this context, but we need this method
+    // to trigger i18next-chained-backend's refresh logic
+  }
+}
+
+// Export as HttpBackendWithSave for consistency with browser version
+// This allows utils.ts to import the same name in both environments
+export const HttpBackendWithSave = FsBackendWithSave;
+
+export const useI18nextBackend = (
+  i18nInstance: I18nInstance,
+  backend?: ExtendedBackendOptions,
+) => {
+  return useI18nextBackendCommon(
+    i18nInstance,
+    FsBackendWithSave,
+    Backend,
+    backend,
+  );
+};

package/src/runtime/i18n/backend/middleware.ts

@@ -0,0 +1,28 @@
+import Backend from 'i18next-http-backend';
+import type { ExtendedBackendOptions } from '../../../shared/type';
+import type { I18nInstance } from '../instance';
+import { useI18nextBackendCommon } from './middleware.common';
+
+/**
+ * Wrapper for HTTP backend to add a no-op save method
+ * This is required for i18next-chained-backend to trigger refresh logic
+ * when cacheHitMode is 'refresh' or 'refreshAndUpdateStore'
+ */
+export class HttpBackendWithSave extends Backend {
+  save(_language: string, _namespace: string, _data: unknown): void {
+    // No-op: HTTP backend doesn't need to save, but we need this method
+    // to trigger i18next-chained-backend's refresh logic
+  }
+}
+
+export const useI18nextBackend = (
+  i18nInstance: I18nInstance,
+  backend?: ExtendedBackendOptions,
+) => {
+  return useI18nextBackendCommon(
+    i18nInstance,
+    HttpBackendWithSave,
+    Backend,
+    backend,
+  );
+};

package/src/runtime/i18n/backend/sdk-backend.ts

@@ -0,0 +1,292 @@
+import type { I18nSdkLoadOptions, I18nSdkLoader } from '../../../shared/type';
+import type { Resources } from '../instance';
+
+interface BackendOptions {
+  sdk?: I18nSdkLoader;
+  [key: string]: unknown;
+}
+
+interface I18nextServices {
+  resourceStore?: {
+    data?: {
+      [language: string]: {
+        [namespace: string]: Record<string, string>;
+      };
+    };
+  };
+  store?: {
+    data?: {
+      [language: string]: {
+        [namespace: string]: Record<string, string>;
+      };
+    };
+  };
+  [key: string]: any;
+}
+
+export class SdkBackend {
+  static type = 'backend';
+  type = 'backend' as const;
+  sdk?: I18nSdkLoader;
+  private allResourcesCache: Resources | null = null;
+  private loadingPromises = new Map<string, Promise<unknown>>();
+  private services?: I18nextServices;
+
+  constructor(_services: unknown, _options: Record<string, unknown>) {
+    void _services;
+    void _options;
+  }
+
+  init(
+    services: I18nextServices,
+    backendOptions: BackendOptions,
+    _i18nextOptions: unknown,
+  ): void {
+    this.services = services;
+    void _i18nextOptions;
+    this.sdk = backendOptions?.sdk;
+    if (!this.sdk) {
+      throw new Error(
+        'SdkBackend requires an SDK function to be provided in backend options',
+      );
+    }
+  }
+
+  read(
+    language: string,
+    namespace: string,
+    callback: (error: Error | null, data: unknown) => void,
+  ) {
+    if (!this.sdk) {
+      console.error('[i18n] SdkBackend.read - SDK function not initialized');
+      callback(new Error('SDK function not initialized'), null);
+      return;
+    }
+
+    const cached = this.allResourcesCache
+      ? this.extractFromCache(language, namespace)
+      : null;
+    if (cached !== null) {
+      // Merge cached data with existing store data to preserve HTTP backend data
+      const mergedData = this.mergeWithExistingResources(
+        language,
+        namespace,
+        cached,
+      );
+      callback(null, mergedData);
+      return;
+    }
+
+    const cacheKey = this.getCacheKey(language, namespace);
+    const existingPromise = this.loadingPromises.get(cacheKey);
+    if (existingPromise) {
+      this.handlePromise(existingPromise, language, namespace, callback, false);
+      return;
+    }
+
+    this.loadResource(language, namespace, callback);
+  }
+
+  create(
+    _languages: string[],
+    _namespace: string,
+    _key: string,
+    _fallbackValue: string,
+  ): void {
+    // Not implemented - translations are managed by the external SDK service
+  }
+
+  isLoading(language: string, namespace: string): boolean {
+    return this.loadingPromises.has(this.getCacheKey(language, namespace));
+  }
+
+  getLoadingResources(): Array<{ language: string; namespace: string }> {
+    const loading: Array<{ language: string; namespace: string }> = [];
+    for (const key of this.loadingPromises.keys()) {
+      const [language, namespace] = key.split(':');
+      if (language && namespace) {
+        loading.push({ language, namespace });
+      }
+    }
+    return loading;
+  }
+
+  hasLoadingResources(): boolean {
+    return this.loadingPromises.size > 0;
+  }
+
+  private getCacheKey(language: string, namespace: string): string {
+    return `${language}:${namespace}`;
+  }
+
+  private loadResource(
+    language: string,
+    namespace: string,
+    callback: (error: Error | null, data: unknown) => void,
+  ): void {
+    try {
+      const result = this.callSdk(language, namespace);
+      const loadPromise =
+        result instanceof Promise ? result : Promise.resolve(result);
+      const cacheKey = this.getCacheKey(language, namespace);
+
+      this.loadingPromises.set(cacheKey, loadPromise);
+
+      this.handlePromise(loadPromise, language, namespace, callback, true);
+    } catch (error) {
+      callback(this.normalizeError(error), null);
+    }
+  }
+
+  private handlePromise(
+    promise: Promise<unknown>,
+    language: string,
+    namespace: string,
+    callback: (error: Error | null, data: unknown) => void,
+    shouldUpdateCache: boolean,
+  ): void {
+    const cacheKey = this.getCacheKey(language, namespace);
+
+    promise
+      .then(data => {
+        const formattedData = this.formatResources(data, language, namespace);
+        // Merge with existing resources in store to preserve data from other backends (e.g., HTTP backend)
+        // This is important when using refreshAndUpdateStore mode in chained backend
+        const mergedData = this.mergeWithExistingResources(
+          language,
+          namespace,
+          formattedData,
+        );
+        if (shouldUpdateCache) {
+          this.updateCache(language, namespace, mergedData);
+          this.loadingPromises.delete(cacheKey);
+        }
+        callback(null, mergedData);
+        this.triggerI18nextUpdate(language, namespace);
+      })
+      .catch(error => {
+        if (shouldUpdateCache) {
+          this.loadingPromises.delete(cacheKey);
+        }
+        callback(this.normalizeError(error), null);
+      });
+  }
+
+  private normalizeError(error: unknown): Error {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+
+  private callSdk(
+    language: string,
+    namespace: string,
+  ): Promise<Resources> | Resources {
+    if (!this.sdk) {
+      throw new Error('SDK function not initialized');
+    }
+
+    const options: I18nSdkLoadOptions = { lng: language, ns: namespace };
+    return this.sdk(options);
+  }
+
+  private extractFromCache(
+    language: string,
+    namespace: string,
+  ): Record<string, string> | null {
+    if (!this.allResourcesCache) {
+      return null;
+    }
+
+    const langData = this.allResourcesCache[language];
+    if (!this.isObject(langData)) {
+      return null;
+    }
+
+    const nsData = langData[namespace];
+    if (!this.isObject(nsData)) {
+      return null;
+    }
+
+    return nsData as Record<string, string>;
+  }
+
+  private updateCache(
+    language: string,
+    namespace: string,
+    data: unknown,
+  ): void {
+    if (!this.allResourcesCache) {
+      this.allResourcesCache = {};
+    }
+
+    if (!this.allResourcesCache[language]) {
+      this.allResourcesCache[language] = {};
+    }
+
+    if (this.isObject(data)) {
+      this.allResourcesCache[language][namespace] = data as Record<
+        string,
+        string
+      >;
+    }
+  }
+
+  private formatResources(
+    data: unknown,
+    language: string,
+    namespace: string,
+  ): Record<string, string> {
+    if (!this.isObject(data)) {
+      return {};
+    }
+
+    const dataObj = data as Record<string, unknown>;
+    const langData = dataObj[language];
+
+    if (this.isObject(langData)) {
+      const nsData = (langData as Record<string, unknown>)[namespace];
+      if (this.isObject(nsData)) {
+        return nsData as Record<string, string>;
+      }
+    }
+
+    const hasLanguageKeys = Object.keys(dataObj).some(key =>
+      this.isObject(dataObj[key]),
+    );
+    if (!hasLanguageKeys) {
+      return dataObj as Record<string, string>;
+    }
+
+    return {};
+  }
+
+  private isObject(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object';
+  }
+
+  private mergeWithExistingResources(
+    language: string,
+    namespace: string,
+    sdkData: Record<string, string>,
+  ): Record<string, string> {
+    // Get existing resources from store (may contain data from HTTP backend)
+    const store = this.services?.resourceStore || this.services?.store;
+    const existingData =
+      store?.data?.[language]?.[namespace] || ({} as Record<string, string>);
+
+    // Merge: preserve existing data (from HTTP backend), add/update with SDK data
+    // This ensures that when using refreshAndUpdateStore, HTTP backend data is not lost
+    return {
+      ...existingData,
+      ...sdkData,
+    };
+  }
+
+  private triggerI18nextUpdate(language: string, namespace: string): void {
+    if (typeof window !== 'undefined') {
+      const event = new CustomEvent('i18n-sdk-resources-loaded', {
+        detail: { language, namespace },
+      });
+      window.dispatchEvent(event);
+    }
+  }
+}

package/src/runtime/i18n/detection/config.ts

@@ -0,0 +1,32 @@
+import { deepMerge } from '../../../shared/deepMerge.js';
+import type { LanguageDetectorOptions } from '../instance';
+
+export const DEFAULT_I18NEXT_DETECTION_OPTIONS = {
+  caches: ['cookie', 'localStorage'],
+  order: [
+    'querystring',
+    'cookie',
+    'localStorage',
+    'header',
+    'navigator',
+    'htmlTag',
+    'path',
+    'subdomain',
+  ],
+  cookieMinutes: 60 * 24 * 365,
+  lookupQuerystring: 'lng',
+  lookupCookie: 'i18next',
+  lookupLocalStorage: 'i18nextLng',
+  lookupHeader: 'accept-language',
+};
+
+export function mergeDetectionOptions(
+  cliOptions?: LanguageDetectorOptions,
+  userOptions?: LanguageDetectorOptions,
+  defaultOptions: LanguageDetectorOptions = DEFAULT_I18NEXT_DETECTION_OPTIONS,
+): LanguageDetectorOptions {
+  return deepMerge(
+    deepMerge(defaultOptions, cliOptions ?? {}),
+    userOptions ?? {},
+  );
+}