@lokascript/i18n 1.0.0

package/src/parser/types.ts

@@ -0,0 +1,113 @@
+// packages/i18n/src/parser/types.ts
+
+/**
+ * KeywordProvider interface for locale-aware parsing.
+ *
+ * This interface allows the parser to resolve non-English keywords
+ * to their canonical English equivalents, enabling multilingual
+ * hyperscript syntax.
+ *
+ * @example
+ * ```typescript
+ * import { esKeywords } from '@lokascript/i18n/parser/es';
+ * const parser = new Parser({ keywords: esKeywords });
+ * parser.parse('en clic alternar .active'); // Works!
+ * ```
+ */
+export interface KeywordProvider {
+  /** The locale code for this provider (e.g., 'es', 'ja') */
+  readonly locale: string;
+
+  /**
+   * Resolve a token to its canonical (English) keyword.
+   * Returns undefined if the token is not a recognized keyword.
+   *
+   * @example
+   * esKeywords.resolve('alternar') // 'toggle'
+   * esKeywords.resolve('en')       // 'on'
+   * esKeywords.resolve('unknown')  // undefined
+   */
+  resolve(token: string): string | undefined;
+
+  /**
+   * Check if the token is a command in this locale.
+   * Includes both locale keywords and English fallbacks.
+   */
+  isCommand(token: string): boolean;
+
+  /**
+   * Check if the token is a keyword (non-command) in this locale.
+   * Includes modifiers, logical operators, events, etc.
+   */
+  isKeyword(token: string): boolean;
+
+  /**
+   * Check if the token is an event name in this locale.
+   */
+  isEvent(token: string): boolean;
+
+  /**
+   * Check if the token is a modifier/preposition in this locale.
+   */
+  isModifier(token: string): boolean;
+
+  /**
+   * Check if the token is a logical operator in this locale.
+   */
+  isLogical(token: string): boolean;
+
+  /**
+   * Check if the token is a value keyword (me, it, true, etc.) in this locale.
+   */
+  isValue(token: string): boolean;
+
+  /**
+   * Check if the token is an expression keyword (first, last, closest, etc.) in this locale.
+   */
+  isExpression(token: string): boolean;
+
+  /**
+   * Get all command names in this locale (for completions).
+   */
+  getCommands(): string[];
+
+  /**
+   * Get all keywords in this locale (for completions).
+   */
+  getKeywords(): string[];
+
+  /**
+   * Get the locale keyword for an English canonical keyword.
+   * Useful for error messages and IDE completions in native language.
+   *
+   * @example
+   * esKeywords.toLocale('toggle') // 'alternar'
+   */
+  toLocale(englishKeyword: string): string | undefined;
+}
+
+/**
+ * Options for creating a keyword provider.
+ */
+export interface KeywordProviderOptions {
+  /**
+   * When true, English keywords are always accepted alongside locale keywords.
+   * This allows mixing: "en click alternar .active"
+   * @default true
+   */
+  allowEnglishFallback?: boolean;
+
+  /**
+   * Categories to include. If not specified, all categories are included.
+   */
+  categories?: Array<
+    | 'commands'
+    | 'modifiers'
+    | 'events'
+    | 'logical'
+    | 'temporal'
+    | 'values'
+    | 'attributes'
+    | 'expressions'
+  >;
+}

package/src/parser/zh.ts

