loreline 0.8.1 → 0.9.0

package/js/loreline.d.ts

@@ -270,6 +270,62 @@ export class Loreline {
      */
     static extractTranslations(script: Script): Translations;
 
+    /**
+     * Loads translations for a specific locale, walking the script's full import tree.
+     *
+     * For each file involved in the script (root + transitively imported), the
+     * corresponding translation file is looked up by inserting `.<locale>` before
+     * the extension (e.g. `characters.lor` → `characters.fr.lor`). Missing translation
+     * files are silently skipped. The returned map can be passed as
+     * `InterpreterOptions.translations` to `play()` or `resume()`.
+     *
+     * @param locale The locale code (e.g. `"fr"`)
+     * @param script The parsed source script (must have been parsed with a file path,
+     *               or `filePath` must be provided)
+     * @param filePath Optional override for where to look for translation files
+     *                 (defaults to `script.filePath`). Can be a `.lor`/`.lor.txt` file
+     *                 path or a directory.
+     * @param handleFile File handler used to read translation files
+     * @param callback Called with the merged translations map. Required if `handleFile` is asynchronous.
+     * @returns The merged translations map (synchronously when `handleFile` is sync)
+     */
+    static loadLocale(
+        locale: string,
+        script: Script,
+        filePath?: string | null,
+        handleFile?: ImportsFileHandler,
+        callback?: (translations: Translations) => void
+    ): Translations | null;
+
+    /**
+     * Enable or disable runtime support for an alternate translation file format.
+     *
+     * By default only `.<locale>.lor` files are tried by `loadLocale`. Call
+     * this to opt in to additional formats:
+     * - `"po"`    — GNU gettext PO (`.po`)
+     * - `"xliff"` — XLIFF 1.2 / 2.x (`.xliff`, `.xlf`)
+     * - `"csv"`   — CSV / TSV (`.csv`, `.tsv`)
+     *
+     * Unknown names are accepted silently (forward-compat for future formats).
+     *
+     * @param name The format identifier (see above)
+     * @param enabled True to enable the format, false to disable
+     */
+    static translationFormat(name: string, enabled: boolean): void;
+
+    /**
+     * Returns the error from the most recent failed `parse()` or `loadLocale()`
+     * call, or `null` on success.
+     *
+     * In async mode (callback supplied) the callback fires with `null` on
+     * failure and this method tells you what went wrong. In sync mode the
+     * call throws, and this is set to the same error so it can be inspected
+     * after the catch.
+     *
+     * Not thread-safe — read immediately after the call returns.
+     */
+    static lastError(): Error | null;
+
     /**
      * Prints a parsed script back into Loreline source code.
      *
@@ -398,6 +454,15 @@ export class Interpreter {
      * @return The current node or null if no node is being executed
      */
     currentNode(): Node | null;
+
+    /**
+     * Returns the file path of the file containing the current node.
+     * Resolves through import chains relative to the given root file path.
+     *
+     * @param rootPath The file path of the root/main script
+     * @return The file path of the file containing the current node, or rootPath if in the root file
+     */
+    currentNodeFilePath(rootPath: string): string;
 }
 
 /**
@@ -483,6 +548,12 @@ export class Script extends Node {
      */
     body:Array<Node>;
 
+    /**
+     * The file path this script was parsed from.
+     * May be null if the script was parsed without a file path.
+     */
+    filePath: string | null;
+
     /**
      * Reconstructs a Script from a JSON representation.
      * @param json The JSON object (as returned by script.toJson())