@od-oneapp/internationalization 2026.1.1301

package/src/shared/dictionary-loader.ts

@@ -0,0 +1,599 @@
+/**
+ * @fileoverview Shared dictionary loading utility
+ *
+ * This utility provides type-safe dictionary loading with proper error handling
+ * and fallback mechanisms. It eliminates code duplication between server.ts and index.ts.
+ *
+ * Features:
+ * - In-memory LRU cache for loaded dictionaries
+ * - Cache statistics for monitoring
+ * - Error handling with fallback to default locale
+ * - Support for multiple locales
+ *
+ * @module @repo/internationalization/shared/dictionary-loader
+ */
+
+import { logDebug, logError, logWarn } from '@repo/shared/logger';
+
+import languine from '../../languine.json';
+
+import type en from '../dictionaries/en.json';
+
+const locales = [languine.locale.source, ...languine.locale.targets] as const;
+
+export type Locale = (typeof locales)[number];
+export type Dictionary = typeof en;
+
+// In-memory cache for loaded dictionaries with LRU eviction
+// Limited to prevent memory bloat in long-running Node 22 processes
+// Can be configured via environment variable for different deployment scenarios
+const MAX_CACHE_SIZE = Number.parseInt(process.env.I18N_CACHE_MAX_SIZE ?? '10', 10) ?? 10;
+const dictionaryCache = new Map<Locale, Promise<Dictionary>>();
+
+// Cache statistics for monitoring (Node 22 performance tracking)
+// Use Number.MAX_SAFE_INTEGER to prevent overflow in long-running processes
+const MAX_SAFE_COUNT = Number.MAX_SAFE_INTEGER;
+const cacheStats = {
+  hits: 0,
+  misses: 0,
+  evictions: 0,
+  errors: 0,
+};
+
+/**
+ * Gets current cache statistics for monitoring and debugging.
+ * Useful for production performance analysis.
+ *
+ * @returns Cache statistics object with hits, misses, evictions, and errors
+ */
+export function getCacheStats() {
+  return {
+    ...cacheStats,
+    size: dictionaryCache.size,
+    maxSize: MAX_CACHE_SIZE,
+    hitRate:
+      cacheStats.hits + cacheStats.misses > 0
+        ? `${((cacheStats.hits / (cacheStats.hits + cacheStats.misses)) * 100).toFixed(2)}%`
+        : '0%',
+  };
+}
+
+/**
+ * Resets cache statistics. Useful for testing or periodic reset.
+ * Also prevents overflow in long-running processes.
+ *
+ * Note: This only resets statistics counters, not the cache itself.
+ * To clear the cache entries, create a new dictionary loader instance.
+ */
+export function resetCacheStats(): void {
+  cacheStats.hits = 0;
+  cacheStats.misses = 0;
+  cacheStats.evictions = 0;
+  cacheStats.errors = 0;
+}
+
+/**
+ * Implements LRU (Least Recently Used) cache eviction.
+ * Moves accessed item to end of Map (most recent).
+ * Node 22 Map maintains insertion order.
+ *
+ * @param locale - The locale to mark as recently used
+ */
+function touchCache(locale: Locale): void {
+  const value = dictionaryCache.get(locale);
+  if (value) {
+    // Remove and re-add to move to end (most recent)
+    dictionaryCache.delete(locale);
+    dictionaryCache.set(locale, value);
+  }
+}
+
+/**
+ * Removes the least-recently-used dictionary from the in-memory cache when the cache size reaches the configured maximum.
+ *
+ * If an entry is evicted, increments the `cacheStats.evictions` counter with overflow protection and emits a debug log entry with eviction metadata when a logger is available.
+ */
+function evictOldestIfNeeded(): void {
+  if (dictionaryCache.size >= MAX_CACHE_SIZE) {
+    // First key is oldest (Map maintains insertion order)
+    const oldestKey = dictionaryCache.keys().next().value;
+    if (oldestKey) {
+      dictionaryCache.delete(oldestKey);
+      // Atomic increment with overflow protection
+      cacheStats.evictions = Math.min((cacheStats.evictions ?? 0) + 1, MAX_SAFE_COUNT);
+      logDebug('Dictionary cache eviction', {
+        evictedLocale: oldestKey,
+        cacheSize: dictionaryCache.size,
+        totalEvictions: cacheStats.evictions,
+        context: {
+          function: 'evictOldestIfNeeded',
+          package: '@repo/internationalization',
+        },
+      });
+    }
+  }
+}
+
+// Minimal valid dictionary structure for fallback
+// Matches the complete structure of en.json to prevent runtime errors
+const EMPTY_DICTIONARY: Dictionary = {
+  common: {
+    locale: '',
+    language: '',
+  },
+  web: {
+    global: {
+      primaryCta: '',
+      secondaryCta: '',
+    },
+    header: {
+      home: '',
+      product: {
+        title: '',
+        description: '',
+        pricing: '',
+      },
+      blog: '',
+      docs: '',
+      contact: '',
+      signIn: '',
+      signUp: '',
+    },
+    home: {
+      meta: {
+        title: '',
+        description: '',
+      },
+      hero: {
+        announcement: '',
+      },
+      cases: {
+        title: '',
+      },
+      features: {
+        title: '',
+        description: '',
+        items: [],
+      },
+      stats: {
+        title: '',
+        description: '',
+        items: [],
+      },
+      testimonials: {
+        title: '',
+        items: [],
+      },
+      faq: {
+        title: '',
+        description: '',
+        cta: '',
+        items: [],
+      },
+      cta: {
+        title: '',
+        description: '',
+      },
+    },
+    blog: {
+      meta: {
+        title: '',
+        description: '',
+      },
+    },
+    contact: {
+      meta: {
+        title: '',
+        description: '',
+      },
+      hero: {
+        benefits: [],
+        form: {
+          title: '',
+          date: '',
+          firstName: '',
+          lastName: '',
+          resume: '',
+          cta: '',
+        },
+      },
+    },
+  },
+};
+
+// Use the structured empty dictionary for type-safe fallback
+// EMPTY_DICTIONARY already provides the correct shape
+
+// Type-safe error for dictionary loading (reserved for future use)
+export interface _DictionaryLoadError {
+  locale: string;
+  message: string;
+  originalError: unknown;
+}
+
+/**
+ * Import a module with a timeout to prevent indefinite hangs.
+ * Uses Promise.race for timeout handling (import() cannot be cancelled).
+ *
+ * @param path - The module path to import
+ * @param timeoutMs - Timeout in milliseconds (default: 5000ms)
+ * @returns Promise that resolves to the imported module
+ * @throws Error if import times out or fails
+ */
+async function importWithTimeout<T>(path: string, timeoutMs = 5000): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    // Race between import and timeout
+    // Note: import() cannot be cancelled, but we can reject the promise on timeout
+    const result = await Promise.race([
+      import(path) as Promise<T>,
+      new Promise<never>((_resolve, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new Error(`Import timeout after ${timeoutMs}ms: ${path}`));
+        }, timeoutMs);
+      }),
+    ]);
+
+    // Clear timeout if import succeeded before timeout
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+
+    return result;
+  } catch (error: unknown) {
+    // Ensure timeout is cleared on error
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Validates and normalizes a locale string to prevent path traversal attacks.
+ *
+ * @param locale - The locale string to validate
+ * @returns The normalized locale if valid, null otherwise
+ */
+function validateAndNormalizeLocale(locale: string): Locale | null {
+  // Validate input length and type
+  if (!locale || typeof locale !== 'string' || locale.length > 20) {
+    return null;
+  }
+
+  // Validate pattern (alphanumeric and hyphens only, BCP 47 format)
+  // Safe regex: bounded quantifiers ({2}, {2,4}), input length pre-validated (max 20), no catastrophic backtracking
+  // eslint-disable-next-line regexp/no-unused-capturing-group, security/detect-unsafe-regex -- Capturing group needed for validation; regex is safe (bounded quantifiers, input length limited)
+  if (!/^[a-z]{2}(-[a-z]{2,4})?$/i.test(locale)) {
+    return null;
+  }
+
+  // Normalize to base locale (e.g., 'en-US' -> 'en')
+  const localeParts = locale.split('-');
+  const normalizedLocale = (localeParts[0] ?? locale).toLowerCase();
+
+  // Validate normalized locale exists in supported locales
+  if (!locales.includes(normalizedLocale)) {
+    return null;
+  }
+
+  return normalizedLocale;
+}
+
+/**
+ * Creates a type-safe dictionary loader with proper error handling
+ *
+ * @returns An object with methods to load dictionaries and check locale support
+ */
+export function createDictionaryLoader() {
+  const dictionaries: Record<Locale, () => Promise<Dictionary>> = Object.fromEntries(
+    locales.map(locale => [
+      locale,
+      (): Promise<Dictionary> => {
+        // Check cache first (LRU-aware)
+        if (dictionaryCache.has(locale)) {
+          touchCache(locale); // Mark as recently used
+          // Atomic increment for cache hit statistics with overflow protection
+          cacheStats.hits = Math.min((cacheStats.hits ?? 0) + 1, MAX_SAFE_COUNT);
+          const cached = dictionaryCache.get(locale);
+          if (!cached) {
+            throw new Error(
+              `Cache inconsistency: locale ${locale} was in cache but get returned undefined`,
+            );
+          }
+          // Log cache hit without sensitive performance data in production
+          if (process.env.NODE_ENV === 'development') {
+            logDebug('Dictionary cache hit', {
+              locale,
+              cached: true,
+              cacheSize: dictionaryCache.size,
+              hitRate: getCacheStats().hitRate,
+              context: {
+                function: 'createDictionaryLoader',
+                package: '@repo/internationalization',
+              },
+            });
+          }
+          return cached;
+        }
+
+        // Cache miss - atomic increment with overflow protection
+        cacheStats.misses = Math.min((cacheStats.misses ?? 0) + 1, MAX_SAFE_COUNT);
+
+        // Evict oldest entry if cache is full
+        evictOldestIfNeeded();
+
+        // Load and cache dictionary
+        // Track whether the original locale load succeeded (not a fallback)
+        let originalLoadSucceeded = false;
+        const loadPromise = (async (): Promise<Dictionary> => {
+          const startTime = performance.now();
+
+          try {
+            // Locale is guaranteed safe here as it comes from the locales array
+            // Use timeout to prevent indefinite hangs
+            const mod = await importWithTimeout<{ default: Dictionary }>(
+              `../dictionaries/${locale}.json`,
+              5000,
+            );
+
+            // Mark that original load succeeded (not a fallback)
+            originalLoadSucceeded = true;
+            const duration = performance.now() - startTime;
+
+            const dictionary = mod.default;
+
+            logDebug('Dictionary loaded successfully', {
+              locale,
+              duration: `${duration.toFixed(2)}ms`,
+              cached: false,
+              timestamp: new Date().toISOString(),
+              context: {
+                function: 'createDictionaryLoader',
+                package: '@repo/internationalization',
+              },
+            });
+
+            return dictionary;
+          } catch (error: unknown) {
+            const duration = performance.now() - startTime;
+            // Atomic increment for error statistics with overflow protection
+            cacheStats.errors = Math.min((cacheStats.errors ?? 0) + 1, MAX_SAFE_COUNT);
+            const errorMessage =
+              error instanceof Error
+                ? error.message
+                : typeof error === 'string'
+                  ? error
+                  : 'Unknown error';
+            const errorStack = error instanceof Error ? error.stack : undefined;
+
+            logError(`Failed to load dictionary for locale: ${locale}`, {
+              error: errorMessage,
+              stack: errorStack,
+              locale,
+              duration: `${duration.toFixed(2)}ms`,
+              totalErrors: cacheStats.errors,
+              context: {
+                function: 'createDictionaryLoader',
+                package: '@repo/internationalization',
+              },
+            });
+
+            // Fallback to English dictionary
+            // IMPORTANT: Do not cache fallback results - they should not be cached
+            // under the original locale key to prevent incorrect caching
+            try {
+              const fallbackStartTime = performance.now();
+              const fallbackMod = await importWithTimeout<{ default: Dictionary }>(
+                '../dictionaries/en.json',
+                5000,
+              );
+              const fallbackDuration = performance.now() - fallbackStartTime;
+
+              const fallbackDictionary = fallbackMod.default;
+
+              logDebug('English fallback dictionary loaded', {
+                originalLocale: locale,
+                fallbackLocale: 'en',
+                duration: `${fallbackDuration.toFixed(2)}ms`,
+                context: {
+                  function: 'createDictionaryLoader',
+                  package: '@repo/internationalization',
+                },
+              });
+
+              // Return fallback but don't cache it - let it fail again next time
+              // This ensures we don't cache incorrect locale mappings
+              return fallbackDictionary;
+            } catch (fallbackError: unknown) {
+              logError('Critical: English fallback dictionary failed to load', {
+                error:
+                  fallbackError instanceof Error
+                    ? fallbackError.message
+                    : typeof fallbackError === 'string'
+                      ? fallbackError
+                      : 'Unknown error',
+                stack: fallbackError instanceof Error ? fallbackError.stack : undefined,
+                locale,
+              });
+              // Bubble up failure so callers can log additional context
+              throw fallbackError;
+            }
+          }
+        })();
+
+        // Wrap promise to check if original load succeeded before caching
+        const cachedPromiseWrapper = async (): Promise<Dictionary> => {
+          try {
+            const result = await loadPromise;
+            // Only keep in cache if original load succeeded (not a fallback)
+            // If original load failed and we used fallback, remove from cache
+            const cached = dictionaryCache.get(locale);
+            if (!originalLoadSucceeded && cached === cachedPromise) {
+              dictionaryCache.delete(locale);
+            }
+            return result;
+          } catch (error: unknown) {
+            // If promise rejects, remove from cache
+            const cached = dictionaryCache.get(locale);
+            if (cached === cachedPromise) {
+              dictionaryCache.delete(locale);
+            }
+            throw error;
+          }
+        };
+
+        // Create the promise and cache it
+        const cachedPromise = cachedPromiseWrapper();
+
+        // Cache the promise initially - we'll remove it later if it was a fallback
+        dictionaryCache.set(locale, cachedPromise);
+
+        return cachedPromise;
+      },
+    ]) satisfies Array<[Locale, () => Promise<Dictionary>]>,
+  ) as Record<Locale, () => Promise<Dictionary>>;
+
+  return {
+    /**
+     * Loads a dictionary for the specified locale with proper type safety and fallbacks.
+     *
+     * @param locale - The locale string to load (e.g., 'en', 'en-US', 'es')
+     * @returns A promise that resolves to the dictionary for the locale
+     *
+     * @example
+     * ```typescript
+     * const loader = createDictionaryLoader();
+     * const dict = await loader.getDictionary('en');
+     * ```
+     */
+    async getDictionary(locale: string): Promise<Dictionary> {
+      const startTime = performance.now();
+
+      // Validate and normalize locale to prevent path traversal
+      const validatedLocale = validateAndNormalizeLocale(locale);
+
+      if (!validatedLocale) {
+        logWarn(`Invalid or unsupported locale "${locale}", defaulting to "en"`, {
+          locale,
+          context: {
+            function: 'getDictionary',
+            package: '@repo/internationalization',
+          },
+        });
+        // Safely attempt English fallback
+        try {
+          const result = await (dictionaries.en?.() ?? Promise.resolve(EMPTY_DICTIONARY));
+          const resolvedDictionary = result;
+          const duration = performance.now() - startTime;
+
+          logDebug('Dictionary loaded via fallback', {
+            requestedLocale: locale,
+            actualLocale: 'en',
+            duration: `${duration.toFixed(2)}ms`,
+            cached: dictionaryCache.has('en'),
+            context: {
+              function: 'getDictionary',
+              package: '@repo/internationalization',
+            },
+          });
+
+          return resolvedDictionary;
+        } catch (error: unknown) {
+          const duration = performance.now() - startTime;
+
+          logError('Failed to load English fallback dictionary', {
+            error:
+              error instanceof Error
+                ? error.message
+                : typeof error === 'string'
+                  ? error
+                  : 'Unknown error',
+            stack: error instanceof Error ? error.stack : undefined,
+            duration: `${duration.toFixed(2)}ms`,
+          });
+          return EMPTY_DICTIONARY;
+        }
+      }
+
+      try {
+        const result = await (dictionaries[validatedLocale]?.() ??
+          Promise.resolve(EMPTY_DICTIONARY));
+        const resolvedDictionary = result;
+        const duration = performance.now() - startTime;
+
+        logDebug('Dictionary retrieved', {
+          locale: validatedLocale,
+          duration: `${duration.toFixed(2)}ms`,
+          cached: dictionaryCache.has(validatedLocale),
+          context: {
+            function: 'getDictionary',
+            package: '@repo/internationalization',
+          },
+        });
+
+        return resolvedDictionary;
+      } catch (error: unknown) {
+        const duration = performance.now() - startTime;
+
+        logError(`Error loading dictionary for locale "${validatedLocale}", falling back to "en"`, {
+          error:
+            error instanceof Error
+              ? error.message
+              : typeof error === 'string'
+                ? error
+                : 'Unknown error',
+          stack: error instanceof Error ? error.stack : undefined,
+          locale: validatedLocale,
+          duration: `${duration.toFixed(2)}ms`,
+          context: {
+            function: 'getDictionary',
+            package: '@repo/internationalization',
+          },
+        });
+        // Safely attempt English fallback
+        try {
+          const fallbackResult = await (dictionaries.en?.() ?? Promise.resolve(EMPTY_DICTIONARY));
+          return fallbackResult;
+        } catch (fallbackError: unknown) {
+          logError('Failed to load English fallback dictionary', {
+            error:
+              fallbackError instanceof Error
+                ? fallbackError.message
+                : typeof fallbackError === 'string'
+                  ? fallbackError
+                  : 'Unknown error',
+            stack: fallbackError instanceof Error ? fallbackError.stack : undefined,
+          });
+          return EMPTY_DICTIONARY;
+        }
+      }
+    },
+
+    /**
+     * Get all available locales.
+     *
+     * @returns An array of all supported locale codes
+     */
+    getLocales: () => locales,
+
+    /**
+     * Check if a locale is supported.
+     *
+     * @param locale - The locale string to check
+     * @returns True if the locale is supported, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const loader = createDictionaryLoader();
+     * if (loader.isLocaleSupported('en-US')) {
+     *   // Load dictionary
+     * }
+     * ```
+     */
+    isLocaleSupported: (locale: string): boolean => {
+      return validateAndNormalizeLocale(locale) !== null;
+    },
+  };
+}

package/src/shared/next-intl-adapter.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview next-intl-adapter.ts
+ *
+ * Provides statically analyzable imports for next-intl modules.
+ * In test environments, falls back to mock modules.
+ */
+
+const isTestEnv = process.env.NODE_ENV === 'test' || process.env.VITEST === 'true';
+
+// Type declarations for the modules
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- Using typeof import() for module type inference
+type MiddlewareModule = typeof import('next-intl/middleware');
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- Using typeof import() for module type inference
+type NavigationModule = typeof import('next-intl/navigation');
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- Using typeof import() for module type inference
+type RoutingModule = typeof import('next-intl/routing');
+
+type LoadedModules = {
+  createMiddleware: MiddlewareModule['default'];
+  createNavigation: NavigationModule['createNavigation'];
+  defineRouting: RoutingModule['defineRouting'];
+};
+
+/**
+ * Load next-intl modules using static import paths so bundlers (Turbopack/webpack)
+ * can resolve them at build time. Variable-path dynamic imports break bundlers.
+ */
+const loadModules = async (): Promise<LoadedModules> => {
+  if (isTestEnv) {
+    // Test environment: use mocks
+    try {
+      const [
+        { default: mockMiddleware },
+        { createNavigation: mockNavigation },
+        { defineRouting: mockRouting },
+      ] = await Promise.all([
+        import('../../test/mocks/next-intl/middleware'),
+        import('../../test/mocks/next-intl/navigation'),
+        import('../../test/mocks/next-intl/routing'),
+      ]);
+      return {
+        createMiddleware: mockMiddleware as unknown as MiddlewareModule['default'],
+        createNavigation: mockNavigation as unknown as NavigationModule['createNavigation'],
+        defineRouting: mockRouting as unknown as RoutingModule['defineRouting'],
+      };
+    } catch (mockError) {
+      const msg =
+        mockError instanceof Error
+          ? mockError.message
+          : typeof mockError === 'string'
+            ? mockError
+            : 'Unknown error';
+      throw new Error(`Failed to load next-intl test mocks: ${msg}. Tests cannot continue.`);
+    }
+  }
+
+  // Production: static imports so bundlers can resolve them
+  try {
+    const [middlewareMod, navigationMod, routingMod] = await Promise.all([
+      import('next-intl/middleware'),
+      import('next-intl/navigation'),
+      import('next-intl/routing'),
+    ]);
+    return {
+      createMiddleware: middlewareMod.default,
+      createNavigation: navigationMod.createNavigation,
+      defineRouting: routingMod.defineRouting,
+    };
+  } catch (error) {
+    const msg =
+      error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error';
+    throw new Error(
+      `Failed to load next-intl modules in production: ${msg}. This is a critical error and the application cannot continue.`,
+    );
+  }
+};
+
+const { createMiddleware, createNavigation, defineRouting } = await loadModules();
+
+export { createMiddleware, createNavigation, defineRouting };