@@ -0,0 +1,38 @@
+// packages/i18n/src/parser/zh.ts
+
+import { zh } from '../dictionaries/zh';
+import { createKeywordProvider } from './create-provider';
+import type { KeywordProvider } from './types';
+
+/**
+ * Chinese (Simplified) keyword provider for the hyperscript parser.
+ *
+ * Enables parsing hyperscript written in Chinese:
+ * - `当 点击 切换 .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 (Chinese `当` + English `click`)
+ *
+ * Chinese is a useful test case because:
+ * - SVO word order (similar to English)
+ * - Logographic script (Chinese characters)
+ * - Isolating morphology (minimal inflection)
+ * - Tests parser's Unicode handling with CJK characters
+ * - Large developer population
+ *
+ * @example
+ * ```typescript
+ * import { zhKeywords } from '@lokascript/i18n/parser/zh';
+ * import { Parser } from '@lokascript/core';
+ *
+ * const parser = new Parser({ keywords: zhKeywords });
+ * parser.parse('当 点击 切换 .active');
+ * ```
+ */
+export const zhKeywords: KeywordProvider = createKeywordProvider(zh, 'zh', {
+  allowEnglishFallback: true,
+});
+
+// Re-export for convenience
+export { zh as zhDictionary } from '../dictionaries/zh';

package/src/plugins/vite.ts

@@ -0,0 +1,224 @@
+// packages/i18n/src/plugins/vite.ts
+
+import type { Plugin } from 'vite';
+import { HyperscriptTranslator } from '../translator';
+
+// node-html-parser is an optional dependency
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let parse: any;
+try {
+  // Dynamic require for optional dependency
+  parse = require('node-html-parser').parse;
+} catch {
+  parse = null;
+}
+
+export interface HyperscriptI18nViteOptions {
+  sourceLocale?: string;
+  targetLocale?: string;
+  preserveOriginal?: boolean;
+  attributes?: string[];
+  include?: RegExp | string[];
+  exclude?: RegExp | string[];
+}
+
+export function hyperscriptI18nVitePlugin(options: HyperscriptI18nViteOptions = {}): Plugin {
+  const {
+    sourceLocale = 'en',
+    targetLocale = 'en',
+    preserveOriginal = false,
+    attributes = ['_', 'script', 'data-script'],
+    include = /\.(html|vue|svelte)$/,
+    exclude = /node_modules/,
+  } = options;
+
+  const translator = new HyperscriptTranslator({ locale: sourceLocale });
+
+  return {
+    name: 'vite-plugin-hyperscript-i18n',
+
+    transform(code: string, id: string) {
+      // Check if file should be processed
+      if (!shouldProcess(id, include, exclude)) {
+        return null;
+      }
+
+      // Skip if no translation needed
+      if (sourceLocale === targetLocale) {
+        return null;
+      }
+
+      try {
+        // Process HTML files
+        if (id.endsWith('.html')) {
+          return transformHtml(code, translator, {
+            sourceLocale,
+            targetLocale,
+            preserveOriginal,
+            attributes,
+          });
+        }
+
+        // Process Vue SFCs
+        if (id.endsWith('.vue')) {
+          return transformVue(code, translator, {
+            sourceLocale,
+            targetLocale,
+            preserveOriginal,
+            attributes,
+          });
+        }
+
+        // Process Svelte components
+        if (id.endsWith('.svelte')) {
+          return transformSvelte(code, translator, {
+            sourceLocale,
+            targetLocale,
+            preserveOriginal,
+            attributes,
+          });
+        }
+
+        return null;
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.error(`Failed to process ${id}: ${message}`);
+      }
+    },
+
+    configureServer(server) {
+      // Add middleware for development
+      server.middlewares.use((_req, res, next) => {
+        // Add i18n headers
+        res.setHeader('X-Hyperscript-I18n-Source', sourceLocale);
+        res.setHeader('X-Hyperscript-I18n-Target', targetLocale);
+        next();
+      });
+    },
+  };
+}
+
+function shouldProcess(
+  id: string,
+  include: RegExp | string[],
+  exclude: RegExp | string[]
+): boolean {
+  const includePattern = Array.isArray(include) ? new RegExp(include.join('|')) : include;
+
+  const excludePattern = Array.isArray(exclude) ? new RegExp(exclude.join('|')) : exclude;
+
+  return includePattern.test(id) && !excludePattern.test(id);
+}
+
+function transformHtml(
+  html: string,
+  translator: HyperscriptTranslator,
+  options: {
+    sourceLocale: string;
+    targetLocale: string;
+    preserveOriginal: boolean;
+    attributes: string[];
+  }
+): { code: string; map?: any } {
+  const root = parse(html);
+  let hasTransformations = false;
+
+  // Find all elements with hyperscript attributes
+  options.attributes.forEach(attr => {
+    const elements = root.querySelectorAll(`[${attr}]`);
+
+    elements.forEach((element: any) => {
+      const original = element.getAttribute(attr);
+      if (!original) return;
+
+      const translated = translator.translate(original, {
+        from: options.sourceLocale,
+        to: options.targetLocale,
+      });
+
+      if (original !== translated) {
+        hasTransformations = true;
+
+        if (options.preserveOriginal) {
+          element.setAttribute(`${attr}-${options.sourceLocale}`, original);
+        }
+
+        element.setAttribute(attr, translated);
+      }
+    });
+  });
+
+  if (!hasTransformations) {
+    return { code: html };
+  }
+
+  return {
+    code: root.toString(),
+    map: null, // Source maps could be added here
+  };
+}
+
+function transformVue(
+  code: string,
+  translator: HyperscriptTranslator,
+  options: any
+): { code: string; map?: any } {
+  // Extract template section
+  const templateMatch = code.match(/<template[^>]*>([\s\S]*?)<\/template>/);
+  if (!templateMatch) {
+    return { code };
+  }
+
+  const template = templateMatch[1];
+  const transformed = transformHtml(template, translator, options);
+
+  if (transformed.code === template) {
+    return { code };
+  }
+
+  // Replace template content
+  const newCode = code.replace(templateMatch[0], `<template>${transformed.code}</template>`);
+
+  return { code: newCode };
+}
+
+function transformSvelte(
+  code: string,
+  translator: HyperscriptTranslator,
+  options: any
+): { code: string; map?: any } {
+  // Svelte components have HTML at the top level
+  const scriptMatch = code.match(/<script[^>]*>[\s\S]*?<\/script>/g);
+  const styleMatch = code.match(/<style[^>]*>[\s\S]*?<\/style>/g);
+
+  // Extract HTML portion
+  let html = code;
+  if (scriptMatch) {
+    scriptMatch.forEach(script => {
+      html = html.replace(script, '');
+    });
+  }
+  if (styleMatch) {
+    styleMatch.forEach(style => {
+      html = html.replace(style, '');
+    });
+  }
+
+  const transformed = transformHtml(html, translator, options);
+
+  if (transformed.code === html) {
+    return { code };
+  }
+
+  // Reconstruct Svelte component
+  let newCode = '';
+  if (scriptMatch) {
+    newCode += scriptMatch.join('\n') + '\n\n';
+  }
+  newCode += transformed.code;
+  if (styleMatch) {
+    newCode += '\n\n' + styleMatch.join('\n');
+  }
+
+  return { code: newCode };
+}

