@elizaos/plugin-translate

LibreTranslate integration for elizaOS agents. This plugin exposes a reusable service that calls a LibreTranslate instance, with built-in language support checks to avoid unsupported-language failures and reduce unnecessary API calls.

Setup

1. Install dependencies and build:

bun install
bun run build

2. Configure environment variables (optional overrides):

• LIBRE_TRANSLATE_BASE_URL – Defaults to https://libretranslate.com. Set this if you run a different LibreTranslate host.
• LIBRE_TRANSLATE_API_KEY – Optional API key if your instance requires authentication.
• LIBRE_TRANSLATE_REQUEST_TIMEOUT_MS – Optional timeout in milliseconds (default 15000).

Supported languages

• Default LibreTranslate instances support the ISO 639-1 codes listed in LANGUAGE_SUPPORT.md.
• The set is exported as LIBRE_TRANSLATE_SUPPORTED_LANGUAGES for reuse in UIs or guards.
• Custom LibreTranslate deployments may support more languages; extend or override the list as needed.

Unsupported-language guard (why it matters)

• LibreTranslate supports fewer languages than the detector (e.g., CLD3/fastText), which can identify ~176 languages.
• We pre-check pairs with isTranslationSupported to avoid 400s like "sn is not supported" and skip directly to the LLM fallback when needed.
• This reduces noisy logs and avoids wasted API calls while keeping full coverage via the LLM path.

Usage

Register the plugin in your agent configuration and access the service at runtime:

import { LibreTranslateService } from '@elizaos/plugin-translate';

const translateService = runtime.getService<LibreTranslateService>(LibreTranslateService.serviceType);
if (!translateService) throw new Error('Translate service not available');

// Optional: guard before calling the API
const sourceLanguage = 'auto';
const targetLanguage = 'es';
if (!translateService.isTranslationSupported(sourceLanguage, targetLanguage)) {
  // Decide how to handle unsupported pairs (e.g., fallback to another provider/LLM)
}

const result = await translateService.translate({
  text: 'Hello world',
  targetLanguage,
  sourceLanguage,
});

Methods

• translate({ text, targetLanguage, sourceLanguage?, format?, apiKeyOverride? }) – Perform a translation.
• isLanguageSupported(languageCode) – Check if a single language is supported by the default LibreTranslate models.
• isTranslationSupported(sourceLanguage, targetLanguage) – Check if a pair is supported (sourceLanguage may be auto).
• getConfig() – Read the resolved configuration (baseUrl, apiKey, timeoutMs).

Development

• bun run test – Run unit tests (uses mocked HTTP calls).
• bun run format – Format source files.
• bun run clean – Clean build artifacts.

Documentation

• LANGUAGE_SUPPORT.md – Supported language list and helper examples.
• FIX_UNSUPPORTED_LANGUAGES.md – Background on the unsupported-language guard and tests.