API Reference

For the complete hyperscript command reference (59 commands,
expressions, compilation API), see the
hyperfixi API docs.

This page documents the LokaScript multilingual-specific APIs.

@lokascript/i18n

Grammar transformation and keyword translation for hyperscript.

translate(code, fromLang, toLang)

Translate hyperscript code between languages.

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

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

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

This is the grammar transformer: it substitutes keywords and reorders
roles using the target language's profile. It is tuned for single commands.
For whole event handlers, and for any case where you need the result to
round-trip back to the source, use
@lokascript/semantic's translate() instead — it
parses to a semantic node first, so the return value is always re-parseable.

toEnglish(code, lang) / toLocale(code, lang)

Shorthands for translating to and from English.

import { toEnglish, toLocale } from '@lokascript/i18n';

toEnglish('alternar .active', 'es'); // → 'toggle .active'
toLocale('toggle .active', 'es');    // → 'alternar .active'

getSupportedLocales()

Returns the list of supported language codes.

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

getSupportedLocales();
// ['en', 'ja', 'ko', 'zh', 'ar', 'tr', 'es', 'de', 'fr', 'pt',
//  'id', 'ms', 'qu', 'sw', 'bn', 'it', 'ru', 'uk', 'vi', 'hi',
//  'tl', 'th', 'pl', 'he']

getProfile(lang)

Returns a language's grammar profile — word order, adposition type, text
direction, and the role markers used during transformation.

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

const ja = getProfile('ja');
ja.wordOrder;       // 'SOV'
ja.adpositionType;  // 'postposition'
ja.direction;       // 'ltr'
ja.markers;         // [{ form: 'を', role: 'patient', ... }, ...]

getProfile('en').wordOrder; // 'SVO'
getProfile('ar').wordOrder; // 'VSO'

@lokascript/semantic

Semantic multilingual parser for hyperscript.

parse(code, language)

Parse hyperscript code into a SemanticNode. The language is a positional
ISO 639-1 code, not an options object. Throws if parsing fails.

import { parse } from '@lokascript/semantic';

const node = parse('on click toggle .active on me', 'en');

node.kind;                    // 'event-handler'
node.metadata.confidence;     // 1
node.metadata.sourceLanguage; // 'en'
node.metadata.patternId;      // 'event-en-standard'

Confidence lives on metadata, and the node is not itself a runtime AST —
use buildAST() for that.

canParse(code, language)

Like parse(), but returns false instead of throwing. Use it to test a
candidate language without a try/catch.

import { canParse, getSupportedLanguages } from '@lokascript/semantic';

canParse('クリック で 私 の .active を 切り替え', 'ja'); // true
canParse('クリック で 私 の .active を 切り替え', 'en'); // false

// There is no built-in language detector. When the language is unknown,
// score the candidates you actually support:
const code = 'クリック で 私 の .active を 切り替え';
const detected = getSupportedLanguages().find((lang) => canParse(code, lang));
// → 'ja'

buildAST(node)

Convert a SemanticNode into a runtime-executable AST.

import { parse, buildAST } from '@lokascript/semantic';

const { ast, warnings } = buildAST(parse('toggle .active', 'en'));
if (warnings.length) console.warn(warnings);

translate(code, fromLang, toLang) (semantic)

Parse in one language and render in another. Unlike the i18n grammar
transformer, this round-trips: the output re-parses in the target language.

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

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

getAllTranslations(code, fromLang)

Translate once into every supported language.

import { getAllTranslations } from '@lokascript/semantic';

getAllTranslations('toggle .active', 'en');
// { en: 'toggle .active', ja: '.active を 切り替え',
//   es: 'alternar .active', ar: 'بدّل .active', ... }

render(node, language) / renderExplicit(node)

Render a parsed node back to hyperscript, or to the language-agnostic
explicit syntax used for debugging role assignment.

import { parse, render, renderExplicit } from '@lokascript/semantic';

const node = parse('on click add .highlight to #box', 'en');

render(parse('toggle .active', 'en'), 'ja');
// → '.active を 切り替え'

renderExplicit(node);
// → '[on event:click body:[add patient:.highlight destination:#box]]'

DEFAULT_CONFIDENCE_THRESHOLD / HIGH_CONFIDENCE_THRESHOLD

0.5 and 0.8. Compare against node.metadata.confidence when deciding
whether to trust a semantic parse.

@lokascript/hyperscript-adapter

Drop-in multilingual plugin for original _hyperscript.
See the adapter plugin page for
quick start, live demos, and bundle options.

hyperscriptI18n(options?)

Create a plugin for _hyperscript.use(). Returns a function that patches runtime.getScript() to translate non-English _="..." attributes before parsing.

import { hyperscriptI18n } from '@lokascript/hyperscript-adapter';

// Basic — uses defaults
_hyperscript.use(hyperscriptI18n());

// With options
_hyperscript.use(
  hyperscriptI18n({
    defaultLanguage: 'es',
    confidenceThreshold: { ja: 0.1, '*': 0.5 },
    debug: true,
  })
);

PluginOptions

preprocess(src, lang, config?)

Standalone preprocessing for programmatic _hyperscript("code") or _hyperscript.evaluate() calls. The plugin only intercepts DOM attributes — use this for code strings.

import { preprocess } from '@lokascript/hyperscript-adapter';

const english = preprocess('alternar .active', 'es');
// → 'toggle .active'

_hyperscript(english);

Parameters:

• src (string) — hyperscript code in the source language
• lang (string) — ISO 639-1 language code (e.g. 'es', 'ja')
• config (Partial<PreprocessorConfig>) — optional overrides

Returns string — English hyperscript. Returns original text if lang is 'en' or translation fails.

preprocessToEnglish(src, lang, config?)

Lower-level preprocessing function. Unlike preprocess(), does not short-circuit for English input. Most users should use preprocess() instead.

PreprocessorConfig

resolveLanguage(elt)

Resolve the language for an element using the cascading strategy:

1. data-lang attribute on the element
2. data-hyperscript-lang on the element or closest ancestor
3. <html lang="..."> on the document
4. Returns null (English assumed)

import { resolveLanguage } from '@lokascript/hyperscript-adapter';

// Useful for debugging language detection
const lang = resolveLanguage(document.querySelector('#myButton'));
console.log(lang); // 'es', 'ja', or null

BCP-47 tags are normalized to ISO 639-1 codes (e.g. "ja-JP" → "ja").

Core API

For the core hyperscript runtime API (compileSync,
compileAsync, eval, validate, etc.), see the
hyperfixi API reference.