Grammar Transformation

The @lokascript/i18n package transforms hyperscript code
between languages by understanding semantic roles and
applying language-specific grammar rules.

How It Works

Every hyperscript command can be broken into semantic roles
that are universal across languages:

Role What it means Example
action The command verb toggle, put, fetch
patient What the action affects .active, #count
destination Where the result goes into #output
source Where data comes from from localStorage
event What triggers it click, keydown

The translate() function maps these roles between languages:

import { translate } from '@lokascript/i18n';

// English → Japanese
const ja = translate('toggle .active', 'en', 'ja');
// → '.active を 切り替え'

// Japanese → English
const en = translate('.active を 切り替え', 'ja', 'en');
// → 'toggle .active'

// English → Spanish
const es = translate('put "Hello" into #output', 'en', 'es');
// → 'poner "Hello" en #output'

Word Order Transformation

The key challenge: languages place semantic roles in different
positions.

SVO → SVO (e.g., English → Spanish)

Minimal reordering. Keywords translate, order stays the same:

English:  toggle  .active
          action  patient

Spanish:  alternar  .active
          action    patient

SVO → SOV (e.g., English → Japanese)

Object moves before the verb. Particles mark roles:

English:    add    .highlight  to    #box
            action  patient    prep  destination

Japanese:   #box   に  .highlight  を   追加
            dest   ←   patient    ←   action

The particle を marks the patient (object) and に marks the
destination. In SOV languages, the verb always comes last.

SVO → VSO (e.g., English → Arabic)

Verb moves to the front:

English:  put     "Hello"  into  #output
          action  patient  prep  destination

Arabic:   ضع      "Hello"  في    #output
          action  patient  prep  destination

Arabic maintains similar preposition patterns to English but
uses right-to-left text rendering.

Language Profiles

Each language has a profile that defines its grammar rules:

  • Word order: SVO, SOV, or VSO
  • Adposition type: Prepositions (before nouns) or
    postpositions (after nouns)
  • Role markers: Which particles/prepositions mark each
    semantic role
  • Text direction: LTR or RTL

Example: How Particles Work in Japanese

Japanese uses postpositions (particles after the noun) to mark
semantic roles:

Particle Role English equivalent
を patient (object) — (word order)
に destination to, into
から source from
で event / instrument on, with
の possession 's, of

These particles are inserted automatically during
transformation based on the semantic role of each token.

The Translation Pipeline

When you call translate(code, fromLang, toLang):

  1. Tokenize — Split input into tokens, identify keywords
    vs CSS selectors vs literals
  2. Role assignment — Map each token to a semantic role
    using the source language grammar
  3. Dictionary lookup — Translate keywords from source to
    target language
  4. Reorder — Rearrange tokens to match target language
    word order
  5. Insert markers — Add particles/prepositions required
    by the target grammar
  6. Join — Assemble the final output string

Supported Commands

The grammar system handles all standard hyperscript commands:

  • Class manipulation: toggle, add, remove
  • Content: put, set, get
  • Async: wait, fetch, send
  • Control flow: if/then/else, repeat
  • DOM: show, hide, remove (element)
  • Logging: log

Feature-level keywords (def, worker, behavior) stay in
English as they are structural rather than behavioral.

API Reference

See the Multilingual API for the full
@lokascript/i18n API including translate(),
getSupportedLanguages(), and getWordOrder().

Next Steps

Edit this page on GitHub