@bleedingdev/modern-js-plugin-i18n 3.2.0-ultramodern.0

package/src/shared/detection.ts

@@ -0,0 +1,131 @@
+import {
+  DEFAULT_I18NEXT_DETECTION_OPTIONS,
+  mergeDetectionOptions,
+} from '../runtime/i18n/detection/config.js';
+import type { LanguageDetectorOptions } from '../runtime/i18n/instance';
+
+/**
+ * Detect language from request using the same detection logic as i18next
+ * This ensures consistency between server-side and client-side detection
+ */
+export function detectLanguageFromRequest(
+  req: {
+    url: string;
+    headers:
+      | {
+          get: (name: string) => string | null;
+        }
+      | Headers;
+  },
+  languages: string[],
+  detectionOptions?: LanguageDetectorOptions,
+): string | null {
+  try {
+    // Merge user detection options with defaults
+    const mergedDetection = detectionOptions
+      ? mergeDetectionOptions(detectionOptions)
+      : DEFAULT_I18NEXT_DETECTION_OPTIONS;
+
+    // Get detection order, excluding 'path' and browser-only detectors
+    const order = (mergedDetection.order || []).filter(
+      (item: string) =>
+        !['path', 'localStorage', 'navigator', 'htmlTag', 'subdomain'].includes(
+          item,
+        ),
+    );
+
+    // If no order specified, use default server-side order
+    const detectionOrder =
+      order.length > 0 ? order : ['querystring', 'cookie', 'header'];
+
+    // Helper to get header value
+    const getHeader = (name: string): string | null => {
+      if (req.headers instanceof Headers) {
+        return req.headers.get(name);
+      }
+      return req.headers.get(name);
+    };
+
+    // Try each detection method in order
+    for (const method of detectionOrder) {
+      let detectedLang: string | null = null;
+
+      switch (method) {
+        case 'querystring': {
+          const lookupKey =
+            mergedDetection.lookupQuerystring ||
+            DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupQuerystring ||
+            'lng';
+          const host = getHeader('host') || 'localhost';
+          const url = new URL(req.url, `http://${host}`);
+          detectedLang = url.searchParams.get(lookupKey);
+          break;
+        }
+        case 'cookie': {
+          const lookupKey =
+            mergedDetection.lookupCookie ||
+            DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupCookie ||
+            'i18next';
+          const cookieHeader = getHeader('Cookie');
+          if (cookieHeader) {
+            const cookies = cookieHeader
+              .split(';')
+              .reduce((acc: Record<string, string>, item: string) => {
+                const [key, value] = item.trim().split('=');
+                if (key && value) {
+                  acc[key] = value;
+                }
+                return acc;
+              }, {});
+            detectedLang = cookies[lookupKey] || null;
+          }
+          break;
+        }
+        case 'header': {
+          const lookupKey =
+            mergedDetection.lookupHeader ||
+            DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupHeader ||
+            'accept-language';
+          const acceptLanguage = getHeader(lookupKey);
+          if (acceptLanguage) {
+            // Parse Accept-Language header: "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7"
+            const languagesList = acceptLanguage
+              .split(',')
+              .map((lang: string) => {
+                const [code, q] = lang.trim().split(';');
+                return {
+                  code: code.split('-')[0], // Extract base language code
+                  quality: q ? parseFloat(q.split('=')[1]) : 1.0,
+                };
+              })
+              .sort(
+                (a: { quality: number }, b: { quality: number }) =>
+                  b.quality - a.quality,
+              );
+
+            // Find first matching language
+            for (const lang of languagesList) {
+              if (languages.length === 0 || languages.includes(lang.code)) {
+                detectedLang = lang.code;
+                break;
+              }
+            }
+          }
+          break;
+        }
+      }
+
+      // If detected and valid, return it
+      if (
+        detectedLang &&
+        (languages.length === 0 || languages.includes(detectedLang))
+      ) {
+        return detectedLang;
+      }
+    }
+  } catch (error) {
+    // Silently ignore errors
+  }
+
+  return null;
+}

package/src/shared/type.ts

