@almadar/core 10.86.0 → 10.87.0

package/dist/i18n/index.d.ts

@@ -1,3 +1,113 @@
+import { J as JsonValue } from '../json-D8gmyK3l.js';
+
+/**
+ * A `.lolo` lexer — the JS-path mirror of `orbital-lolo/src/lexer.rs`.
+ *
+ * It exists so the JS path can rewrite a program's VOCABULARY without
+ * re-implementing the parser: every token carries its byte span, so a
+ * consumer splices replacement text into the original source and every
+ * comment, blank line and alignment survives untouched.
+ *
+ * The character classes below are copied from the Rust lexer rather than
+ * re-derived — an identifier continues on `alphanumeric | _ | / | -` (so
+ * `render-ui` and `str/upper` are ONE token), a sigil root continues on
+ * `alphanumeric | _ | .`, and `true`/`false`/`null` are their own kinds.
+ * `is_alphanumeric` there is Unicode, so the `u`-flagged `\p{L}`/`\p{N}`
+ * classes here match it for Arabic and Slovenian identifiers.
+ *
+ * @packageDocumentation
+ */
+type LoloTokenKind = 'comment' | 'string' | 'number' | 'identifier' | 'literal' | 'sigil' | 'payload-sigil' | 'punct';
+interface LoloToken {
+    kind: LoloTokenKind;
+    /** Byte-independent (UTF-16 code unit) start offset into the source. */
+    start: number;
+    /** Exclusive end offset. */
+    end: number;
+    /**
+     * The token's semantic text. For `identifier`/`literal` it is the word
+     * itself; for `sigil`/`payload-sigil` it is the name WITHOUT the `@`/`?`
+     * prefix; for everything else it is the raw slice.
+     */
+    text: string;
+    /** Offset at which `text` starts (differs from `start` for sigils). */
+    textStart: number;
+}
+/**
+ * Tokenize a `.lolo` source. Never throws: an unterminated string or block
+ * comment runs to end-of-input and is returned as that token, because this
+ * lexer's callers render source they did not necessarily author (a docs
+ * fence, an editor buffer mid-keystroke) and must degrade to "translate
+ * nothing" rather than fail.
+ */
+declare function lexLolo(source: string): LoloToken[];
+
+/**
+ * English → native rendering of a `.lolo` program and a `.orb` document —
+ * the forward direction of `@almadar/core/i18n`.
+ *
+ * Everything else in this module family goes native → English so a program
+ * written in Arabic or Slovenian COMPILES (`aliasMap`, the Rust
+ * `Lang::canon_*`). This is the mirror: it takes the canonical English
+ * program and renders it in a target language, so a reader can be shown the
+ * same program in their own vocabulary.
+ *
+ * ## Why it is position-aware and not a word substitution
+ *
+ * The i18n contract (`docs/Almadar_i18n.md` §"What a native program looks
+ * like") is that the parser "canonicalizes at the grammar position that
+ * expects the word, never by text replacement, so a native identifier that
+ * happens to equal a keyword translation is only a keyword where a keyword is
+ * expected". The forward direction inherits that constraint exactly. Blind
+ * substitution corrupts real programs: `entity`/`type`/`fields`/`name`/
+ * `label`/`description` are all vocabulary words AND the commonest pattern
+ * prop keys, and `parse_object_literal` takes object keys VERBATIM — a
+ * pattern prop is opaque and is never translated. Likewise an entity's field
+ * names and a trait's state names are the author's identifiers even when they
+ * spell a keyword.
+ *
+ * So this walks the token stream with a frame stack that reproduces the
+ * parser's positional expectations, and translates only where the grammar
+ * says a vocabulary word belongs. Rendering splices into the original source
+ * by span, so comments, blank lines and alignment survive byte-for-byte.
+ *
+ * The gate on all of it is round-trip equality: for the whole `.lolo` corpus,
+ * `orb emit orb` of the translated program must equal `orb emit orb` of the
+ * English one. That proves both halves — every vocabulary word was translated
+ * (or the `.orb` would differ) and no identifier was (same).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The flat English → native map over every `.lolo` vocabulary family plus the
+ * caller's operators. Well-defined because `checkI18nCoverage` rule 2 forbids
+ * one English word having two translations across sections — verified at 545
+ * entries with zero conflicts for both `ar` and `sl`.
+ *
+ * Exported for callers that only need the vocabulary (a highlighter building
+ * native token patterns, a docs table); `localizeLoloSource` does NOT use it,
+ * because which family applies is a positional question.
+ */
+declare function localizeMap(lang: LanguageCode, operators?: OperatorTables): ReadonlyMap<string, string>;
+interface LocalizeLoloOptions {
+    /** Operator vocabulary — supplied by the caller (`@almadar/std`), since core must not import std. */
+    operators?: OperatorTables;
+}
+/**
+ * Render an English `.lolo` source in `lang`, preserving the original
+ * formatting exactly. `lang === 'en'` returns the source unchanged.
+ */
+declare function localizeLoloSource(source: string, lang: LanguageCode, options?: LocalizeLoloOptions): string;
+/**
+ * Render an English `.orb` value in `lang` — the exact inverse of the Rust
+ * `translate_orb_value`: object keys via `orb`, a `type` value via `types`,
+ * an array's leading string (an s-expression / effect head) via
+ * `effects ∪ operators`, and the root of any `@sigil` string. Every other
+ * string — an entity name, a label, free text — is left alone.
+ */
+declare function localizeOrbValue(value: JsonValue, lang: LanguageCode, options?: LocalizeLoloOptions): JsonValue;
+
 /**
  * Internationalization (i18n) — vocabulary tables for the `.lolo`/`.orb`
  * language (English, Arabic, Slovenian). See `Almadar_i18n.md` / the i18n
@@ -66,4 +176,4 @@ declare function checkI18nCoverage(input: I18nCoverageInput): {
  */
 declare function reportIdenticalToEnglish(input: I18nCoverageInput): I18nProblem[];
 
-export { I18N_SECTIONS, type I18nCoverageInput, type I18nMeta, type I18nProblem, type I18nProblemKind, type I18nSection, type I18nTables, LANGUAGE_CODES, LOLO_FIRST_TOKEN_KEYWORDS, type LanguageCode, type OperatorTables, aliasMap, checkI18nCoverage, coreTables, getVocabulary, languageOfLoloFirstToken, languageOfOrbTopLevelKeys, parseI18nTables, parseOperatorTables, reportIdenticalToEnglish };
+export { I18N_SECTIONS, type I18nCoverageInput, type I18nMeta, type I18nProblem, type I18nProblemKind, type I18nSection, type I18nTables, LANGUAGE_CODES, LOLO_FIRST_TOKEN_KEYWORDS, type LanguageCode, type LocalizeLoloOptions, type LoloToken, type LoloTokenKind, type OperatorTables, aliasMap, checkI18nCoverage, coreTables, getVocabulary, languageOfLoloFirstToken, languageOfOrbTopLevelKeys, lexLolo, localizeLoloSource, localizeMap, localizeOrbValue, parseI18nTables, parseOperatorTables, reportIdenticalToEnglish };