Translate Operator

Overview

The Translate LOP leverages the argostranslate Python library to perform offline text translation between numerous languages directly within TouchDesigner. It can translate individual text snippets, text from DATs, or entire conversation histories. Because it operates offline after initial language package downloads, it’s ideal for real-time applications or environments with limited internet access.

Offline Translation

Once the required language pair package is downloaded via the operator, translation happens locally without needing an internet connection.

Requirements

• Python Packages:
  • argostranslate: The core translation library. Must be installed via the ChatTD Python Manager.
• Language Packages: Specific language pair models (e.g., English to Spanish) need to be downloaded the first time they are used. The operator will prompt for installation if a required package is missing when translation is triggered.
• ChatTD Operator: Required for dependency management (installing argostranslate) and asynchronous operations. Ensure the ChatTD Operator parameter on the ‘About’ page points to your configured ChatTD instance.

Input/Output

Inputs

• Input 1 (input_table, Optional DAT): Connect a Table DAT containing conversation history here. Required when using Text Input Source modes like all_conversation, all_user, etc. Expected columns: role, message, id, timestamp.
• Input 2 (input_message, Optional DAT): Connect a Text DAT containing the text to be translated here. Used only when Text Input Source is set to Input DAT [ in2 ].

Outputs

• Output 1 (Table DAT): Contains the translated conversation table. Structure mirrors the input conversation table, but with messages translated according to the selected Text Input Source mode. Available when Output Type [ out1 ] is translate.
• Output 2 (Text DAT): Contains the translated text as plain text or translation statistics, depending on the Output Type [ out2 ] parameter.

Parameters

Page: Translate

Active (Active) op('translate').par.Active Toggle

Default:

Off

Status (Status) op('translate').par.Status String

Default:

Argos initialization complete - Ready for translation

Translate (Translate) op('translate').par.Translate Pulse

Default:

None

Auto [ onChange ] (Onchange) op('translate').par.Onchange Toggle

Default:

On

Text to Translate (Text) op('translate').par.Text String

Default:

None

From Language (Fromlang) op('translate').par.Fromlang Menu

Default:

en

Options:

en, es, fr, de, it, pt, nl, ru, ja, ko, zh, ar, hi, bn, pa, tr, vi, th, el, he, pl, uk, cs, sv, da, fi, no, hu, ro, id

To Language (Tolang) op('translate').par.Tolang Menu

Default:

es

Options:

en, es, fr, de, it, pt, nl, ru, ja, ko, zh, ar, hi, bn, pa, tr, vi, th, el, he, pl, uk, cs, sv, da, fi, no, hu, ro, id

Text Input Source (Textinput) op('translate').par.Textinput Menu

Default:

parameter

Options:

parameter, input_dat, all_conversation, all_user, all_assistant, system

Output Type [ out1 ] (Out1type) op('translate').par.Out1type Menu

Default:

translate

Options:

input, translate

Output Type [ out2 ] (Out2type) op('translate').par.Out2type Menu

Default:

text_only

Options:

text_only, translate_stats

Page: Callbacks

Callbacks Header

Callback DAT (Callbackdat) op('translate').par.Callbackdat DAT

Default:

None

Edit Callbacks (Editcallbacksscript) op('translate').par.Editcallbacksscript Pulse

Default:

None

Create Callbacks (Createpulse) op('translate').par.Createpulse Pulse

Default:

None

onTranslateComplete (Ontranslatecomplete) op('translate').par.Ontranslatecomplete Toggle

Default:

On

Textport Debug Callbacks (Debugcallbacks) op('translate').par.Debugcallbacks Menu

Default:

Full Details

Options:

None, Errors Only, Basic Info, Full Details

Available Callbacks:

• onTranslateComplete

Example Callback Structure:

def onTranslateComplete(info):
# Called after a translation task completes successfully or fails.
# info dictionary contains details like:
# - op: The Translate operator instance
# - text: The original input text or list of texts
# - translated_text: The resulting translated text or list
# - from_code: Source language code (e.g., 'en')
# - to_code: Target language code (e.g., 'es')
# - generation_time: Time taken for the translation in seconds
# - input_source: The 'Text Input Source' mode used
# - status: Success message or error details

print(f"Translation completed from {info.get('from_code')} to {info.get('to_code')}.")
print(f"Time taken: {info.get('generation_time'):.2f} seconds")

# Example: Check if translation was successful before proceeding
# if 'success' in info.get('status', '').lower():
#   op('downstream_processor').par.Cook.pulse()
pass

Page: About

Bypass (Bypass) op('translate').par.Bypass Toggle

Default:

Off

Show Built-in Parameters (Showbuiltin) op('translate').par.Showbuiltin Toggle

Default:

Off

Version (Version) op('translate').par.Version String

Default:

1.0.0

Last Updated (Lastupdated) op('translate').par.Lastupdated String

Default:

2025-01-26

Creator (Creator) op('translate').par.Creator String

Default:

dotsimulate

Website (Website) op('translate').par.Website String

Default:

https://dotsimulate.com

ChatTD Operator (Chattd) op('translate').par.Chattd OP

Default:

/dot_lops/ChatTD

Usage Examples

Basic Parameter Text Translation

1. Ensure 'argostranslate' is installed via ChatTD Python Manager.
2. Set 'Text Input Source' to 'Parameter Text'.
3. Enter text into the 'Text to Translate' parameter (e.g., "Hello, how are you?").
4. Select 'From Language' (e.g., 'en' for English).
5. Select 'To Language' (e.g., 'fr' for French).
6. Pulse the 'Translate' parameter.
7. The operator may prompt you to install the 'en' -> 'fr' language package if it's the first time. Click 'Install'.
8. View the translated text in the Text DAT connected to the second output.

Translating from Input DAT

1. Create a Text DAT (e.g., 'my_text_in').
2. Enter text into 'my_text_in'.
3. Connect 'my_text_in' to the second input of the Translate operator.
4. Set 'Text Input Source' to 'Input DAT [ in2 ]'.
5. Select 'From Language' and 'To Language'.
6. Pulse 'Translate' (or enable 'Auto [ onChange ]').
7. View translated text at the second output.

Translating a Full Conversation Table

1. Create a Table DAT (e.g., 'conversation_in') with columns: 'role', 'message', 'id', 'timestamp'. Populate it with messages.
2. Connect 'conversation_in' to the first input of the Translate operator.
3. Set 'Text Input Source' to 'Full Conversation'.
4. Select 'From Language' and 'To Language'.
5. Set 'Output Type [ out1 ]' to 'translate'.
6. Pulse 'Translate' (or enable 'Auto [ onChange ]').
7. View the translated conversation table at the first output.

Technical Notes

• Offline Operation: Core translation is offline after necessary language packages are downloaded.
• Package Installation: Language packages are downloaded and installed on demand when a specific language pair is first used. This requires an internet connection only during the installation phase and may briefly freeze the TouchDesigner UI.
• Dependencies: Requires the argostranslate Python package, installable via ChatTD.
• Asynchronous Translation: The actual translation process runs asynchronously via ChatTD’s TDAsyncIO to prevent blocking the main TouchDesigner thread, especially for longer texts or full conversations.
• Performance: Translation speed depends on the complexity of the text, the language pair, and system performance. Translating large conversation tables will take longer than single snippets.

Related Operators

• ChatTD: Provides core services like dependency management and asynchronous task execution required by this operator.