package/src/plugins/webpack.ts

@@ -0,0 +1,124 @@
+// packages/i18n/src/plugins/webpack.ts
+
+import { HyperscriptTranslator } from '../translator';
+
+// node-html-parser is an optional dependency
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let parse: any;
+try {
+  parse = require('node-html-parser').parse;
+} catch {
+  parse = null;
+}
+
+// Webpack types - optional peer dependency
+interface Compiler {
+  hooks: any;
+  webpack: any;
+}
+interface WebpackPluginInstance {
+  apply(compiler: Compiler): void;
+}
+
+export interface HyperscriptI18nWebpackOptions {
+  sourceLocale?: string;
+  targetLocale?: string;
+  preserveOriginal?: boolean;
+  attributes?: string[];
+  test?: RegExp;
+}
+
+export class HyperscriptI18nWebpackPlugin implements WebpackPluginInstance {
+  private options: Required<HyperscriptI18nWebpackOptions>;
+  private translator: HyperscriptTranslator;
+
+  constructor(options: HyperscriptI18nWebpackOptions = {}) {
+    this.options = {
+      sourceLocale: options.sourceLocale || 'en',
+      targetLocale: options.targetLocale || 'en',
+      preserveOriginal: options.preserveOriginal ?? false,
+      attributes: options.attributes || ['_', 'script', 'data-script'],
+      test: options.test || /\.(html)$/,
+    };
+
+    this.translator = new HyperscriptTranslator({
+      locale: this.options.sourceLocale,
+    });
+  }
+
+  apply(compiler: Compiler): void {
+    const pluginName = 'HyperscriptI18nWebpackPlugin';
+
+    // Skip if no translation needed
+    if (this.options.sourceLocale === this.options.targetLocale) {
+      return;
+    }
+
+    compiler.hooks.compilation.tap(pluginName, (compilation: any) => {
+      // Hook into HTML processing
+      compilation.hooks.processAssets.tapPromise(
+        {
+          name: pluginName,
+          stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE,
+        },
+        async (assets: any) => {
+          const promises = Object.keys(assets)
+            .filter(filename => this.options.test.test(filename))
+            .map(filename => this.processAsset(compilation, filename));
+
+          await Promise.all(promises);
+        }
+      );
+    });
+  }
+
+  private async processAsset(compilation: any, filename: string): Promise<void> {
+    const asset = compilation.assets[filename];
+    const source = asset.source();
+
+    try {
+      const processed = this.processHtml(source);
+
+      if (processed !== source) {
+        compilation.assets[filename] = {
+          source: () => processed,
+          size: () => processed.length,
+        };
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      compilation.errors.push(new Error(`Failed to process ${filename}: ${message}`));
+    }
+  }
+
+  private processHtml(html: string): string {
+    const root = parse(html);
+    let hasChanges = false;
+
+    this.options.attributes.forEach(attr => {
+      const elements = root.querySelectorAll(`[${attr}]`);
+
+      elements.forEach((element: any) => {
+        const original = element.getAttribute(attr);
+        if (!original) return;
+
+        const translated = this.translator.translate(original, {
+          from: this.options.sourceLocale,
+          to: this.options.targetLocale,
+        });
+
+        if (original !== translated) {
+          hasChanges = true;
+
+          if (this.options.preserveOriginal) {
+            element.setAttribute(`${attr}-${this.options.sourceLocale}`, original);
+          }
+
+          element.setAttribute(attr, translated);
+        }
+      });
+    });
+
+    return hasChanges ? root.toString() : html;
+  }
+}

package/src/pluralization.test.ts

@@ -0,0 +1,197 @@
+// packages/i18n/src/pluralization.test.ts
+
+import { describe, it, expect } from 'vitest';
+import { pluralRules, getPlural, PluralAwareTranslator } from './pluralization';
+
+describe('Pluralization', () => {
+  describe('plural rules', () => {
+    it('should handle English pluralization', () => {
+      expect(pluralRules.en(1)).toBe('one');
+      expect(pluralRules.en(0)).toBe('other');
+      expect(pluralRules.en(2)).toBe('other');
+      expect(pluralRules.en(5)).toBe('other');
+    });
+
+    it('should handle French pluralization', () => {
+      expect(pluralRules.fr(0)).toBe('one');
+      expect(pluralRules.fr(1)).toBe('one');
+      expect(pluralRules.fr(1.5)).toBe('one');
+      expect(pluralRules.fr(2)).toBe('other');
+      expect(pluralRules.fr(5)).toBe('other');
+    });
+
+    it('should handle Russian pluralization (complex)', () => {
+      expect(pluralRules.ru(1)).toBe('one');
+      expect(pluralRules.ru(21)).toBe('one');
+      expect(pluralRules.ru(2)).toBe('few');
+      expect(pluralRules.ru(3)).toBe('few');
+      expect(pluralRules.ru(4)).toBe('few');
+      expect(pluralRules.ru(22)).toBe('few');
+      expect(pluralRules.ru(5)).toBe('many');
+      expect(pluralRules.ru(11)).toBe('many');
+      expect(pluralRules.ru(15)).toBe('many');
+    });
+
+    it('should handle Arabic pluralization (with zero)', () => {
+      expect(pluralRules.ar(0)).toBe('zero');
+      expect(pluralRules.ar(1)).toBe('one');
+      expect(pluralRules.ar(2)).toBe('two');
+      expect(pluralRules.ar(3)).toBe('few');
+      expect(pluralRules.ar(10)).toBe('few');
+      expect(pluralRules.ar(11)).toBe('many');
+      expect(pluralRules.ar(99)).toBe('many');
+      expect(pluralRules.ar(100)).toBe('other');
+    });
+
+    it('should handle Chinese (no pluralization)', () => {
+      expect(pluralRules.zh(0)).toBe('other');
+      expect(pluralRules.zh(1)).toBe('other');
+      expect(pluralRules.zh(2)).toBe('other');
+      expect(pluralRules.zh(100)).toBe('other');
+    });
+  });
+
+  describe('getPlural', () => {
+    it('should return correct plural form for English', () => {
+      const forms = {
+        one: 'second',
+        other: 'seconds',
+      };
+
+      expect(getPlural('en', 1, forms)).toBe('second');
+      expect(getPlural('en', 0, forms)).toBe('seconds');
+      expect(getPlural('en', 2, forms)).toBe('seconds');
+    });
+
+    it('should return correct plural form for Russian', () => {
+      const forms = {
+        one: 'секунда',
+        few: 'секунды',
+        many: 'секунд',
+        other: 'секунд',
+      };
+
+      expect(getPlural('ru', 1, forms)).toBe('секунда');
+      expect(getPlural('ru', 2, forms)).toBe('секунды');
+      expect(getPlural('ru', 5, forms)).toBe('секунд');
+    });
+
+    it('should fallback to other form', () => {
+      const forms = {
+        other: 'default',
+      };
+
+      expect(getPlural('en', 1, forms)).toBe('default');
+      expect(getPlural('ru', 1, forms)).toBe('default');
+    });
+  });
+
+  describe('PluralAwareTranslator', () => {
+    describe('translateTimeExpression', () => {
+      it('should translate English time expressions', () => {
+        expect(PluralAwareTranslator.translateTimeExpression(1, 'second', 'en')).toBe('1 second');
+        expect(PluralAwareTranslator.translateTimeExpression(2, 'second', 'en')).toBe('2 seconds');
+        expect(PluralAwareTranslator.translateTimeExpression(1, 'minute', 'en')).toBe('1 minute');
+        expect(PluralAwareTranslator.translateTimeExpression(5, 'minute', 'en')).toBe('5 minutes');
+      });
+
+      it('should translate Spanish time expressions', () => {
+        expect(PluralAwareTranslator.translateTimeExpression(1, 'second', 'es')).toBe('1 segundo');
+        expect(PluralAwareTranslator.translateTimeExpression(2, 'second', 'es')).toBe('2 segundos');
+        expect(PluralAwareTranslator.translateTimeExpression(1, 'hour', 'es')).toBe('1 hora');
+        expect(PluralAwareTranslator.translateTimeExpression(3, 'hour', 'es')).toBe('3 horas');
+      });
+
+      it('should translate Russian time expressions', () => {
+        expect(PluralAwareTranslator.translateTimeExpression(1, 'second', 'ru')).toBe('1 секунда');
+        expect(PluralAwareTranslator.translateTimeExpression(2, 'second', 'ru')).toBe('2 секунды');
+        expect(PluralAwareTranslator.translateTimeExpression(5, 'second', 'ru')).toBe('5 секунд');
+      });
+
+      it('should translate Arabic time expressions', () => {
+        expect(PluralAwareTranslator.translateTimeExpression(0, 'second', 'ar')).toBe('0 ثوانِ');
+        expect(PluralAwareTranslator.translateTimeExpression(1, 'second', 'ar')).toBe('1 ثانية');
+        expect(PluralAwareTranslator.translateTimeExpression(2, 'second', 'ar')).toBe('2 ثانيتان');
+        expect(PluralAwareTranslator.translateTimeExpression(3, 'second', 'ar')).toBe('3 ثوانِ');
+      });
+
+      it('should handle unsupported locales with fallback', () => {
+        expect(PluralAwareTranslator.translateTimeExpression(1, 'second', 'unknown')).toBe(
+          '1 second'
+        );
+        expect(PluralAwareTranslator.translateTimeExpression(2, 'second', 'unknown')).toBe(
+          '2 seconds'
+        );
+      });
+    });
+
+    describe('translateHyperscriptTime', () => {
+      it('should translate time expressions in hyperscript', () => {
+        const input = 'wait 5 seconds then wait 1 minute';
+        const result = PluralAwareTranslator.translateHyperscriptTime(input, 'es');
+
+        expect(result).toBe('wait 5 segundos then wait 1 minuto');
+      });
+
+      it('should handle milliseconds', () => {
+        const input = 'wait 500 milliseconds';
+        const result = PluralAwareTranslator.translateHyperscriptTime(input, 'en');
+
+        expect(result).toBe('wait 500 milliseconds');
+      });
+
+      it('should handle abbreviated forms', () => {
+        const input = 'wait 100 ms';
+        const result = PluralAwareTranslator.translateHyperscriptTime(input, 'en');
+
+        expect(result).toBe('wait 100 milliseconds');
+      });
+
+      it('should preserve non-time content', () => {
+        const input = 'on click wait 2 seconds then show #result';
+        const result = PluralAwareTranslator.translateHyperscriptTime(input, 'es');
+
+        expect(result).toBe('on click wait 2 segundos then show #result');
+      });
+    });
+
+    describe('getOrdinal', () => {
+      it('should generate English ordinals', () => {
+        expect(PluralAwareTranslator.getOrdinal(1, 'en')).toBe('1st');
+        expect(PluralAwareTranslator.getOrdinal(2, 'en')).toBe('2nd');
+        expect(PluralAwareTranslator.getOrdinal(3, 'en')).toBe('3rd');
+        expect(PluralAwareTranslator.getOrdinal(4, 'en')).toBe('4th');
+        expect(PluralAwareTranslator.getOrdinal(11, 'en')).toBe('11th');
+        expect(PluralAwareTranslator.getOrdinal(21, 'en')).toBe('21st');
+        expect(PluralAwareTranslator.getOrdinal(22, 'en')).toBe('22nd');
+        expect(PluralAwareTranslator.getOrdinal(23, 'en')).toBe('23rd');
+      });
+
+      it('should generate Spanish ordinals', () => {
+        expect(PluralAwareTranslator.getOrdinal(1, 'es')).toBe('1º');
+        expect(PluralAwareTranslator.getOrdinal(5, 'es')).toBe('5º');
+      });
+
+      it('should generate French ordinals', () => {
+        expect(PluralAwareTranslator.getOrdinal(1, 'fr')).toBe('1er');
+        expect(PluralAwareTranslator.getOrdinal(2, 'fr')).toBe('2e');
+        expect(PluralAwareTranslator.getOrdinal(5, 'fr')).toBe('5e');
+      });
+
+      it('should generate Chinese ordinals', () => {
+        expect(PluralAwareTranslator.getOrdinal(1, 'zh')).toBe('第1');
+        expect(PluralAwareTranslator.getOrdinal(5, 'zh')).toBe('第5');
+      });
+
+      it('should generate Japanese ordinals', () => {
+        expect(PluralAwareTranslator.getOrdinal(1, 'ja')).toBe('1番目');
+        expect(PluralAwareTranslator.getOrdinal(5, 'ja')).toBe('5番目');
+      });
+
+      it('should generate Korean ordinals', () => {
+        expect(PluralAwareTranslator.getOrdinal(1, 'ko')).toBe('1번째');
+        expect(PluralAwareTranslator.getOrdinal(5, 'ko')).toBe('5번째');
+      });
+    });
+  });
+});