@@ -0,0 +1,170 @@
+import type {
+  LanguageDetectorOptions,
+  Resources,
+} from '../runtime/i18n/instance';
+
+export interface BaseLocaleDetectionOptions {
+  localePathRedirect?: boolean;
+  i18nextDetector?: boolean;
+  languages?: string[];
+  fallbackLanguage?: string;
+  detection?: LanguageDetectorOptions;
+  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
+}
+
+export interface LocaleDetectionOptions extends BaseLocaleDetectionOptions {
+  localeDetectionByEntry?: Record<string, BaseLocaleDetectionOptions>;
+}
+
+/**
+ * Options for loading i18n resources via SDK
+ */
+export interface I18nSdkLoadOptions {
+  /** Single language code to load (e.g., 'en', 'zh') */
+  lng?: string;
+  /** Single namespace to load (e.g., 'translation', 'common') */
+  ns?: string;
+  /** Multiple language codes to load */
+  lngs?: string[];
+  /** Multiple namespaces to load */
+  nss?: string[];
+  /** Load all available languages and namespaces */
+  all?: boolean;
+}
+
+/**
+ * SDK function to load i18n resources
+ * Supports multiple loading modes:
+ * 1. Single resource: sdk({ lng: 'en', ns: 'translation' })
+ * 2. Batch by languages: sdk({ lngs: ['en', 'zh'], ns: 'translation' })
+ * 3. Batch by namespaces: sdk({ lng: 'en', nss: ['translation', 'common'] })
+ * 4. Batch by both: sdk({ lngs: ['en', 'zh'], nss: ['translation', 'common'] })
+ * 5. Load all: sdk({ all: true }) or sdk()
+ *
+ * @param options - Loading options
+ * @returns Promise that resolves to resources object or the resources object directly
+ *          Resources format: { [lng]: { [ns]: { [key]: value } } }
+ */
+export type I18nSdkLoader = (
+  options: I18nSdkLoadOptions,
+) => Promise<Resources> | Resources;
+
+/**
+ * Chained backend configuration
+ * Used internally when both loadPath and sdk are provided
+ */
+export interface ChainedBackendConfig {
+  _useChainedBackend: boolean;
+  _chainedBackendConfig: {
+    backendOptions: Array<Record<string, unknown>>;
+  };
+  cacheHitMode?: 'none' | 'refresh' | 'refreshAndUpdateStore';
+}
+
+/**
+ * Extended backend options that may include chained backend configuration
+ */
+export type ExtendedBackendOptions = BaseBackendOptions &
+  Partial<ChainedBackendConfig>;
+
+export interface BaseBackendOptions {
+  enabled?: boolean;
+  loadPath?: string;
+  addPath?: string;
+  /**
+   * Cache hit mode for chained backend (only effective when both `loadPath` and `sdk` are provided)
+   *
+   * - `'none'` (default): If the first backend returns resources, stop and don't try the next backend
+   * - `'refresh'`: Try to refresh the cache by loading from the next backend and update the cache
+   * - `'refreshAndUpdateStore'`: Try to refresh the cache by loading from the next backend,
+   *   update the cache and also update the i18next resource store. This allows FS/HTTP resources
+   *   to be displayed first, then SDK resources will update them asynchronously.
+   *
+   * @default 'refreshAndUpdateStore' when both loadPath and sdk are provided
+   */
+  cacheHitMode?: 'none' | 'refresh' | 'refreshAndUpdateStore';
+  /**
+   * SDK function to load i18n resources dynamically
+   *
+   * **Important**: In `modern.config.ts`, you can only set this to `true` or any identifier
+   * to enable SDK mode. The actual SDK function must be provided in `modern.runtime.ts`
+   * via `initOptions.backend.sdk`.
+   *
+   * When both `loadPath` (or FS backend) and `sdk` are provided, the plugin will automatically
+   * use `i18next-chained-backend` to chain multiple backends. The order will be:
+   * 1. HTTP/FS backend (primary) - loads from `loadPath` or file system first for quick initial display
+   * 2. SDK backend (fallback/update) - loads from the SDK function to update/refresh translations
+   *
+   * With `cacheHitMode: 'refreshAndUpdateStore'` (default), FS/HTTP resources will be displayed
+   * immediately, then SDK resources will be loaded asynchronously to update the translations.
+   *
+   * If only `sdk` is provided, it will be used instead of the default HTTP/FS backend
+   *
+   * @example In modern.config.ts - enable SDK mode
+   * ```ts
+   * backend: {
+   *   enabled: true,
+   *   sdk: true, // or any identifier, just to enable SDK mode
+   * }
+   * ```
+   *
+   * @example In modern.runtime.ts - provide the actual SDK function
+   * ```ts
+   * export default defineRuntimeConfig({
+   *   i18n: {
+   *     initOptions: {
+   *       backend: {
+   *         sdk: async (options) => {
+   *           // Your SDK implementation
+   *           if (options.all) {
+   *             return await mySdk.getAllResources();
+   *           }
+   *           if (options.lng && options.ns) {
+   *             return await mySdk.getResource(options.lng, options.ns);
+   *           }
+   *           // Handle other cases...
+   *         }
+   *       }
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Single resource loading
+   * ```ts
+   * sdk: async (options) => {
+   *   if (options.lng && options.ns) {
+   *     const response = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+   *     return response.json();
+   *   }
+   * }
+   * ```
+   *
+   * @example Load all resources at once
+   * ```ts
+   * sdk: async (options) => {
+   *   if (options?.all) {
+   *     // Load all languages and namespaces
+   *     return await mySdk.getAllResources();
+   *   }
+   *   // Handle other cases...
+   * }
+   * ```
+   *
+   * @example Batch loading
+   * ```ts
+   * sdk: async (options) => {
+   *   if (options?.lngs && options?.nss) {
+   *     // Load multiple languages and namespaces
+   *     return await mySdk.getBatchResources(options.lngs, options.nss);
+   *   }
+   *   // Handle single or other cases...
+   * }
+   * ```
+   */
+  sdk?: I18nSdkLoader | boolean | string;
+}
+
+export interface BackendOptions extends BaseBackendOptions {
+  backendOptionsByEntry?: Record<string, BaseBackendOptions>;
+}

