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 is 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. Install it 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.

Input/Output

Inputs

• Input 1 (Optional Table DAT): Connect a Table DAT containing conversation history here. Required when using Text Input Source modes like Full Conversation, All User Messages, etc. Expected columns: role, message, id, timestamp.
• Input 2 (Optional Text 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. Controlled by the Output Type [ out1 ] parameter.
• Output 2 (Text DAT): Contains the translated text as plain text or translation statistics, depending on the Output Type [ out2 ] parameter.

Usage Examples

Basic Parameter Text Translation

1. Ensure argostranslate is installed via ChatTD Python Manager.
2. On the Translate page, set Text Input Source to Parameter Text.
3. Enter text into the Text to Translate field (e.g., “Hello, how are you?”).
4. Select From Language (e.g., English).
5. Select To Language (e.g., French).
6. Pulse the Translate button.
7. The operator may prompt you to install the English to French language package if it is the first time. Click Install.
8. View the translated text at the second output.

Translating from Input DAT

1. Create a Text DAT and enter the text you want to translate.
2. Connect it to the second input of the Translate operator.
3. Set Text Input Source to Input DAT [ in2 ].
4. Select From Language and To Language.
5. Pulse Translate (or enable Auto [ onChange ] for automatic translation on input changes).
6. View the translated text at the second output.

Translating a Full Conversation Table

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

Translating Role-Specific Messages

1. Connect a conversation Table DAT to the first input.
2. Set Text Input Source to All User Messages, All Assistant Messages, or System Messages to translate only messages from a specific role.
3. Select your language pair and pulse Translate.
4. The output table preserves all messages but only translates those matching the selected role.

Technical Notes

• Offline Operation: Core translation is fully offline after the 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.
• Asynchronous Translation: The translation process runs asynchronously to prevent blocking the main TouchDesigner thread, especially for longer texts or full conversations.
• Supported Languages: 30 languages are available including English, Spanish, French, German, Italian, Portuguese, Dutch, Russian, Japanese, Korean, Chinese, Arabic, Hindi, and more. The full list is visible in the From Language and To Language menus.
• 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.

Parameters

Translate

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

Default:

False

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

Default:

"" (Empty String)

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

Default:

False

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

Default:

False

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

Default:

"" (Empty String)

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:

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

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:

input

Options:

input, translate

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

Default:

text_only

Options:

text_only, translate_stats

Callbacks

Callbacks Header

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

Default:

ChatTD_callbacks

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

Default:

False

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

Default:

False

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

Default:

False

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

Default:

Full Details

Options:

None, Errors Only, Basic Info, Full Details

Callbacks

Available Callbacks:

• onTranslateComplete

Example Callback Structure:

def onTranslateComplete(info):
# Called after a translation task completes successfully.
# info dictionary contains:
# - 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

Related Operators

• Chat