Bidirectional Translation¶

In a nutshell

Many OVOS skills only "speak" one language, usually English. This plugin acts like a live interpreter sitting between you and the assistant: it translates what you say into the language the skills understand, and then translates the assistant's reply back into your language before it is spoken aloud. So you can ask a question in Spanish, have an English-only skill answer it, and still hear the response in Spanish. See Translation Plugins or the Glossary for related terms.

📐 Formal specification

This "interpreter in the middle" is built entirely from transformers, as defined by OVOS-TRANSFORM-1 — Transformer Plugins. The spec defines six ordered chains (audio / utterance / metadata / intent / dialog / tts) at fixed points in the utterance lifecycle: inbound translation runs as an utterance-transformer (before intent matching), outbound translation as a dialog- or tts-transformer (after a skill responds). For the full set see the spec index.

The Bidirectional Translation Plugin (ovos-bidirectional-translation-plugin) lets OpenVoiceOS interact in any language, even if the installed skills are only available in a single primary language, like English.

It translates user utterances into the system's native language before intent matching. Then it translates the system's spoken responses back into the user's original language.

How it Works¶

The plugin consists of two main components:

Utterance Transformer: Detects the language of the incoming text. If it doesn't match the system's native language, it translates the utterance so ovos-core can understand it.
Dialog Transformer: Intercepts the dialog generated by a skill and translates the response back into the language the user originally spoke.

Interaction Flow¶

sequenceDiagram
    participant U as User (ES)
    participant STT
    participant UT as UtteranceXForm
    participant Core as ovos-core
    participant Skill as Time Skill (EN)
    participant DT as DialogXForm
    participant TTS

    U->>STT: "¿Qué hora es?"
    STT->>UT: text (Spanish)
    UT->>Core: "What time is it?"<br/>(translated to English)
    Core->>Skill: match TimeIntent
    Skill->>DT: "The time is 10:00 AM"
    DT->>TTS: "Son las 10:00 AM"<br/>(translated back to Spanish)
    TTS->>U: speaks Spanish response

Diagram: The sequence starts with the Spanish-speaking user and ends with TTS speaking the Spanish response, branching through translation to English for the skill match and back to Spanish for the reply.

User speaks in Spanish: "¿Qué hora es?"
STT transcribes to text (Spanish).
Utterance Transformer detects Spanish, translates to English: "What time is it?".
ovos-core matches the TimeIntent in the English-only Time Skill.
Skill responds in English: "The time is 10:00 AM".
Dialog Transformer detects that the user originally spoke Spanish, translates response: "Son las 10:00 AM".
TTS speaks the Spanish response.

Configuration¶

This plugin only orchestrates translation. It does not translate anything itself. You must first configure a language detection plugin and a translation plugin under the "language" section of mycroft.conf (see Translation Plugins). The transformers below then call whatever you configured there.

Recommended Plugins¶

Local: ovos-translate-plugin-nllb (No Language Left Behind, offline) paired with an offline detector such as ovos-lang-detector-fasttext-plugin, or the ovos-lang-detector-plugin-voter entry point from ovos-lang-detector-classics-plugin. The voter loads cld2, langdetect and fastlang and raises at startup if any of them is missing, so install it as ovos-lang-detector-classics-plugin pycld2 langdetect fastlang.
Remote: ovos-translate-plugin-server for translation and ovos-lang-detector-plugin-server for detection (both from ovos-translate-server-plugin, pointing at an ovos-translate-server).

Configuration Example¶

{
  "language": {
    "detection_module": "ovos-lang-detector-plugin-voter",
    "translation_module": "ovos-translate-plugin-nllb",
    "ovos-translate-plugin-nllb": {
      "model": "nllb-200_600M_int8"
    }
  },
  "utterance_transformers": {
    "ovos-utterance-translation-plugin": {
      "bidirectional": true,
      "verify_lang": false,
      "ignore_invalid_langs": true,
      "translate_secondary_langs": false
    }
  },
  "dialog_transformers": {
    "ovos-dialog-translation-plugin": {}
  }
}

The two transformers are keyed by their entry-point names — ovos-utterance-translation-plugin (an opm.transformer.text plugin, the class UtteranceTranslator) and ovos-dialog-translation-plugin (an opm.transformer.dialog plugin, the class DialogTranslator). Both ship from the single package ovos-bidirectional-translation-plugin.

Option Reference¶

These keys go in the ovos-utterance-translation-plugin config block. Defaults are what the plugin uses when the key is absent.

Key	Default	Effect
`bidirectional`	`true`	When an utterance is translated in, also translate the spoken response back to the user's language. If `false`, OVOS understands the user but answers in its primary language.
`verify_lang`	`false`	Run the detector on every utterance and trust the detected language over the `Session` language. Useful for chat-style clients where the incoming language tag is unreliable.
`ignore_invalid_langs`	`false`	Only meaningful with `verify_lang`. If the detected language is not one of the valid (primary + secondary) languages, ignore the detection instead of acting on it. This guards against false positives on short text.
`translate_secondary_langs`	`false`	If `true`, only the primary `lang` counts as "native" and even configured `secondary_langs` get translated to the primary language. If `false`, secondary languages are treated as already understood and pass through untranslated.

The valid-language set is computed from lang + secondary_langs in mycroft.conf. An utterance is only translated when its session language is not in that set.

Forcing the Output Language (Bus API)¶

The DialogTranslator listens on the messagebus. A skill or client can use it to pin the response language for a session, independent of what the user spoke:

Message	`data`	Effect
`ovos.language.output.force`	`{"lang": "<bcp47>"}`	Force all spoken dialog for this session into `<lang>` until reset.
`ovos.language.output.reset`	—	Clear the forced output language for the session.

Technical Considerations¶

Alpha Status: This plugin is in alpha and adds latency, since each turn may incur two translation round-trips (utterance in, dialog out).
First-utterance only: when STT emits multiple candidate utterances, only the first is translated. The rest pass through untranslated.
Where to install: in a split deployment (e.g. ovos-docker), the utterance transformer must run where intents are processed (ovos-core). The dialog transformer must run where speech is produced (ovos-audio). The translation and detection plugins must be installed in both places.