@lokascript/i18n 1.0.0

package/src/translator.ts

@@ -0,0 +1,297 @@
+// packages/i18n/src/translator.ts
+
+import {
+  Dictionary,
+  DICTIONARY_CATEGORIES,
+  I18nConfig,
+  TranslationOptions,
+  TranslationResult,
+  Token,
+  TokenType,
+  ValidationResult,
+} from './types';
+import { dictionaries } from './dictionaries';
+import { detectLocale } from './utils/locale';
+import { tokenize } from './utils/tokenizer';
+import { validate } from './validators';
+
+export class HyperscriptTranslator {
+  private config: I18nConfig;
+  private dictionaries: Map<string, Dictionary>;
+  private reverseDictionaries: Map<string, Map<string, string>>;
+
+  constructor(config: I18nConfig) {
+    this.config = {
+      fallbackLocale: 'en',
+      preserveOriginalAttribute: 'data-i18n-original',
+      detectLocale: true, // Enable language detection by default
+      ...config,
+      locale: config.locale || 'en', // Ensure locale has a default
+    };
+
+    this.dictionaries = new Map();
+    this.reverseDictionaries = new Map();
+
+    // Load built-in dictionaries
+    Object.entries(dictionaries).forEach(([locale, dict]) => {
+      this.addDictionary(locale, dict);
+    });
+
+    // Load custom dictionaries
+    if (config.dictionaries) {
+      Object.entries(config.dictionaries).forEach(([locale, dict]) => {
+        this.addDictionary(locale, dict);
+      });
+    }
+  }
+
+  translate(text: string, options: TranslationOptions): string {
+    const result = this.translateWithDetails(text, options);
+    return result.translated;
+  }
+
+  translateWithDetails(text: string, options: TranslationOptions): TranslationResult {
+    const fromLocale = options.from || this.detectLanguage(text);
+    const toLocale = options.to;
+
+    if (fromLocale === toLocale) {
+      return {
+        translated: text,
+        original: text,
+        tokens: [],
+        locale: { from: fromLocale, to: toLocale },
+      };
+    }
+
+    // Get dictionaries
+    const fromDict = this.getDictionary(fromLocale);
+    const toDict = this.getDictionary(toLocale);
+
+    if (!fromDict || !toDict) {
+      throw new Error(`Missing dictionary for locale: ${!fromDict ? fromLocale : toLocale}`);
+    }
+
+    // Tokenize the input
+    const tokens = tokenize(text, fromLocale);
+
+    // Translate tokens
+    const translatedTokens = this.translateTokens(tokens, fromLocale, toLocale);
+
+    // Reconstruct the text
+    const translated = this.reconstructText(translatedTokens);
+
+    // Validate target dictionary if requested
+    if (options.validate && toDict) {
+      const validation = validate(toDict, toLocale);
+      if (!validation.valid) {
+        console.warn('Translation validation warnings:', validation.warnings);
+      }
+    }
+
+    const result: TranslationResult = {
+      translated,
+      tokens: translatedTokens,
+      locale: { from: fromLocale, to: toLocale },
+      warnings: [],
+    };
+    if (options.preserveOriginal) {
+      result.original = text;
+    }
+    return result;
+  }
+
+  private translateTokens(tokens: Token[], fromLocale: string, toLocale: string): Token[] {
+    const fromDict = this.getDictionary(fromLocale);
+    const toDict = this.getDictionary(toLocale);
+    const reverseFromDict = this.getReverseDictionary(fromLocale);
+    const emptyDict: Dictionary = {
+      commands: {},
+      modifiers: {},
+      events: {},
+      logical: {},
+      temporal: {},
+      values: {},
+      attributes: {},
+      expressions: {},
+    };
+
+    return tokens.map(token => {
+      let translated = token.value;
+
+      // Only translate keywords, not identifiers or literals
+      if (this.isTranslatableToken(token)) {
+        // First, try direct translation from source to target
+        if (fromLocale !== 'en' && toLocale !== 'en') {
+          // Translate through English as intermediate
+          const english = this.findTranslation(token.value, fromDict || emptyDict, reverseFromDict);
+          if (english) {
+            translated =
+              this.findTranslation(english, toDict || emptyDict, new Map()) || token.value;
+          }
+        } else if (fromLocale === 'en') {
+          // Direct translation from English
+          translated =
+            this.findTranslation(token.value, toDict || emptyDict, new Map()) || token.value;
+        } else {
+          // Translation to English
+          translated =
+            this.findTranslation(token.value, fromDict || emptyDict, reverseFromDict) ||
+            token.value;
+        }
+      }
+
+      return {
+        ...token,
+        translated,
+      };
+    });
+  }
+
+  private findTranslation(
+    word: string,
+    dict: Dictionary,
+    reverseDict: Map<string, string>
+  ): string | null {
+    const lowerWord = word.toLowerCase();
+
+    // Check if translating FROM this locale using reverse dictionary
+    if (reverseDict.size > 0) {
+      const english = reverseDict.get(lowerWord);
+      if (english) return english;
+    }
+
+    // Check categories in priority order (events before commands to handle 'click' etc.)
+    const categoryOrder = [
+      'events',
+      'commands',
+      'expressions',
+      'modifiers',
+      'logical',
+      'temporal',
+      'values',
+      'attributes',
+    ];
+
+    for (const category of categoryOrder) {
+      const translations = dict[category as keyof Dictionary];
+      if (translations && typeof translations === 'object') {
+        for (const [key, value] of Object.entries(translations)) {
+          if (key.toLowerCase() === lowerWord) return value;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private isTranslatableToken(token: Token): boolean {
+    const translatableTypes: TokenType[] = [
+      'command',
+      'modifier',
+      'event',
+      'logical',
+      'temporal',
+      'value',
+      'attribute',
+      'expression',
+    ];
+    return translatableTypes.includes(token.type);
+  }
+
+  private reconstructText(tokens: Token[]): string {
+    return tokens.map(token => token.translated || token.value).join('');
+  }
+
+  detectLanguage(text: string): string {
+    if (!this.config.detectLocale) {
+      return this.config.locale;
+    }
+
+    return detectLocale(text, Array.from(this.dictionaries.keys()));
+  }
+
+  addDictionary(locale: string, dictionary: Dictionary): void {
+    this.dictionaries.set(locale, dictionary);
+
+    // Build reverse dictionary for this locale using type-safe iteration
+    const reverseDict = new Map<string, string>();
+
+    for (const category of DICTIONARY_CATEGORIES) {
+      const translations = dictionary[category];
+      if (translations) {
+        for (const [english, translated] of Object.entries(translations)) {
+          reverseDict.set(translated.toLowerCase(), english);
+        }
+      }
+    }
+
+    this.reverseDictionaries.set(locale, reverseDict);
+  }
+
+  getDictionary(locale: string): Dictionary | undefined {
+    return this.dictionaries.get(locale);
+  }
+
+  private getReverseDictionary(locale: string): Map<string, string> {
+    return this.reverseDictionaries.get(locale) || new Map();
+  }
+
+  getSupportedLocales(): string[] {
+    return Array.from(this.dictionaries.keys());
+  }
+
+  validateDictionary(locale: string): ValidationResult {
+    const dict = this.getDictionary(locale);
+    if (!dict) {
+      return {
+        valid: false,
+        errors: [
+          { type: 'missing', key: locale, message: `Dictionary not found for locale: ${locale}` },
+        ],
+        warnings: [],
+        coverage: { total: 0, translated: 0, missing: [] },
+      };
+    }
+
+    return validate(dict, locale);
+  }
+
+  isRTL(locale: string): boolean {
+    const rtlLocales = this.config.rtlLocales || ['ar', 'he', 'fa', 'ur'];
+    return rtlLocales.includes(locale);
+  }
+
+  getCompletions(context: { text: string; position: number; locale: string }): string[] {
+    const dict = this.getDictionary(context.locale);
+    if (!dict) return [];
+
+    const completions: string[] = [];
+
+    // Get the partial word at cursor
+    const beforeCursor = context.text.substring(0, context.position);
+    const partial = beforeCursor.match(/\b(\w+)$/)?.[1] || '';
+    const lowerPartial = partial.toLowerCase();
+
+    // Search all categories for matches using type-safe iteration
+    // For non-English locales, search translated values; for English, search keys
+    for (const category of DICTIONARY_CATEGORIES) {
+      const translations = dict[category];
+      if (translations) {
+        for (const [key, value] of Object.entries(translations)) {
+          // Search keys (English terms) and values (translated terms)
+          if (key.toLowerCase().startsWith(lowerPartial)) {
+            completions.push(key);
+          }
+          if (value.toLowerCase().startsWith(lowerPartial) && !completions.includes(value)) {
+            completions.push(value);
+          }
+        }
+      }
+    }
+
+    return completions;
+  }
+}
+
+// Export a singleton instance for convenience
+export const translator = new HyperscriptTranslator({ locale: 'en' });

package/src/types.ts

@@ -0,0 +1,209 @@
+// packages/i18n/src/types.ts
+
+/**
+ * Dictionary category names as a union type for type-safe access.
+ */
+export type DictionaryCategory =
+  | 'commands'
+  | 'modifiers'
+  | 'events'
+  | 'logical'
+  | 'temporal'
+  | 'values'
+  | 'attributes'
+  | 'expressions';
+
+/**
+ * All valid dictionary categories.
+ */
+export const DICTIONARY_CATEGORIES: readonly DictionaryCategory[] = [
+  'commands',
+  'modifiers',
+  'events',
+  'logical',
+  'temporal',
+  'values',
+  'attributes',
+  'expressions',
+] as const;
+
+/**
+ * Dictionary structure for i18n translations.
+ * Maps English canonical keywords to locale-specific translations.
+ *
+ * Note: Index signature removed for stricter type safety.
+ * Use DICTIONARY_CATEGORIES to iterate over categories.
+ */
+export interface Dictionary {
+  commands: Record<string, string>;
+  modifiers: Record<string, string>;
+  events: Record<string, string>;
+  logical: Record<string, string>;
+  temporal: Record<string, string>;
+  values: Record<string, string>;
+  attributes: Record<string, string>;
+  expressions: Record<string, string>;
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Type guard to check if a string is a valid dictionary category.
+ */
+export function isDictionaryCategory(key: string): key is DictionaryCategory {
+  return DICTIONARY_CATEGORIES.includes(key as DictionaryCategory);
+}
+
+/**
+ * Safely get a category from a dictionary with type narrowing.
+ * Returns undefined if the category doesn't exist.
+ */
+export function getDictionaryCategory(
+  dict: Dictionary,
+  category: string
+): Record<string, string> | undefined {
+  if (isDictionaryCategory(category)) {
+    return dict[category];
+  }
+  return undefined;
+}
+
+/**
+ * Iterate over all categories in a dictionary with proper typing.
+ */
+export function forEachCategory(
+  dict: Dictionary,
+  callback: (category: DictionaryCategory, entries: Record<string, string>) => void
+): void {
+  for (const category of DICTIONARY_CATEGORIES) {
+    callback(category, dict[category]);
+  }
+}
+
+/**
+ * Find a translation in any category of a dictionary.
+ * Returns the English key if found, undefined otherwise.
+ */
+export function findInDictionary(
+  dict: Dictionary,
+  localizedWord: string
+): { category: DictionaryCategory; englishKey: string } | undefined {
+  const normalized = localizedWord.toLowerCase();
+  for (const category of DICTIONARY_CATEGORIES) {
+    const entries = dict[category];
+    for (const [english, localized] of Object.entries(entries)) {
+      if (localized.toLowerCase() === normalized) {
+        return { category, englishKey: english };
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Find a translation for an English word in any category.
+ * Returns the localized word if found, undefined otherwise.
+ */
+export function translateFromEnglish(dict: Dictionary, englishWord: string): string | undefined {
+  const normalized = englishWord.toLowerCase();
+  for (const category of DICTIONARY_CATEGORIES) {
+    const entries = dict[category];
+    const translated = entries[normalized];
+    if (translated) {
+      return translated;
+    }
+  }
+  return undefined;
+}
+
+export interface I18nConfig {
+  locale: string;
+  fallbackLocale?: string;
+  dictionaries?: Record<string, Dictionary>;
+  detectLocale?: boolean;
+  rtlLocales?: string[];
+  preserveOriginalAttribute?: string;
+}
+
+export interface TranslationOptions {
+  from?: string;
+  to: string;
+  preserveOriginal?: boolean;
+  validate?: boolean;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+  coverage: {
+    total: number;
+    translated: number;
+    missing: string[];
+  };
+}
+
+export interface ValidationError {
+  type: 'missing' | 'invalid' | 'duplicate';
+  key: string;
+  message: string;
+}
+
+export interface ValidationWarning {
+  type: 'unused' | 'deprecated' | 'inconsistent';
+  key: string;
+  message: string;
+}
+
+export interface LocaleMetadata {
+  code: string;
+  name: string;
+  nativeName: string;
+  rtl: boolean;
+  pluralRules?: (n: number) => string;
+}
+
+export interface TranslationContext {
+  locale: string;
+  direction: 'ltr' | 'rtl';
+  dictionary: Dictionary;
+  metadata: LocaleMetadata;
+}
+
+export type TokenType =
+  | 'command'
+  | 'modifier'
+  | 'event'
+  | 'logical'
+  | 'temporal'
+  | 'value'
+  | 'attribute'
+  | 'expression'
+  | 'identifier'
+  | 'operator'
+  | 'literal';
+
+export interface Token {
+  type: TokenType;
+  value: string;
+  translated?: string;
+  position: {
+    start: number;
+    end: number;
+    line: number;
+    column: number;
+  };
+}
+
+export interface TranslationResult {
+  translated: string;
+  original?: string;
+  tokens: Token[];
+  locale: {
+    from: string;
+    to: string;
+  };
+  warnings?: string[];
+}

package/src/utils/locale.ts

@@ -0,0 +1,190 @@
+// packages/i18n/src/utils/locale.ts
+
+import { dictionaries } from '../dictionaries';
+import { DICTIONARY_CATEGORIES } from '../types';
+
+export interface LocaleInfo {
+  code: string;
+  language: string;
+  region?: string;
+  script?: string;
+}
+
+/**
+ * Parse a locale string into its components
+ * Examples: 'en-US', 'zh-Hans-CN', 'es-419'
+ */
+export function parseLocale(locale: string): LocaleInfo {
+  const parts = locale.split('-');
+  const info: LocaleInfo = {
+    code: locale,
+    language: parts[0].toLowerCase(),
+  };
+
+  if (parts.length > 1) {
+    // Check if second part is a script (4 letters, first capitalized)
+    if (parts[1].length === 4 && /^[A-Z][a-z]{3}$/.test(parts[1])) {
+      info.script = parts[1];
+      if (parts[2]) {
+        info.region = parts[2].toUpperCase();
+      }
+    } else {
+      info.region = parts[1].toUpperCase();
+    }
+  }
+
+  return info;
+}
+
+/**
+ * Detect the language of hyperscript text
+ */
+export function detectLocale(text: string, supportedLocales: string[]): string {
+  const scores = new Map<string, number>();
+
+  // Initialize scores
+  supportedLocales.forEach(locale => scores.set(locale, 0));
+
+  // Count keyword matches for each locale using type-safe iteration
+  for (const [locale, dictionary] of Object.entries(dictionaries)) {
+    if (!supportedLocales.includes(locale)) continue;
+
+    let score = 0;
+
+    // Check all categories
+    for (const category of DICTIONARY_CATEGORIES) {
+      const translations = dictionary[category];
+      for (const keyword of Object.values(translations)) {
+        // Skip empty or single-character keywords (too ambiguous for detection)
+        if (!keyword || keyword.length < 2) continue;
+
+        // Use word boundary matching for accuracy
+        const regex = new RegExp(`\\b${escapeRegex(keyword)}\\b`, 'gi');
+        const matches = text.match(regex);
+        if (matches) {
+          score += matches.length;
+        }
+      }
+    }
+
+    scores.set(locale, score);
+  }
+
+  // Find locale with highest score
+  let maxScore = 0;
+  let detectedLocale = 'en'; // Default to English
+
+  scores.forEach((score, locale) => {
+    if (score > maxScore) {
+      maxScore = score;
+      detectedLocale = locale;
+    }
+  });
+
+  return detectedLocale;
+}
+
+/**
+ * Get the best matching locale from available locales
+ */
+export function getBestMatchingLocale(
+  requestedLocale: string,
+  availableLocales: string[]
+): string | null {
+  // Exact match
+  if (availableLocales.includes(requestedLocale)) {
+    return requestedLocale;
+  }
+
+  const requested = parseLocale(requestedLocale);
+
+  // Try language-only match
+  const languageMatch = availableLocales.find(locale => {
+    const available = parseLocale(locale);
+    return available.language === requested.language;
+  });
+
+  if (languageMatch) {
+    return languageMatch;
+  }
+
+  // Try language-script match
+  if (requested.script) {
+    const scriptMatch = availableLocales.find(locale => {
+      const available = parseLocale(locale);
+      return available.language === requested.language && available.script === requested.script;
+    });
+
+    if (scriptMatch) {
+      return scriptMatch;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get user's preferred locales from browser
+ */
+export function getBrowserLocales(): string[] {
+  if (typeof window === 'undefined') {
+    return ['en'];
+  }
+
+  const locales: string[] = [];
+
+  // Modern browser API
+  if (navigator.languages && navigator.languages.length > 0) {
+    locales.push(...navigator.languages);
+  }
+
+  // Fallback to single language
+  if (navigator.language) {
+    locales.push(navigator.language);
+  }
+
+  // Legacy IE
+  if ((navigator as any).userLanguage) {
+    locales.push((navigator as any).userLanguage);
+  }
+
+  // Remove duplicates and return
+  return [...new Set(locales)];
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Format a locale for display
+ */
+export function formatLocaleName(locale: string): string {
+  const names: Record<string, string> = {
+    en: 'English',
+    es: 'Español',
+    ko: '한국어',
+    zh: '中文',
+    'zh-TW': '繁體中文',
+    ja: '日本語',
+    fr: 'Français',
+    de: 'Deutsch',
+    pt: 'Português',
+    hi: 'हिन्दी',
+    ar: 'العربية',
+  };
+
+  return names[locale] || locale;
+}
+
+/**
+ * Check if a locale uses RTL writing
+ */
+export function isRTL(locale: string): boolean {
+  const rtlLocales = ['ar', 'he', 'fa', 'ur', 'yi', 'ji', 'ku', 'dv'];
+  const info = parseLocale(locale);
+  return rtlLocales.includes(info.language);
+}