@lite-translator/core

Dependency-free, privacy-friendly translation API for the browser. Translation text never leaves the user's device — no cloud, no servers.

Part of lite-translator — a small, offline-capable browser translation library. This package provides the engine-independent core API. Pair it with @lite-translator/engine-onnx for local ONNX/Transformers.js inference.

Install

npm install @lite-translator/core @lite-translator/engine-onnx

Quickstart

import { createTranslator } from "@lite-translator/core";
import { createOnnxEngine } from "@lite-translator/engine-onnx";

const translator = await createTranslator({
  from: "de",
  to: "en",
  engines: [createOnnxEngine()],
});

const result = await translator.translate("Hallo Welt");
console.log(result.text);
await translator.dispose();

Features

Batch translation

Translate many texts in a single inference call — one tokenization, encoder and decoder pass for the whole batch instead of N roundtrips.

const results = await translator.translateBatch([
  "Hallo Welt",
  "Guten Morgen",
  "Wie geht es dir?",
]);
// results[i].text corresponds to input i (order preserved, empty strings kept)

i18n-style translation

Register UI strings across components with t(key, text), then translate all of them in one translateAll() call — one inference pass, no race conditions.

const t = translator.t();

// Component A
t("header.title", "Willkommen"); // registers, returns "Willkommen"
t("header.subtitle", "Bitte wählen");

// Component B
t("footer.button", "Bestätigen");

// One click — one inference call for all registered strings
await translator.translateAll();

t("header.title"); // → "Welcome" (translated)
t("footer.button"); // → "Confirm" (translated)

The store is reactive: frameworks bind via subscribe() / snapshot() and re-render automatically. Identical values are deduplicated before inference. → Full guide

Live translation

Incremental translation for chat or speech-to-text. Input is segmented at sentence boundaries; completed sentences are cached and only the still-growing tail is re-translated.

const live = translator.createLiveSession({ debounce: 250 });

live.on("translation", (e) => {
  console.log(e.text); // full translation
  console.log(e.partial); // still-growing tail
});

live.update("Hallo wie geht");

→ Full guide

Debug output

Structured lifecycle and timing events via an opt-in onDebug callback — zero overhead when absent.

const translator = await createTranslator({
  from: "de",
  to: "en",
  engines: [engine],
  onDebug: (e) => console.debug(`[${e.type}]`, e),
});

await translator.preload();
// [load-start] { pair: { from: "de", to: "en" }, ... }
// [load-done]  { durationMs: 1234, ... }

await translator.translate("Hallo Welt");
// [translate-start] { inputLength: 10, ... }
// [translate-done]  { durationMs: 45, outputLength: 11, ... }

→ Full guide

Capabilities

Inspect the engine's resolved device, dtype, and model after load.

await translator.preload();
console.log(translator.capabilities());
// { engine: "onnx", device: "wasm", dtype: "bnb4", modelId: "onnx-community/opus-mt-de-en" }

Cache management

Remove a model from the browser's Cache Storage to free disk space or force a re-download.

await translator.preload();
console.log(await translator.isCached()); // true
await translator.removeModel();
console.log(await translator.isCached()); // false

API

| Export | Description | | --- | --- | | createTranslator(options) | Creates a translator (no model download on import) | | translator.translate(text, options?) | Translates text; options.signal for AbortSignal cancellation | | translator.translateBatch(texts, options?) | Translates multiple texts in one call (order preserved) | | translator.preload() | Explicitly preloads the model | | translator.t() | Returns bound t(key, text?) for i18n-style registration | | translator.translateAll(options?) | Translates all t()-registered strings in one translateBatch() and notifies store subscribers once | | translator.createLiveSession(options?) | Creates a LiveSession for incremental live translation | | translator.capabilities() | Returns resolved engine capabilities (device, dtype, model info) | | translator.removeModel() | Removes cached model files from Cache Storage | | translator.store() | Reactive TranslationStore backing t() (lazy, undefined before first t()) | | translator.isReady() | Model loaded and ready | | translator.isCached() | Model present in local cache (offline-capable) | | translator.dispose() | Frees resources | | TranslatorPool | Manages translators by language pair with LRU eviction (maxSize) | | formatTranslatorError(err) | Formats any error into a consistent human-readable string | | isTranslatorError(err) | Type guard for TranslatorError | | withBatchFallback(engine) | Wraps an engine without translateBatch with a sequential fallback |

Links

• GitHub repository
• Roadmap
• API reference
• Integration guides
• Engine package: @lite-translator/engine-onnx