convex-cms 0.0.1

package/src/component/localeFallbackChain.ts

@@ -0,0 +1,673 @@
+/**
+ * Locale Fallback Chain Configuration and Utilities
+ *
+ * This module provides configuration and utility functions for locale fallback chains.
+ * When content isn't available in a requested locale, the system falls back through
+ * a configured chain until content is found.
+ *
+ * @example
+ * ```typescript
+ * // Configure fallback chains
+ * const config: LocaleFallbackConfig = {
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES", "en-US"],  // Mexican Spanish -> Spain Spanish -> US English
+ *     "es-ES": ["en-US"],            // Spain Spanish -> US English
+ *     "fr-CA": ["fr-FR", "en-US"],   // Canadian French -> France French -> US English
+ *     "zh-Hans-CN": ["zh-Hans", "en-US"], // Simplified Chinese (China) -> Simplified Chinese -> US English
+ *   },
+ * };
+ *
+ * // Resolve fallback chain for a locale
+ * const chain = resolveFallbackChain("es-MX", config);
+ * // Returns: ["es-ES", "en-US", "en-US"] -> deduplicated to ["es-ES", "en-US"]
+ * ```
+ *
+ * @module localeFallbackChain
+ */
+
+import type { LocaleResolutionOptions } from "./localeFields.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * BCP 47 locale code (e.g., "en-US", "zh-Hans", "zh-Hans-CN").
+ */
+export type LocaleCode = string;
+
+/**
+ * Configuration for locale fallback behavior.
+ *
+ * Defines how the system should resolve content when the requested locale
+ * is not available. Fallback chains are tried in order until content is found.
+ */
+export interface LocaleFallbackConfig {
+  /**
+   * The default locale used as the final fallback when all other options are exhausted.
+   * This should be the locale with the most complete content.
+   *
+   * @default "en"
+   */
+  defaultLocale: LocaleCode;
+
+  /**
+   * Mapping of locale codes to their fallback chains.
+   * Each locale can have an ordered array of fallback locales to try.
+   *
+   * @example
+   * ```typescript
+   * fallbackChains: {
+   *   "es-MX": ["es-ES", "en-US"],  // Try Spain Spanish, then US English
+   *   "es-AR": ["es-ES", "en-US"],  // Argentine Spanish also falls back to Spain Spanish
+   *   "pt-BR": ["pt-PT", "en-US"],  // Brazilian Portuguese -> Portugal Portuguese
+   * }
+   * ```
+   */
+  fallbackChains?: Record<LocaleCode, LocaleCode[]>;
+
+  /**
+   * Whether to automatically generate fallback chains based on locale hierarchy.
+   *
+   * When enabled, the system will automatically create fallback chains based on
+   * the BCP 47 locale structure:
+   * - "zh-Hans-CN" -> ["zh-Hans", "zh", defaultLocale]
+   * - "en-US" -> ["en", defaultLocale]
+   *
+   * Explicit fallbackChains take precedence over auto-generated ones.
+   *
+   * @default true
+   */
+  autoGenerateFallbacks?: boolean;
+
+  /**
+   * List of supported locales. If provided, fallback chains will only include
+   * locales from this list.
+   *
+   * @example
+   * ```typescript
+   * supportedLocales: ["en-US", "es-ES", "fr-FR", "de-DE"]
+   * ```
+   */
+  supportedLocales?: LocaleCode[];
+}
+
+/**
+ * Result of resolving a fallback chain for a locale.
+ */
+export interface ResolvedFallbackChain {
+  /**
+   * The original locale that was requested.
+   */
+  requestedLocale: LocaleCode;
+
+  /**
+   * The complete fallback chain in priority order.
+   * Does not include the requested locale itself.
+   */
+  fallbackChain: LocaleCode[];
+
+  /**
+   * The default locale (final fallback).
+   */
+  defaultLocale: LocaleCode;
+
+  /**
+   * Whether the chain was auto-generated or explicitly configured.
+   */
+  isAutoGenerated: boolean;
+}
+
+/**
+ * Options for building a fallback chain.
+ */
+export interface BuildFallbackChainOptions {
+  /**
+   * Whether to include the default locale in the chain.
+   * @default true
+   */
+  includeDefault?: boolean;
+
+  /**
+   * Whether to deduplicate the chain (remove duplicate locales).
+   * @default true
+   */
+  deduplicate?: boolean;
+
+  /**
+   * Maximum length of the fallback chain.
+   * @default 10
+   */
+  maxLength?: number;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Default fallback configuration.
+ */
+export const DEFAULT_FALLBACK_CONFIG: Required<LocaleFallbackConfig> = {
+  defaultLocale: "en",
+  fallbackChains: {},
+  autoGenerateFallbacks: true,
+  supportedLocales: [],
+};
+
+// =============================================================================
+// Locale Parsing Utilities
+// =============================================================================
+
+/**
+ * Parsed components of a BCP 47 locale code.
+ */
+export interface ParsedLocale {
+  /**
+   * The language code (2-3 lowercase letters).
+   * @example "en", "zh", "pt"
+   */
+  language: string;
+
+  /**
+   * The script code (4 letters, title case), if present.
+   * @example "Hans", "Hant", "Latn"
+   */
+  script?: string;
+
+  /**
+   * The region code (2 uppercase letters), if present.
+   * @example "US", "CN", "BR"
+   */
+  region?: string;
+}
+
+/**
+ * Parses a BCP 47 locale code into its components.
+ *
+ * Supports the following formats:
+ * - "en" (language only)
+ * - "en-US" (language + region)
+ * - "zh-Hans" (language + script)
+ * - "zh-Hans-CN" (language + script + region)
+ *
+ * @param locale - The locale code to parse
+ * @returns The parsed locale components, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseLocale("en-US");
+ * // Returns: { language: "en", region: "US" }
+ *
+ * parseLocale("zh-Hans-CN");
+ * // Returns: { language: "zh", script: "Hans", region: "CN" }
+ *
+ * parseLocale("invalid");
+ * // Returns: null
+ * ```
+ */
+export function parseLocale(locale: LocaleCode): ParsedLocale | null {
+  if (!locale || typeof locale !== "string") {
+    return null;
+  }
+
+  // Pattern: language[-Script][-REGION]
+  // Language: 2-3 lowercase letters
+  // Script: 4 letters, title case (optional)
+  // Region: 2 uppercase letters (optional)
+  const pattern = /^([a-z]{2,3})(?:-([A-Z][a-z]{3}))?(?:-([A-Z]{2}))?$/;
+  const match = locale.match(pattern);
+
+  if (!match) {
+    // Try simpler patterns
+    // Just language
+    if (/^[a-z]{2,3}$/.test(locale)) {
+      return { language: locale };
+    }
+    return null;
+  }
+
+  const [, language, script, region] = match;
+
+  const result: ParsedLocale = { language };
+  if (script) result.script = script;
+  if (region) result.region = region;
+
+  return result;
+}
+
+/**
+ * Formats parsed locale components back into a BCP 47 locale code.
+ *
+ * @param parsed - The parsed locale components
+ * @returns The formatted locale code
+ *
+ * @example
+ * ```typescript
+ * formatLocale({ language: "en", region: "US" });
+ * // Returns: "en-US"
+ *
+ * formatLocale({ language: "zh", script: "Hans", region: "CN" });
+ * // Returns: "zh-Hans-CN"
+ * ```
+ */
+export function formatLocale(parsed: ParsedLocale): LocaleCode {
+  let result = parsed.language;
+  if (parsed.script) result += `-${parsed.script}`;
+  if (parsed.region) result += `-${parsed.region}`;
+  return result;
+}
+
+/**
+ * Generates the locale hierarchy (parent locales) for a given locale.
+ *
+ * @param locale - The locale to get hierarchy for
+ * @returns Array of parent locales from most specific to least specific
+ *
+ * @example
+ * ```typescript
+ * getLocaleHierarchy("zh-Hans-CN");
+ * // Returns: ["zh-Hans", "zh"]
+ *
+ * getLocaleHierarchy("en-US");
+ * // Returns: ["en"]
+ *
+ * getLocaleHierarchy("en");
+ * // Returns: []
+ * ```
+ */
+export function getLocaleHierarchy(locale: LocaleCode): LocaleCode[] {
+  const parsed = parseLocale(locale);
+  if (!parsed) return [];
+
+  const hierarchy: LocaleCode[] = [];
+
+  // If we have region, add without region
+  if (parsed.region) {
+    if (parsed.script) {
+      // zh-Hans-CN -> zh-Hans
+      hierarchy.push(formatLocale({ language: parsed.language, script: parsed.script }));
+    }
+    // zh-Hans-CN -> zh, or en-US -> en
+    hierarchy.push(parsed.language);
+  } else if (parsed.script) {
+    // zh-Hans -> zh
+    hierarchy.push(parsed.language);
+  }
+
+  return hierarchy;
+}
+
+// =============================================================================
+// Fallback Chain Resolution
+// =============================================================================
+
+/**
+ * Resolves the complete fallback chain for a locale.
+ *
+ * The resolution order is:
+ * 1. Explicit fallback chain from configuration (if defined)
+ * 2. Auto-generated hierarchy-based chain (if enabled)
+ * 3. Default locale as final fallback
+ *
+ * @param locale - The locale to resolve the fallback chain for
+ * @param config - The fallback configuration
+ * @param options - Options for building the chain
+ * @returns The resolved fallback chain
+ *
+ * @example
+ * ```typescript
+ * const config: LocaleFallbackConfig = {
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES"],
+ *   },
+ * };
+ *
+ * // Explicit chain
+ * resolveFallbackChain("es-MX", config);
+ * // Returns: { requestedLocale: "es-MX", fallbackChain: ["es-ES", "en-US"], ... }
+ *
+ * // Auto-generated chain
+ * resolveFallbackChain("fr-CA", config);
+ * // Returns: { requestedLocale: "fr-CA", fallbackChain: ["fr", "en-US"], ... }
+ * ```
+ */
+export function resolveFallbackChain(
+  locale: LocaleCode,
+  config: LocaleFallbackConfig = DEFAULT_FALLBACK_CONFIG,
+  options: BuildFallbackChainOptions = {}
+): ResolvedFallbackChain {
+  const {
+    includeDefault = true,
+    deduplicate = true,
+    maxLength = 10,
+  } = options;
+
+  const {
+    defaultLocale = DEFAULT_FALLBACK_CONFIG.defaultLocale,
+    fallbackChains = {},
+    autoGenerateFallbacks = true,
+    supportedLocales = [],
+  } = config;
+
+  let chain: LocaleCode[] = [];
+  let isAutoGenerated = false;
+
+  // Check for explicit fallback chain
+  if (fallbackChains[locale]) {
+    chain = [...fallbackChains[locale]];
+  } else if (autoGenerateFallbacks) {
+    // Auto-generate based on locale hierarchy
+    chain = getLocaleHierarchy(locale);
+    isAutoGenerated = true;
+  }
+
+  // Add default locale if not already in chain
+  if (includeDefault && !chain.includes(defaultLocale)) {
+    chain.push(defaultLocale);
+  }
+
+  // Filter to supported locales if specified
+  if (supportedLocales.length > 0) {
+    chain = chain.filter((l) => supportedLocales.includes(l));
+  }
+
+  // Deduplicate
+  if (deduplicate) {
+    chain = [...new Set(chain)];
+  }
+
+  // Remove the requested locale itself if present
+  chain = chain.filter((l) => l !== locale);
+
+  // Limit length
+  if (chain.length > maxLength) {
+    chain = chain.slice(0, maxLength);
+  }
+
+  return {
+    requestedLocale: locale,
+    fallbackChain: chain,
+    defaultLocale,
+    isAutoGenerated,
+  };
+}
+
+/**
+ * Gets the fallback chain as a simple array of locale codes.
+ *
+ * This is a convenience function for use with `getLocalizedValue`.
+ *
+ * @param locale - The locale to get fallback chain for
+ * @param config - The fallback configuration
+ * @returns Array of fallback locale codes
+ *
+ * @example
+ * ```typescript
+ * const chain = getFallbackChain("es-MX", config);
+ * // Returns: ["es-ES", "en-US"]
+ *
+ * // Use with getLocalizedValue
+ * const result = getLocalizedValue(value, {
+ *   locale: "es-MX",
+ *   fallbackChain: chain,
+ * });
+ * ```
+ */
+export function getFallbackChain(
+  locale: LocaleCode,
+  config: LocaleFallbackConfig = DEFAULT_FALLBACK_CONFIG
+): LocaleCode[] {
+  return resolveFallbackChain(locale, config).fallbackChain;
+}
+
+// =============================================================================
+// Configuration Utilities
+// =============================================================================
+
+/**
+ * Creates a LocaleFallbackConfig with defaults applied.
+ *
+ * @param config - Partial configuration to merge with defaults
+ * @returns Complete configuration with defaults
+ *
+ * @example
+ * ```typescript
+ * const config = createFallbackConfig({
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES"],
+ *   },
+ * });
+ * ```
+ */
+export function createFallbackConfig(
+  config: Partial<LocaleFallbackConfig> = {}
+): Required<LocaleFallbackConfig> {
+  return {
+    defaultLocale: config.defaultLocale ?? DEFAULT_FALLBACK_CONFIG.defaultLocale,
+    fallbackChains: config.fallbackChains ?? DEFAULT_FALLBACK_CONFIG.fallbackChains,
+    autoGenerateFallbacks: config.autoGenerateFallbacks ?? DEFAULT_FALLBACK_CONFIG.autoGenerateFallbacks,
+    supportedLocales: config.supportedLocales ?? DEFAULT_FALLBACK_CONFIG.supportedLocales,
+  };
+}
+
+/**
+ * Validates a LocaleFallbackConfig for common issues.
+ *
+ * @param config - The configuration to validate
+ * @returns Array of validation errors (empty if valid)
+ *
+ * @example
+ * ```typescript
+ * const errors = validateFallbackConfig({
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["invalid-locale"],
+ *   },
+ *   supportedLocales: ["en-US", "es-ES"],
+ * });
+ * // Returns: ["Fallback chain for 'es-MX' contains unsupported locale: 'invalid-locale'"]
+ * ```
+ */
+export function validateFallbackConfig(config: LocaleFallbackConfig): string[] {
+  const errors: string[] = [];
+  const { defaultLocale, fallbackChains = {}, supportedLocales = [] } = config;
+
+  // Check default locale
+  if (!defaultLocale) {
+    errors.push("defaultLocale is required");
+  } else if (!parseLocale(defaultLocale)) {
+    errors.push(`Invalid defaultLocale format: '${defaultLocale}'`);
+  }
+
+  // Check supported locales include default
+  if (supportedLocales.length > 0 && defaultLocale && !supportedLocales.includes(defaultLocale)) {
+    errors.push(`defaultLocale '${defaultLocale}' is not in supportedLocales`);
+  }
+
+  // Validate fallback chains
+  for (const [locale, chain] of Object.entries(fallbackChains)) {
+    // Check locale format
+    if (!parseLocale(locale)) {
+      errors.push(`Invalid locale format in fallbackChains: '${locale}'`);
+    }
+
+    // Check chain items
+    for (const fallback of chain) {
+      if (!parseLocale(fallback)) {
+        errors.push(`Invalid fallback locale format for '${locale}': '${fallback}'`);
+      }
+
+      // Check against supported locales
+      if (supportedLocales.length > 0 && !supportedLocales.includes(fallback)) {
+        errors.push(`Fallback chain for '${locale}' contains unsupported locale: '${fallback}'`);
+      }
+    }
+
+    // Check for circular references
+    if (chain.includes(locale)) {
+      errors.push(`Fallback chain for '${locale}' contains self-reference`);
+    }
+  }
+
+  // Validate supported locales formats
+  for (const locale of supportedLocales) {
+    if (!parseLocale(locale)) {
+      errors.push(`Invalid locale format in supportedLocales: '${locale}'`);
+    }
+  }
+
+  return errors;
+}
+
+// =============================================================================
+// Integration with LocaleResolutionOptions
+// =============================================================================
+
+/**
+ * Builds LocaleResolutionOptions from a locale and fallback configuration.
+ *
+ * This function creates the options object needed by `getLocalizedValue` and
+ * `resolveContentData` from the locale fallback configuration.
+ *
+ * @param locale - The requested locale
+ * @param config - The fallback configuration
+ * @returns LocaleResolutionOptions for use with locale resolution functions
+ *
+ * @example
+ * ```typescript
+ * const config: LocaleFallbackConfig = {
+ *   defaultLocale: "en-US",
+ *   fallbackChains: {
+ *     "es-MX": ["es-ES"],
+ *   },
+ * };
+ *
+ * const options = buildLocaleResolutionOptions("es-MX", config);
+ * // Returns: {
+ * //   locale: "es-MX",
+ * //   fallbackChain: ["es-ES", "en-US"],
+ * //   defaultLocale: "en-US"
+ * // }
+ *
+ * // Use with getLocalizedValue
+ * const result = getLocalizedValue(value, options);
+ * ```
+ */
+export function buildLocaleResolutionOptions(
+  locale: LocaleCode,
+  config: LocaleFallbackConfig = DEFAULT_FALLBACK_CONFIG
+): LocaleResolutionOptions {
+  const resolved = resolveFallbackChain(locale, config);
+
+  return {
+    locale,
+    fallbackChain: resolved.fallbackChain,
+    defaultLocale: resolved.defaultLocale,
+  };
+}
+
+// =============================================================================
+// Common Fallback Chain Presets
+// =============================================================================
+
+/**
+ * Preset fallback configurations for common localization scenarios.
+ */
+export const FALLBACK_PRESETS = {
+  /**
+   * Spanish locale family fallback chain.
+   * Regional Spanish variants fall back to Spain Spanish, then English.
+   */
+  spanish: {
+    "es-MX": ["es-ES", "en"],     // Mexican Spanish
+    "es-AR": ["es-ES", "en"],     // Argentine Spanish
+    "es-CO": ["es-ES", "en"],     // Colombian Spanish
+    "es-CL": ["es-ES", "en"],     // Chilean Spanish
+    "es-PE": ["es-ES", "en"],     // Peruvian Spanish
+    "es-VE": ["es-ES", "en"],     // Venezuelan Spanish
+    "es-ES": ["en"],              // Spain Spanish
+  },
+
+  /**
+   * Portuguese locale family fallback chain.
+   * Brazilian Portuguese falls back to Portugal Portuguese, then English.
+   */
+  portuguese: {
+    "pt-BR": ["pt-PT", "en"],     // Brazilian Portuguese
+    "pt-PT": ["en"],              // Portugal Portuguese
+  },
+
+  /**
+   * Chinese locale family fallback chain.
+   * Simplified and Traditional Chinese with regional variants.
+   */
+  chinese: {
+    "zh-Hans-CN": ["zh-Hans", "zh", "en"], // Simplified Chinese (China)
+    "zh-Hans-SG": ["zh-Hans", "zh", "en"], // Simplified Chinese (Singapore)
+    "zh-Hant-TW": ["zh-Hant", "zh", "en"], // Traditional Chinese (Taiwan)
+    "zh-Hant-HK": ["zh-Hant", "zh", "en"], // Traditional Chinese (Hong Kong)
+    "zh-Hans": ["zh", "en"],               // Simplified Chinese
+    "zh-Hant": ["zh", "en"],               // Traditional Chinese
+  },
+
+  /**
+   * French locale family fallback chain.
+   */
+  french: {
+    "fr-CA": ["fr-FR", "en"],     // Canadian French
+    "fr-BE": ["fr-FR", "en"],     // Belgian French
+    "fr-CH": ["fr-FR", "en"],     // Swiss French
+    "fr-FR": ["en"],              // France French
+  },
+
+  /**
+   * German locale family fallback chain.
+   */
+  german: {
+    "de-AT": ["de-DE", "en"],     // Austrian German
+    "de-CH": ["de-DE", "en"],     // Swiss German
+    "de-DE": ["en"],              // Germany German
+  },
+
+  /**
+   * English locale family fallback chain.
+   */
+  english: {
+    "en-GB": ["en-US", "en"],     // British English
+    "en-AU": ["en-GB", "en-US", "en"], // Australian English
+    "en-CA": ["en-US", "en"],     // Canadian English
+    "en-NZ": ["en-AU", "en-GB", "en"], // New Zealand English
+    "en-US": ["en"],              // US English
+  },
+} as const;
+
+/**
+ * Merges multiple fallback chain presets into a single configuration.
+ *
+ * @param presets - Array of preset names to merge
+ * @returns Combined fallback chains
+ *
+ * @example
+ * ```typescript
+ * const chains = mergeFallbackPresets(["spanish", "portuguese"]);
+ * // Returns merged chains for both Spanish and Portuguese locales
+ * ```
+ */
+export function mergeFallbackPresets(
+  presets: (keyof typeof FALLBACK_PRESETS)[]
+): Record<LocaleCode, LocaleCode[]> {
+  const merged: Record<LocaleCode, LocaleCode[]> = {};
+
+  for (const presetName of presets) {
+    const preset = FALLBACK_PRESETS[presetName];
+    if (preset) {
+      Object.assign(merged, preset);
+    }
+  }
+
+  return merged;
+}