Captions & translation

Push text into the caption chain, or call the currently active MT engine directly.

---

feed_direct_caption — source text only

host.feed_direct_caption(
    text: str,
    lang: str = "auto",
    *,
    tts: bool = False,
    drop_noise: bool = False,
) -> bool

Parameter	Description
text	Source text; an empty string returns False
lang	Source language, defaults to auto
tts	Whether to read the translation aloud; tools default to False
drop_noise	Whether to discard web noise such as ok / you; tools must pass False

Behaviour:

• SI running: goes through the full caption / history / TTS policy.
• Otherwise: lightweight path (MT + captions + history) — no ASR, no audio stream is opened.
• If the user turned both "Source" and "Translation" off, they are turned on automatically (so you never end up "translated but invisible").

Compatible alias: feedDirectCaption(text, lang) ≡ feed_direct_caption(text, lang, tts=False, drop_noise=False).

---

feed_caption — you already have the translation

host.feed_caption(
    text: str,
    translation: str | None = None,
    lang: str = "auto",
    source: str = "plugin",
    *,
    tts: bool = False,
    drop_noise: bool = False,
) -> bool

When translation is non-empty, MT is skipped and the bilingual captions go up directly. Used for: selections that already carry a translation, caption-bridge frame patches, and so on.

source is written into the history record (defaults to "plugin"; the internal lightweight path uses "select", browser captions use "web").

---

translate / translate_batch

host.translate(text: str, source: str = "auto", target: str = "zh",
               glossary_context: str | None = None) -> str

host.translate_batch(texts: list[str], source: str = "auto", target: str = "zh",
                     *, glossary_context: str | None = None) -> list[str]

• Goes through the currently active BaseMTEngineProvider.translate.
• Failures return an empty string and never raise (failed entries in translate_batch are empty strings too).
• glossary_context is passed through to the active MT (see mt).

---

Which one to use

Situation	Use
Source text only, and you want the host to handle the whole chain (including read-aloud)	feed_direct_caption(..., tts=True)
Source text only, and you do not want read-aloud	feed_direct_caption(...)
You already have the translation (selection / externally synced captions)	feed_caption(text, translation, source=…)
You only want to translate a piece of text quietly, without publishing captions	translate()
You need "translation + captions + read-aloud" as one unit	feed_direct_caption(..., tts=True) — do not stitch speak() + feed() together

---

Related

• Speech & feedback
• Event bus — caption/history events
• mt machine translation
• tool