@lokascript/i18n 1.0.0

package/src/parser/id.ts

@@ -0,0 +1,34 @@
+// packages/i18n/src/parser/id.ts
+
+import { id } from '../dictionaries/id';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * Indonesian (Bahasa Indonesia) keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in Indonesian:
+ * - `pada klik ganti .active` → parses as `on click toggle .active`
+ * - `jika benar lalu log "Halo"` → parses as `if true then log "Hello"`
+ *
+ * Indonesian is an SVO language with:
+ * - Agglutinative morphology (prefixes/suffixes)
+ * - No grammatical gender
+ * - Prepositions (like English)
+ * - Relatively simple syntax
+ *
+ * @example
+ * ```typescript
+ * import { idKeywords } from '@lokascript/i18n/parser/id';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: idKeywords });
+ * parser.parse('pada klik ganti .active');
+ * ```
+ */
+export const idKeywords: KeywordProvider = createKeywordProvider(id, 'id', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { id as idDictionary } from '../dictionaries/id';

package/src/parser/index.ts

@@ -0,0 +1,50 @@
+// packages/i18n/src/parser/index.ts
+
+/**
+ * Parser integration for multilingual hyperscript.
+ *
+ * This module provides KeywordProvider implementations that enable
+ * the hyperscript parser to understand non-English keywords.
+ *
+ * @example
+ * ```typescript
+ * // Spanish
+ * import { esKeywords } from '@lokascript/i18n/parser';
+ * const parser = new Parser({ keywords: esKeywords });
+ * parser.parse('en clic alternar .active');
+ *
+ * // Japanese
+ * import { jaKeywords } from '@lokascript/i18n/parser';
+ * const parser = new Parser({ keywords: jaKeywords });
+ * parser.parse('クリック で 切り替え .active');
+ *
+ * // Custom locale
+ * import { createKeywordProvider } from '@lokascript/i18n/parser';
+ * import { fr } from '@lokascript/i18n/dictionaries';
+ * const frKeywords = createKeywordProvider(fr, 'fr');
+ * ```
+ */
+
+// Types
+export type { KeywordProvider, KeywordProviderOptions } from './types';
+
+// Factory
+export { createKeywordProvider, createEnglishProvider } from './create-provider';
+export { ENGLISH_COMMANDS, ENGLISH_KEYWORDS, UNIVERSAL_ENGLISH_KEYWORDS } from './create-provider';
+
+// Locale packs
+export { esKeywords, esDictionary } from './es';
+export { jaKeywords, jaDictionary } from './ja';
+export { frKeywords, frDictionary } from './fr';
+export { deKeywords, deDictionary } from './de';
+export { arKeywords, arDictionary } from './ar';
+export { koKeywords, koDictionary } from './ko';
+export { zhKeywords, zhDictionary } from './zh';
+export { trKeywords, trDictionary } from './tr';
+export { idKeywords, idDictionary } from './id';
+export { quKeywords, quDictionary } from './qu';
+export { swKeywords, swDictionary } from './sw';
+export { ptKeywords, ptDictionary } from './pt';
+
+// Locale management
+export { LocaleManager, detectBrowserLocale } from './locale-manager';

package/src/parser/ja.ts

@@ -0,0 +1,36 @@
+// packages/i18n/src/parser/ja.ts
+
+import { ja } from '../dictionaries/ja';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * Japanese keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in Japanese:
+ * - `クリック で 切り替え .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 (English `click` + Japanese `で`, `切り替え`)
+ *
+ * Japanese is a useful test case because:
+ * - SOV word order (subject-object-verb) vs English SVO
+ * - No articles (a, an, the)
+ * - Unicode characters (tests tokenizer robustness)
+ *
+ * @example
+ * ```typescript
+ * import { jaKeywords } from '@lokascript/i18n/parser/ja';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: jaKeywords });
+ * parser.parse('クリック で 切り替え .active');
+ * ```
+ */
+export const jaKeywords: KeywordProvider = createKeywordProvider(ja, 'ja', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { ja as jaDictionary } from '../dictionaries/ja';

package/src/parser/ko.ts

@@ -0,0 +1,37 @@
+// packages/i18n/src/parser/ko.ts
+
+import { ko } from '../dictionaries/ko';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * Korean keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in Korean:
+ * - `에 클릭 토글 .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 (Korean `에` + English `click`)
+ *
+ * Korean is a useful test case because:
+ * - SOV word order (Subject-Object-Verb)
+ * - Hangul script (syllabic blocks)
+ * - Agglutinative morphology with particles
+ * - Tests parser's Unicode handling with Korean characters
+ *
+ * @example
+ * ```typescript
+ * import { koKeywords } from '@lokascript/i18n/parser/ko';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: koKeywords });
+ * parser.parse('에 클릭 토글 .active');
+ * ```
+ */
+export const koKeywords: KeywordProvider = createKeywordProvider(ko, 'ko', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { ko as koDictionary } from '../dictionaries/ko';

package/src/parser/locale-manager.test.ts

@@ -0,0 +1,198 @@
+// packages/i18n/src/parser/locale-manager.test.ts
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { LocaleManager, detectBrowserLocale } from './locale-manager';
+import { esKeywords } from './es';
+import { jaKeywords } from './ja';
+import { frKeywords } from './fr';
+import { deKeywords } from './de';
+import { arKeywords } from './ar';
+
+describe('LocaleManager', () => {
+  beforeEach(() => {
+    LocaleManager.reset();
+  });
+
+  describe('register / unregister', () => {
+    it('should register a locale provider', () => {
+      LocaleManager.register('es', esKeywords);
+      expect(LocaleManager.has('es')).toBe(true);
+    });
+
+    it('should unregister a locale provider', () => {
+      LocaleManager.register('es', esKeywords);
+      LocaleManager.unregister('es');
+      expect(LocaleManager.has('es')).toBe(false);
+    });
+
+    it('should handle case-insensitive locale codes', () => {
+      LocaleManager.register('ES', esKeywords);
+      expect(LocaleManager.has('es')).toBe(true);
+      expect(LocaleManager.has('ES')).toBe(true);
+    });
+  });
+
+  describe('setDefault / getDefault', () => {
+    it('should have en as default initially', () => {
+      expect(LocaleManager.getDefault()).toBe('en');
+    });
+
+    it('should set default locale', () => {
+      LocaleManager.register('es', esKeywords);
+      LocaleManager.setDefault('es');
+      expect(LocaleManager.getDefault()).toBe('es');
+    });
+
+    it('should throw when setting unregistered locale as default', () => {
+      expect(() => LocaleManager.setDefault('xyz')).toThrow("Locale 'xyz' is not registered");
+    });
+
+    it('should allow setting en as default without registration', () => {
+      LocaleManager.setDefault('en');
+      expect(LocaleManager.getDefault()).toBe('en');
+    });
+  });
+
+  describe('get', () => {
+    it('should get English provider by default', () => {
+      const provider = LocaleManager.get();
+      expect(provider.locale).toBe('en');
+    });
+
+    it('should get registered locale provider', () => {
+      LocaleManager.register('es', esKeywords);
+      const provider = LocaleManager.get('es');
+      expect(provider.locale).toBe('es');
+    });
+
+    it('should get default locale when no argument provided', () => {
+      LocaleManager.register('ja', jaKeywords);
+      LocaleManager.setDefault('ja');
+      const provider = LocaleManager.get();
+      expect(provider.locale).toBe('ja');
+    });
+
+    it('should throw for unregistered locale', () => {
+      expect(() => LocaleManager.get('xyz')).toThrow("Locale 'xyz' is not registered");
+    });
+  });
+
+  describe('has', () => {
+    it('should always have en', () => {
+      expect(LocaleManager.has('en')).toBe(true);
+    });
+
+    it('should return false for unregistered locale', () => {
+      expect(LocaleManager.has('xyz')).toBe(false);
+    });
+
+    it('should return true for registered locale', () => {
+      LocaleManager.register('fr', frKeywords);
+      expect(LocaleManager.has('fr')).toBe(true);
+    });
+  });
+
+  describe('getAvailable', () => {
+    it('should include en by default', () => {
+      expect(LocaleManager.getAvailable()).toContain('en');
+    });
+
+    it('should include registered locales', () => {
+      LocaleManager.register('es', esKeywords);
+      LocaleManager.register('ja', jaKeywords);
+      const available = LocaleManager.getAvailable();
+      expect(available).toContain('en');
+      expect(available).toContain('es');
+      expect(available).toContain('ja');
+    });
+  });
+
+  describe('registerAll', () => {
+    it('should register multiple locales at once', () => {
+      LocaleManager.registerAll({
+        es: esKeywords,
+        ja: jaKeywords,
+        fr: frKeywords,
+        de: deKeywords,
+        ar: arKeywords,
+      });
+
+      expect(LocaleManager.has('es')).toBe(true);
+      expect(LocaleManager.has('ja')).toBe(true);
+      expect(LocaleManager.has('fr')).toBe(true);
+      expect(LocaleManager.has('de')).toBe(true);
+      expect(LocaleManager.has('ar')).toBe(true);
+    });
+  });
+
+  describe('reset', () => {
+    it('should clear all registered locales and reset default', () => {
+      LocaleManager.register('es', esKeywords);
+      LocaleManager.setDefault('es');
+
+      LocaleManager.reset();
+
+      expect(LocaleManager.has('es')).toBe(false);
+      expect(LocaleManager.getDefault()).toBe('en');
+    });
+  });
+
+  describe('Integration: keyword resolution', () => {
+    beforeEach(() => {
+      LocaleManager.registerAll({
+        es: esKeywords,
+        ja: jaKeywords,
+        fr: frKeywords,
+      });
+    });
+
+    it('should resolve keywords for different locales', () => {
+      // Spanish
+      const es = LocaleManager.get('es');
+      expect(es.resolve('alternar')).toBe('toggle');
+
+      // Japanese
+      const ja = LocaleManager.get('ja');
+      expect(ja.resolve('切り替え')).toBe('toggle');
+
+      // French
+      const fr = LocaleManager.get('fr');
+      expect(fr.resolve('basculer')).toBe('toggle');
+
+      // English
+      const en = LocaleManager.get('en');
+      expect(en.resolve('toggle')).toBe('toggle');
+    });
+
+    it('should support switching default locale dynamically', () => {
+      // Start with English
+      expect(LocaleManager.get().resolve('toggle')).toBe('toggle');
+
+      // Switch to Spanish
+      LocaleManager.setDefault('es');
+      expect(LocaleManager.get().resolve('alternar')).toBe('toggle');
+
+      // Switch to Japanese
+      LocaleManager.setDefault('ja');
+      expect(LocaleManager.get().resolve('切り替え')).toBe('toggle');
+    });
+  });
+});
+
+describe('detectBrowserLocale', () => {
+  beforeEach(() => {
+    LocaleManager.reset();
+  });
+
+  it('should return English provider when navigator is undefined', () => {
+    // In Node.js environment, navigator is undefined
+    const provider = detectBrowserLocale();
+    expect(provider.locale).toBe('en');
+  });
+
+  it('should return English when no matching locale is registered', () => {
+    // No locales registered, should fall back to English
+    const provider = detectBrowserLocale();
+    expect(provider.locale).toBe('en');
+  });
+});

package/src/parser/locale-manager.ts

@@ -0,0 +1,197 @@
+// packages/i18n/src/parser/locale-manager.ts
+
+import type { KeywordProvider } from './types';
+import { createEnglishProvider } from './create-provider';
+
+/**
+ * LocaleManager - Centralized locale configuration for hyperscript parsing.
+ *
+ * Provides utilities for:
+ * - Setting/getting the default locale
+ * - Creating locale-aware parsers
+ * - Runtime locale switching
+ *
+ * @example
+ * ```typescript
+ * import { LocaleManager } from '@lokascript/i18n/parser';
+ * import { esKeywords, frKeywords } from '@lokascript/i18n/parser';
+ *
+ * // Register available locales
+ * LocaleManager.register('es', esKeywords);
+ * LocaleManager.register('fr', frKeywords);
+ *
+ * // Set default locale
+ * LocaleManager.setDefault('es');
+ *
+ * // Get keyword provider for parsing
+ * const provider = LocaleManager.get(); // Returns esKeywords
+ * const frProvider = LocaleManager.get('fr'); // Returns frKeywords
+ *
+ * // Use with parser
+ * const parser = new Parser({ keywords: LocaleManager.get() });
+ * ```
+ */
+export class LocaleManager {
+  private static providers = new Map<string, KeywordProvider>();
+  private static defaultLocale: string = 'en';
+  private static englishProvider: KeywordProvider = createEnglishProvider();
+
+  /**
+   * Register a locale provider.
+   *
+   * @param locale - The locale code (e.g., 'es', 'ja', 'fr')
+   * @param provider - The KeywordProvider for this locale
+   */
+  static register(locale: string, provider: KeywordProvider): void {
+    LocaleManager.providers.set(locale.toLowerCase(), provider);
+  }
+
+  /**
+   * Unregister a locale provider.
+   *
+   * @param locale - The locale code to remove
+   */
+  static unregister(locale: string): void {
+    LocaleManager.providers.delete(locale.toLowerCase());
+  }
+
+  /**
+   * Set the default locale.
+   *
+   * @param locale - The locale code to use as default
+   * @throws Error if the locale is not registered
+   */
+  static setDefault(locale: string): void {
+    const normalizedLocale = locale.toLowerCase();
+    if (normalizedLocale !== 'en' && !LocaleManager.providers.has(normalizedLocale)) {
+      throw new Error(
+        `Locale '${locale}' is not registered. ` +
+          `Available locales: ${LocaleManager.getAvailable().join(', ')}`
+      );
+    }
+    LocaleManager.defaultLocale = normalizedLocale;
+  }
+
+  /**
+   * Get the current default locale.
+   *
+   * @returns The default locale code
+   */
+  static getDefault(): string {
+    return LocaleManager.defaultLocale;
+  }
+
+  /**
+   * Get a keyword provider for a locale.
+   *
+   * @param locale - The locale code (optional, defaults to the default locale)
+   * @returns The KeywordProvider for the locale
+   * @throws Error if the locale is not registered
+   */
+  static get(locale?: string): KeywordProvider {
+    const targetLocale = (locale || LocaleManager.defaultLocale).toLowerCase();
+
+    // English is always available
+    if (targetLocale === 'en') {
+      return LocaleManager.englishProvider;
+    }
+
+    const provider = LocaleManager.providers.get(targetLocale);
+    if (!provider) {
+      throw new Error(
+        `Locale '${targetLocale}' is not registered. ` +
+          `Available locales: ${LocaleManager.getAvailable().join(', ')}`
+      );
+    }
+
+    return provider;
+  }
+
+  /**
+   * Check if a locale is registered.
+   *
+   * @param locale - The locale code to check
+   * @returns True if the locale is available
+   */
+  static has(locale: string): boolean {
+    const normalizedLocale = locale.toLowerCase();
+    return normalizedLocale === 'en' || LocaleManager.providers.has(normalizedLocale);
+  }
+
+  /**
+   * Get all available locale codes.
+   *
+   * @returns Array of locale codes
+   */
+  static getAvailable(): string[] {
+    return ['en', ...Array.from(LocaleManager.providers.keys())];
+  }
+
+  /**
+   * Reset the LocaleManager to its initial state.
+   * Useful for testing.
+   */
+  static reset(): void {
+    LocaleManager.providers.clear();
+    LocaleManager.defaultLocale = 'en';
+  }
+
+  /**
+   * Register all built-in locales at once.
+   *
+   * @example
+   * ```typescript
+   * import { LocaleManager } from '@lokascript/i18n/parser';
+   * import { esKeywords, jaKeywords, frKeywords, deKeywords, arKeywords } from '@lokascript/i18n/parser';
+   *
+   * LocaleManager.registerAll({
+   *   es: esKeywords,
+   *   ja: jaKeywords,
+   *   fr: frKeywords,
+   *   de: deKeywords,
+   *   ar: arKeywords,
+   * });
+   * ```
+   */
+  static registerAll(providers: Record<string, KeywordProvider>): void {
+    for (const [locale, provider] of Object.entries(providers)) {
+      LocaleManager.register(locale, provider);
+    }
+  }
+}
+
+/**
+ * Quick utility to detect the browser's preferred locale and return
+ * a matching provider, falling back to English.
+ *
+ * @returns The KeywordProvider for the browser's locale or English
+ *
+ * @example
+ * ```typescript
+ * import { detectBrowserLocale } from '@lokascript/i18n/parser';
+ * import { Parser } from '@lokascript/core';
+ *
+ * // Auto-detect and use browser locale
+ * const parser = new Parser({ keywords: detectBrowserLocale() });
+ * ```
+ */
+export function detectBrowserLocale(): KeywordProvider {
+  if (typeof navigator === 'undefined') {
+    return LocaleManager.get('en');
+  }
+
+  // Get browser languages in order of preference
+  const languages = navigator.languages || [navigator.language];
+
+  for (const lang of languages) {
+    // Extract the base language code (e.g., 'es-MX' -> 'es')
+    const baseLocale = lang.split('-')[0].toLowerCase();
+
+    if (LocaleManager.has(baseLocale)) {
+      return LocaleManager.get(baseLocale);
+    }
+  }
+
+  // Fallback to English
+  return LocaleManager.get('en');
+}