LocalMode
Transformers

Translation

Multi-language translation with Helsinki-NLP models.

Translate text between languages using Helsinki-NLP OPUS-MT models. Each model handles a specific language pair.

For full API reference (translate(), translateMany(), options, result types, and custom providers), see the Core Translation guide.

See it in action

Try the Translator block — it runs offline Opus-MT translation live in the browser.

ModelDirectionSizeUse Case
Xenova/opus-mt-en-frEnglish → French~100MBEN-FR translation
Xenova/opus-mt-en-deEnglish → German~100MBEN-DE translation
Xenova/opus-mt-en-esEnglish → Spanish~100MBEN-ES translation
Xenova/opus-mt-fr-enFrench → English~100MBFR-EN translation
Xenova/opus-mt-de-enGerman → English~100MBDE-EN translation
Xenova/opus-mt-es-enSpanish → English~100MBES-EN translation

OPUS-MT models are directional — each model translates one direction only. Use the correct model for your source → target language pair. Browse the full list at Helsinki-NLP on HuggingFace.

Multi-Target Models

Some Opus-MT models translate into several languages or scripts and need a sentence-initial >>id<< token naming the target. The translator adds it for the multi-target models it knows: Xenova/opus-mt-en-zh gets >>cmn_Hans<< (Simplified Mandarin) and Xenova/opus-mt-en-ar gets >>ara<< (Modern Standard Arabic). The token reaches the model as a single vocabulary id; without it, en-zh can return an unrelated sentence for short inputs.

import { transformers } from '@localmode/transformers';

// Default target: '>>cmn_Hans<<'
const zh = transformers.translator('Xenova/opus-mt-en-zh');

// Another target from the model's vocabulary (Traditional script)
const zhHant = transformers.translator('Xenova/opus-mt-en-zh', {
  targetLanguageToken: '>>cmn_Hant<<',
});

// Send the text unchanged
const raw = transformers.translator('Xenova/opus-mt-en-zh', { targetLanguageToken: false });

A token written at the start of the text ('>>yue_Hant<< Hello') names the target for that text, and providerOptions: { transformers: { targetLanguageToken } } overrides the setting per call. A token that is not in the model's vocabulary throws. The defaults are exported as OPUS_MT_TARGET_LANGUAGE_TOKENS, and resolveTargetLanguageToken(modelId, override?) returns the token a model will use.

Pinning a Revision

Pass revision (a branch, tag, or commit hash) to fix the model files a load downloads; it defaults to 'main' and works on every model factory, or on createTransformers({ revision }) for all of them:

const model = transformers.translator('Xenova/opus-mt-en-zh', {
  revision: '046f55aec303cdee3e0318604406d4df20f1e8ea',
});

Multi-Language Support

Based on the Translator block — use a different model per language pair:

import { transformers } from '@localmode/transformers';
import { translate } from '@localmode/core';

const models = {
  'en-fr': transformers.translator('Xenova/opus-mt-en-fr'),
  'en-de': transformers.translator('Xenova/opus-mt-en-de'),
  'en-es': transformers.translator('Xenova/opus-mt-en-es'),
  'fr-en': transformers.translator('Xenova/opus-mt-fr-en'),
  'de-en': transformers.translator('Xenova/opus-mt-de-en'),
  'es-en': transformers.translator('Xenova/opus-mt-es-en'),
};

async function translateText(text: string, pair: keyof typeof models) {
  const { translation } = await translate({
    model: models[pair],
    text,
  });
  return translation;
}

Best Practices

Translation Tips

  1. One model per direction — OPUS-MT models are unidirectional
  2. Cache model instances — Store models in a Map keyed by language pair
  3. Keep text reasonable — Very long texts may lose quality; consider chunking
  4. Support cancellation — Pass abortSignal for user-cancelable translations

Composed Block

BlockDescriptionLinks
TranslatorOffline Opus-MT translation across language pairsLive · Install: npx shadcn add @localmode/ui/blocks/writing-tools/translate

Next Steps

On this page