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.
Recommended Models
| Model | Direction | Size | Use Case |
|---|---|---|---|
Xenova/opus-mt-en-fr | English → French | ~100MB | EN-FR translation |
Xenova/opus-mt-en-de | English → German | ~100MB | EN-DE translation |
Xenova/opus-mt-en-es | English → Spanish | ~100MB | EN-ES translation |
Xenova/opus-mt-fr-en | French → English | ~100MB | FR-EN translation |
Xenova/opus-mt-de-en | German → English | ~100MB | DE-EN translation |
Xenova/opus-mt-es-en | Spanish → English | ~100MB | ES-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
- One model per direction — OPUS-MT models are unidirectional
- Cache model instances — Store models in a Map keyed by language pair
- Keep text reasonable — Very long texts may lose quality; consider chunking
- Support cancellation — Pass
abortSignalfor user-cancelable translations
Composed Block
| Block | Description | Links |
|---|---|---|
| Translator | Offline Opus-MT translation across language pairs | Live · Install: npx shadcn add @localmode/ui/blocks/writing-tools/translate |