@lokascript/i18n 1.0.0

package/src/parser/analyze-conflicts.test.ts

@@ -0,0 +1,229 @@
+// packages/i18n/src/parser/analyze-conflicts.test.ts
+/**
+ * Analyzes dictionaries for parsing conflicts.
+ *
+ * A conflict occurs when the same locale word maps to different English words
+ * across different categories (e.g., 'de' in Spanish maps to both 'from' and 'of').
+ *
+ * The priority system in create-provider.ts handles these by giving priority to:
+ * commands > logical > events > values > temporal > modifiers > attributes
+ */
+
+import { describe, it, expect } from 'vitest';
+import { es } from '../dictionaries/es';
+import { ja } from '../dictionaries/ja';
+import { fr } from '../dictionaries/fr';
+import { de } from '../dictionaries/de';
+import { ar } from '../dictionaries/ar';
+import { ko } from '../dictionaries/ko';
+import { zh } from '../dictionaries/zh';
+import { tr } from '../dictionaries/tr';
+import type { Dictionary } from '../types';
+
+interface Conflict {
+  localeWord: string;
+  mappings: Array<{ english: string; category: string }>;
+}
+
+function analyzeConflicts(dictionary: Dictionary, localeName: string): Conflict[] {
+  const conflicts: Conflict[] = [];
+  const wordMap = new Map<string, Array<{ english: string; category: string }>>();
+
+  const categories = [
+    { name: 'commands', data: dictionary.commands },
+    { name: 'modifiers', data: dictionary.modifiers },
+    { name: 'events', data: dictionary.events },
+    { name: 'logical', data: dictionary.logical },
+    { name: 'temporal', data: dictionary.temporal },
+    { name: 'values', data: dictionary.values },
+    { name: 'attributes', data: dictionary.attributes },
+  ];
+
+  for (const { name, data } of categories) {
+    if (!data) continue;
+    for (const [english, locale] of Object.entries(data)) {
+      const normalized = locale.toLowerCase();
+      if (!wordMap.has(normalized)) {
+        wordMap.set(normalized, []);
+      }
+      wordMap.get(normalized)!.push({ english: english.toLowerCase(), category: name });
+    }
+  }
+
+  // Find words with multiple mappings
+  for (const [localeWord, mappings] of wordMap) {
+    if (mappings.length > 1) {
+      // Check if they map to different English words
+      const uniqueEnglish = new Set(mappings.map(m => m.english));
+      if (uniqueEnglish.size > 1) {
+        conflicts.push({ localeWord, mappings });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+describe('Dictionary Conflict Analysis', () => {
+  describe('Spanish (es)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(es, 'es');
+      console.log('\n=== Spanish Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // Known conflicts: 'en' (on/in/into), 'de' (from/of)
+      // These are handled by priority - commands win
+      expect(conflicts.length).toBeGreaterThan(0);
+
+      // Verify 'en' conflict exists
+      const enConflict = conflicts.find(c => c.localeWord === 'en');
+      expect(enConflict).toBeDefined();
+    });
+  });
+
+  describe('Japanese (ja)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(ja, 'ja');
+      console.log('\n=== Japanese Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // Document any conflicts found
+      if (conflicts.length === 0) {
+        console.log('  No conflicts found!');
+      }
+    });
+  });
+
+  describe('French (fr)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(fr, 'fr');
+      console.log('\n=== French Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // 'à' maps to both 'to' and 'at', 'de' maps to 'from' and 'of'
+      const aConflict = conflicts.find(c => c.localeWord === 'à');
+      expect(aConflict).toBeDefined();
+    });
+  });
+
+  describe('German (de)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(de, 'de');
+      console.log('\n=== German Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // Document any conflicts
+      if (conflicts.length === 0) {
+        console.log('  No conflicts found!');
+      }
+    });
+  });
+
+  describe('Arabic (ar)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(ar, 'ar');
+      console.log('\n=== Arabic Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // Document any conflicts
+      if (conflicts.length === 0) {
+        console.log('  No conflicts found!');
+      }
+    });
+  });
+
+  describe('Korean (ko)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(ko, 'ko');
+      console.log('\n=== Korean Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // Korean has notable conflicts: '에' (on/to/at), '동안' (for/while), '아니면' (unless/else)
+      const aeConflict = conflicts.find(c => c.localeWord === '에');
+      expect(aeConflict).toBeDefined();
+    });
+  });
+
+  describe('Chinese (zh)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(zh, 'zh');
+      console.log('\n=== Chinese Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // Chinese has notable conflicts: '当' (on/while), '获取' (take/get/fetch)
+      const dangConflict = conflicts.find(c => c.localeWord === '当');
+      expect(dangConflict).toBeDefined();
+    });
+  });
+
+  describe('Turkish (tr)', () => {
+    it('should identify conflicts', () => {
+      const conflicts = analyzeConflicts(tr, 'tr');
+      console.log('\n=== Turkish Conflicts ===');
+      for (const c of conflicts) {
+        console.log(`  '${c.localeWord}' maps to:`);
+        for (const m of c.mappings) {
+          console.log(`    - '${m.english}' (${m.category})`);
+        }
+      }
+
+      // Document any conflicts
+      if (conflicts.length === 0) {
+        console.log('  No conflicts found!');
+      }
+    });
+  });
+
+  describe('Priority Resolution', () => {
+    it('should explain how conflicts are resolved', () => {
+      // This test documents the priority system
+      console.log('\n=== Conflict Resolution Strategy ===');
+      console.log('Priority order (highest to lowest):');
+      console.log('  1. commands - core actions like toggle, put, set');
+      console.log('  2. logical - operators like and, or, then, else');
+      console.log('  3. events - DOM events like click, focus');
+      console.log('  4. values - literals like true, false, me, it');
+      console.log('  5. temporal - time units like seconds, ms');
+      console.log('  6. modifiers - prepositions like to, from, with');
+      console.log('  7. attributes - DOM properties like class, style');
+      console.log('\nExample: Spanish "en" maps to both "on" (command) and "in" (modifier)');
+      console.log('  → Resolution: "en" resolves to "on" because commands have priority');
+      expect(true).toBe(true);
+    });
+  });
+});