package/src/shared/utils.ts

@@ -0,0 +1,82 @@
+import type {
+  BackendOptions,
+  BaseBackendOptions,
+  BaseLocaleDetectionOptions,
+  LocaleDetectionOptions,
+} from './type';
+
+export function getEntryConfig<T extends Record<string, any>>(
+  entryName: string,
+  config: T,
+  entryKey: string,
+): T | undefined {
+  const entryConfigMap = (config as any)[entryKey] as
+    | Record<string, T>
+    | undefined;
+  return entryConfigMap?.[entryName];
+}
+
+export function removeEntryConfigKey<T extends Record<string, any>>(
+  config: T,
+  entryKey: string,
+): Omit<T, typeof entryKey> {
+  const { [entryKey]: _, ...rest } = config;
+  return rest;
+}
+
+export function getLocaleDetectionOptions(
+  entryName: string,
+  localeDetection: BaseLocaleDetectionOptions,
+): BaseLocaleDetectionOptions {
+  const fullConfig = localeDetection as LocaleDetectionOptions;
+  const entryConfig = getEntryConfig(
+    entryName,
+    fullConfig,
+    'localeDetectionByEntry',
+  );
+
+  if (entryConfig) {
+    const globalConfig = removeEntryConfigKey(
+      fullConfig,
+      'localeDetectionByEntry',
+    );
+    return {
+      ...globalConfig,
+      ...entryConfig,
+    };
+  }
+
+  if ('localeDetectionByEntry' in fullConfig) {
+    return removeEntryConfigKey(fullConfig, 'localeDetectionByEntry');
+  }
+
+  return localeDetection;
+}
+
+export function getBackendOptions(
+  entryName: string,
+  backend: BaseBackendOptions,
+): BaseBackendOptions {
+  const fullConfig = backend as BackendOptions;
+  const entryConfig = getEntryConfig(
+    entryName,
+    fullConfig,
+    'backendOptionsByEntry',
+  );
+  if (entryConfig) {
+    const globalConfig = removeEntryConfigKey(
+      fullConfig,
+      'backendOptionsByEntry',
+    );
+    return {
+      ...globalConfig,
+      ...entryConfig,
+    };
+  }
+
+  if ('backendOptionsByEntry' in fullConfig) {
+    return removeEntryConfigKey(fullConfig, 'backendOptionsByEntry');
+  }
+
+  return backend;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@modern-js/tsconfig/base",
+  "compilerOptions": {
+    "declaration": false,
+    "lib": ["DOM", "ESNext", "dom.iterable"],
+    "jsx": "preserve",
+    "baseUrl": "./",
+    "isolatedModules": true,
+    "paths": {},
+    "rootDir": "./src"
+  },
+  "include": ["src", "types"]
+}