package/src/parser/ar.ts

@@ -0,0 +1,40 @@
+// packages/i18n/src/parser/ar.ts
+
+import { ar } from '../dictionaries/ar';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * Arabic keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in Arabic:
+ * - `على نقر بدل .active` → parses as `on click toggle .active`
+ * - `إذا صحيح ثم سجل "مرحبا"` → parses as `if true then log "hello"`
+ *
+ * English keywords are also accepted (mixed mode), so:
+ * - `على click بدل .active` also works (Arabic `على` + English `click`)
+ *
+ * Arabic is a crucial test case because:
+ * - Right-to-left (RTL) script
+ * - Different character set (Unicode Arabic block)
+ * - Space-separated words with diacritics
+ * - Tests parser's Unicode handling robustly
+ *
+ * Note: The parser handles RTL text correctly because tokenization
+ * is based on whitespace/operator boundaries, not visual direction.
+ *
+ * @example
+ * ```typescript
+ * import { arKeywords } from '@lokascript/i18n/parser/ar';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: arKeywords });
+ * parser.parse('على نقر بدل .active');
+ * ```
+ */
+export const arKeywords: KeywordProvider = createKeywordProvider(ar, 'ar', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { ar as arDictionary } from '../dictionaries/ar';

package/src/parser/create-provider.ts

@@ -0,0 +1,309 @@
+// packages/i18n/src/parser/create-provider.ts
+
+import type { Dictionary } from '../types';
+import type { KeywordProvider, KeywordProviderOptions } from './types';
+import {
+  ENGLISH_COMMANDS,
+  ENGLISH_KEYWORDS,
+  ENGLISH_MODIFIERS,
+  ENGLISH_LOGICAL_KEYWORDS,
+  ENGLISH_VALUE_KEYWORDS,
+  ENGLISH_EXPRESSION_KEYWORDS,
+  UNIVERSAL_ENGLISH_KEYWORDS,
+} from '../constants';
+
+/**
+ * Creates a KeywordProvider from a dictionary.
+ *
+ * The provider creates reverse mappings (locale → English) for fast
+ * resolution during parsing.
+ *
+ * @example
+ * ```typescript
+ * import { es } from '../dictionaries/es';
+ * export const esKeywords = createKeywordProvider(es, 'es');
+ * ```
+ */
+export function createKeywordProvider(
+  dictionary: Dictionary,
+  locale: string,
+  options: KeywordProviderOptions = {}
+): KeywordProvider {
+  const { allowEnglishFallback = true } = options;
+
+  // Build reverse maps: locale keyword → English canonical
+  const reverseCommands = new Map<string, string>();
+  const reverseModifiers = new Map<string, string>();
+  const reverseEvents = new Map<string, string>();
+  const reverseLogical = new Map<string, string>();
+  const reverseTemporal = new Map<string, string>();
+  const reverseValues = new Map<string, string>();
+  const reverseAttributes = new Map<string, string>();
+  const reverseExpressions = new Map<string, string>();
+  const reverseAll = new Map<string, string>();
+
+  // Forward maps: English → locale keyword
+  const forwardAll = new Map<string, string>();
+
+  // Build reverse mappings from dictionary
+  // Note: reverseAll uses priority - first category to claim a locale word wins
+  function buildReverseMap(
+    category: Record<string, string>,
+    reverseMap: Map<string, string>,
+    priority: boolean = false
+  ): void {
+    for (const [english, localeWord] of Object.entries(category)) {
+      const normalizedLocale = localeWord.toLowerCase();
+      reverseMap.set(normalizedLocale, english.toLowerCase());
+      // Only set in reverseAll if not already claimed (priority) or if this is a priority category
+      if (priority || !reverseAll.has(normalizedLocale)) {
+        reverseAll.set(normalizedLocale, english.toLowerCase());
+      }
+      forwardAll.set(english.toLowerCase(), localeWord.toLowerCase());
+    }
+  }
+
+  // Build all reverse maps
+  // Priority order: commands first (highest priority for parsing), then logical, events, values
+  // This ensures 'en' (Spanish) → 'on' (command) rather than 'in' (modifier)
+  if (dictionary.commands) {
+    buildReverseMap(dictionary.commands, reverseCommands, true);
+  }
+  if (dictionary.logical) {
+    buildReverseMap(dictionary.logical, reverseLogical, true);
+  }
+  if (dictionary.events) {
+    buildReverseMap(dictionary.events, reverseEvents);
+  }
+  if (dictionary.values) {
+    buildReverseMap(dictionary.values, reverseValues);
+  }
+  if (dictionary.temporal) {
+    buildReverseMap(dictionary.temporal, reverseTemporal);
+  }
+  // Modifiers last (lowest priority) - they often conflict with commands
+  if (dictionary.modifiers) {
+    buildReverseMap(dictionary.modifiers, reverseModifiers);
+  }
+  if (dictionary.attributes) {
+    buildReverseMap(dictionary.attributes, reverseAttributes);
+  }
+  if (dictionary.expressions) {
+    buildReverseMap(dictionary.expressions, reverseExpressions);
+  }
+
+  // Collect all locale commands and keywords for completions
+  const localeCommands = new Set(reverseCommands.keys());
+  const allLocaleKeywords = new Set(reverseAll.keys());
+
+  // Add English keywords/commands if fallback is enabled
+  if (allowEnglishFallback) {
+    for (const cmd of ENGLISH_COMMANDS) {
+      localeCommands.add(cmd);
+    }
+    for (const kw of ENGLISH_KEYWORDS) {
+      allLocaleKeywords.add(kw);
+    }
+    for (const kw of UNIVERSAL_ENGLISH_KEYWORDS) {
+      allLocaleKeywords.add(kw);
+    }
+  }
+
+  return {
+    locale,
+
+    resolve(token: string): string | undefined {
+      const normalized = token.toLowerCase();
+
+      // Check if it's a locale keyword
+      const english = reverseAll.get(normalized);
+      if (english !== undefined) {
+        return english;
+      }
+
+      // If English fallback is enabled, check if it's already English
+      if (allowEnglishFallback) {
+        if (ENGLISH_COMMANDS.has(normalized) || ENGLISH_KEYWORDS.has(normalized)) {
+          return normalized;
+        }
+        // Universal keywords (DOM events, etc.) pass through
+        if (UNIVERSAL_ENGLISH_KEYWORDS.has(normalized)) {
+          return normalized;
+        }
+      }
+
+      return undefined;
+    },
+
+    isCommand(token: string): boolean {
+      const normalized = token.toLowerCase();
+
+      // Check locale commands
+      if (reverseCommands.has(normalized)) {
+        return true;
+      }
+
+      // Check English commands if fallback enabled
+      if (allowEnglishFallback && ENGLISH_COMMANDS.has(normalized)) {
+        return true;
+      }
+
+      return false;
+    },
+
+    isKeyword(token: string): boolean {
+      const normalized = token.toLowerCase();
+
+      // Check locale keywords (modifiers, logical, temporal, values)
+      if (
+        reverseModifiers.has(normalized) ||
+        reverseLogical.has(normalized) ||
+        reverseTemporal.has(normalized) ||
+        reverseValues.has(normalized)
+      ) {
+        return true;
+      }
+
+      // Check English keywords if fallback enabled
+      if (allowEnglishFallback && ENGLISH_KEYWORDS.has(normalized)) {
+        return true;
+      }
+
+      return false;
+    },
+
+    isEvent(token: string): boolean {
+      const normalized = token.toLowerCase();
+
+      // Check locale events
+      if (reverseEvents.has(normalized)) {
+        return true;
+      }
+
+      // Universal English events always accepted
+      if (UNIVERSAL_ENGLISH_KEYWORDS.has(normalized)) {
+        return true;
+      }
+
+      return false;
+    },
+
+    isModifier(token: string): boolean {
+      const normalized = token.toLowerCase();
+      return (
+        reverseModifiers.has(normalized) ||
+        (allowEnglishFallback && ENGLISH_MODIFIERS.has(normalized))
+      );
+    },
+
+    isLogical(token: string): boolean {
+      const normalized = token.toLowerCase();
+      return (
+        reverseLogical.has(normalized) ||
+        (allowEnglishFallback && ENGLISH_LOGICAL_KEYWORDS.has(normalized))
+      );
+    },
+
+    isValue(token: string): boolean {
+      const normalized = token.toLowerCase();
+      return (
+        reverseValues.has(normalized) ||
+        (allowEnglishFallback && ENGLISH_VALUE_KEYWORDS.has(normalized))
+      );
+    },
+
+    isExpression(token: string): boolean {
+      const normalized = token.toLowerCase();
+      return (
+        reverseExpressions.has(normalized) ||
+        (allowEnglishFallback && ENGLISH_EXPRESSION_KEYWORDS.has(normalized))
+      );
+    },
+
+    getCommands(): string[] {
+      return Array.from(localeCommands);
+    },
+
+    getKeywords(): string[] {
+      return Array.from(allLocaleKeywords);
+    },
+
+    toLocale(englishKeyword: string): string | undefined {
+      return forwardAll.get(englishKeyword.toLowerCase());
+    },
+  };
+}
+
+/**
+ * Creates a default English-only keyword provider.
+ * This is used when no locale is specified.
+ */
+export function createEnglishProvider(): KeywordProvider {
+  return {
+    locale: 'en',
+
+    resolve(token: string): string | undefined {
+      const normalized = token.toLowerCase();
+      if (
+        ENGLISH_COMMANDS.has(normalized) ||
+        ENGLISH_KEYWORDS.has(normalized) ||
+        UNIVERSAL_ENGLISH_KEYWORDS.has(normalized)
+      ) {
+        return normalized;
+      }
+      return undefined;
+    },
+
+    isCommand(token: string): boolean {
+      return ENGLISH_COMMANDS.has(token.toLowerCase());
+    },
+
+    isKeyword(token: string): boolean {
+      return ENGLISH_KEYWORDS.has(token.toLowerCase());
+    },
+
+    isEvent(token: string): boolean {
+      return UNIVERSAL_ENGLISH_KEYWORDS.has(token.toLowerCase());
+    },
+
+    isModifier(token: string): boolean {
+      return ENGLISH_MODIFIERS.has(token.toLowerCase());
+    },
+
+    isLogical(token: string): boolean {
+      return ENGLISH_LOGICAL_KEYWORDS.has(token.toLowerCase());
+    },
+
+    isValue(token: string): boolean {
+      return ENGLISH_VALUE_KEYWORDS.has(token.toLowerCase());
+    },
+
+    isExpression(token: string): boolean {
+      return ENGLISH_EXPRESSION_KEYWORDS.has(token.toLowerCase());
+    },
+
+    getCommands(): string[] {
+      return Array.from(ENGLISH_COMMANDS);
+    },
+
+    getKeywords(): string[] {
+      return Array.from(ENGLISH_KEYWORDS);
+    },
+
+    toLocale(_englishKeyword: string): string | undefined {
+      // English provider returns the keyword as-is
+      return _englishKeyword.toLowerCase();
+    },
+  };
+}
+
+// Re-export the English keyword sets from constants for use in core
+export {
+  ENGLISH_COMMANDS,
+  ENGLISH_KEYWORDS,
+  ENGLISH_MODIFIERS,
+  ENGLISH_LOGICAL_KEYWORDS,
+  ENGLISH_VALUE_KEYWORDS,
+  ENGLISH_EXPRESSION_KEYWORDS,
+  UNIVERSAL_ENGLISH_KEYWORDS,
+} from '../constants';

package/src/parser/de.ts

@@ -0,0 +1,36 @@
+// packages/i18n/src/parser/de.ts
+
+import { de } from '../dictionaries/de';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * German keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in German:
+ * - `bei klick umschalten .active` → parses as `on click toggle .active`
+ * - `wenn wahr dann protokollieren "hallo"` → parses as `if true then log "hello"`
+ *
+ * English keywords are also accepted (mixed mode), so:
+ * - `bei click umschalten .active` also works (German `bei` + English `click`)
+ *
+ * German is a useful test case because:
+ * - Compound words (Zusammensetzungen) are common
+ * - Different word order in clauses (V2 in main, V-final in subordinate)
+ * - Case system (nominative, accusative, dative, genitive)
+ *
+ * @example
+ * ```typescript
+ * import { deKeywords } from '@lokascript/i18n/parser/de';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: deKeywords });
+ * parser.parse('bei klick umschalten .active');
+ * ```
+ */
+export const deKeywords: KeywordProvider = createKeywordProvider(de, 'de', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { de as deDictionary } from '../dictionaries/de';

package/src/parser/es.ts

@@ -0,0 +1,31 @@
+// packages/i18n/src/parser/es.ts
+
+import { es } from '../dictionaries/es';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * Spanish keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in Spanish:
+ * - `en clic alternar .active` → parses as `on click toggle .active`
+ * - `si verdadero entonces registrar "hola"` → parses as `if true then log "hello"`
+ *
+ * English keywords are also accepted (mixed mode), so:
+ * - `en click alternar .active` also works (Spanish `en` + English `click`)
+ *
+ * @example
+ * ```typescript
+ * import { esKeywords } from '@lokascript/i18n/parser/es';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: esKeywords });
+ * parser.parse('en clic alternar .active');
+ * ```
+ */
+export const esKeywords: KeywordProvider = createKeywordProvider(es, 'es', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { es as esDictionary } from '../dictionaries/es';

package/src/parser/fr.ts

@@ -0,0 +1,31 @@
+// packages/i18n/src/parser/fr.ts
+
+import { fr } from '../dictionaries/fr';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * French keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in French:
+ * - `sur clic basculer .active` → parses as `on click toggle .active`
+ * - `si vrai alors enregistrer "bonjour"` → parses as `if true then log "hello"`
+ *
+ * English keywords are also accepted (mixed mode), so:
+ * - `sur click basculer .active` also works (French `sur` + English `click`)
+ *
+ * @example
+ * ```typescript
+ * import { frKeywords } from '@lokascript/i18n/parser/fr';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: frKeywords });
+ * parser.parse('sur clic basculer .active');
+ * ```
+ */
+export const frKeywords: KeywordProvider = createKeywordProvider(fr, 'fr', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { fr as frDictionary } from '../dictionaries/fr';