How to Write an OmegaT Script

Introduction

OmegaT scripts use the JSR-223 (Scripting for the Java™ Platform) API. This means any language with a JSR-223 compliant engine can be used, although Groovy and JavaScript are supported out of the box.

Script Locations

There are two primary locations where OmegaT looks for scripts:

1. User-defined Script Directory: This is the primary location for your scripts. You can configure this directory in Tools > Scripting…. By default, it is the scripts folder in OmegaT’s installation or working directory.

2. OmegaT Configuration Script Directory: Located at <configDir>/script (e.g., ~/.omegat/script on Linux). This directory is mainly used for internal data exchange (see Interaction with SegmentExportImport).

Supported Languages

• Groovy (.groovy): The recommended language for OmegaT scripts. It has excellent integration with Java and is widely used in the OmegaT community.

• JavaScript (.js): Supported via the built-in Nashorn (in older Java versions) or GraalJS engines.

• Other languages: You can add support for other languages (like Python or Ruby) by placing the corresponding JSR-223 engine JAR files into the OmegaT lib or plugins folder.

Global Bindings

When a script is executed, several global variables are automatically made available:

Variable	Description	Type
project	The current translation project.	ITranslationProject
editor	The editor component.	IEditor
glossary	The glossary management component.	IGlossaries
mainWindow	The main application window.	IMainWindow
Core	Access to the org.omegat.core.Core class.	Class<Core>
console	A logger for printing messages and clearing the output area in the Scripting Window.	IScriptLogger
res	A ResourceBundle for the script (if localized).	ResourceBundle

You can use console.println("Message") to print to the Scripting Window’s output area.

Script Metadata and Localization

You can provide a name and description for your scripts, which will be shown in the Scripting Window.

Embedded Metadata

Add the following tags in a comment at the beginning of your script:

// :name = My Custom Script
// :description = This script performs a specific task.

Localization via Properties

Create a properties/ subdirectory in your script folder and add a .properties file with the same name as your script (e.g., MyScript.groovy -> properties/MyScript.properties). Available keys:

• name: The localized name of the script.

• description: The localized description.

Event-Driven Scripts

OmegaT can automatically trigger scripts when specific events occur. To use this, place your scripts in a subdirectory of your User-defined Script Directory named after the event.

In addition to the Global Bindings, event-driven scripts receive specific variables depending on the event:

Directory Name	Trigger Event	Additional Bindings
application_startup	Shortly after OmegaT starts.	(none)
application_shutdown	When OmegaT is closing.	(none)
entry_activated	When a new segment is activated.	newEntry (SourceTextEntry)
new_file	When a new file is loaded.	activeFileName (String)
new_word	When a new word is detected.	newWord (String)
project_changed	When the project state changes.	eventType (PROJECT_CHANGE_TYPE)

Scripts in these folders are executed in alphabetical order.

GUI and Threading

By default, scripts run in a separate thread to avoid freezing the OmegaT interface. However, if your script needs to interact with Swing components (the GUI), those operations must run on the Event Dispatch Thread (EDT).

OmegaT simplifies this: if you define a function named gui, it will be automatically called on the EDT after the main body of the script has finished executing.

def gui() {
    // This code runs on the EDT
    javax.swing.JOptionPane.showMessageDialog(null, "Hello from the EDT!")
}

// Main script logic runs here (non-EDT)
console.println("Script is running...")

Interaction with SegmentExportImport

The SegmentExportImport feature allows external tools and scripts to interact with OmegaT’s content via text files in the OmegaT Configuration Script Directory (<configDir>/script). These files provide a simple way to access OmegaT content and process it with local programs such as shell scripts.

• source.txt: Contains the original text of the current segment. The text in the file is replaced each time a new segment is entered, provided that the Export the segment to text files preference is enabled (Options > Preferences > Editor).

• target.txt: Contains the translated text of the current segment. The text in the file is replaced each time a new segment is entered, provided that the Export the segment to text files preference is enabled.

• selection.txt: Stores the currently selected text when Edit > Export Selection is used. The text in the file is replaced each time this function is called.

• import.txt: If an external process writes to this file, OmegaT will automatically read its content and replace the current segment’s translation with it.

Example: A Simple Groovy Script

// :name = Hello World
// :description = Greets the user and prints project info.

import javax.swing.JOptionPane

console.println("Hello from Groovy!")
console.println("Current project: " + project.projectProperties.projectName)

def gui() {
    JOptionPane.showMessageDialog(null, "Hello, OmegaT user!")
}

Default Scripts Documentation

OmegaT comes with a set of default scripts in the scripts/ folder. Detailed documentation for these scripts is available here:

Editor and Translation Utilities

• nbsp.groovy - Replace spaces with non-breaking spaces in French.

• modify_segment.groovy - Example of how to modify the current segment.

• replace_strip_tags.groovy - Remove tags in the current target or selection.

• replace_with_match_no_tags.groovy - Replace current target with tag-free match.

• currency_translate.groovy - Translate currency representations.

• strip_bidi_marks.groovy - Remove bidirectional marks.

• tagwipe.groovy - Remove unnecessary tags from docx documents.

Project and File Management

• open_tm_folder.groovy - Open the /tm folder.

• open_folder.groovy - Open the project root folder.

• open_glossary.groovy - Open the writeable glossary in an editor.

• open_project_save.groovy - Open project_save.tmx in an editor.

• open_current_file.groovy - Open the current source file.

• auto_open_last_project.groovy - Automatically open the last used project.

Check and QA Utilities

• check_rules.groovy - QA script to check various rules.

• check_same_segments.groovy - Check for identical source and target segments.

• check_same_segments.js - JavaScript version of identical segment check.

• show_same_segments.groovy - Display a list of identical source and target segments.

• spellcheck.groovy - Global spell checking utility.

• external_spellcheck.groovy - Export segments to an external file for spell checking.

Other Utilities and Development Examples

• gui_scripting.groovy - Example of GUI scripting using Groovy.

• issue_provider_sample.groovy - Example of a custom issue provider.

• keybinding.groovy - Example of keybinding event handling.

• svn_cleanup_selected.groovy - Perform SVN cleanup on project folders.

• switch_colour_theme.js - Switch OmegaT editor color themes.

• toolbar.groovy - Example of adding a custom toolbar with script buttons.

• extract_text_content.groovy - Extract project content to a text file.

• adapt_tags_to_match_target.groovy - Automatically adapt tags when inserting a match.

• search_replace.groovy - Simple search and replace across the project. OmegaT provides a powerful scripting feature that allows users and developers to automate tasks, extend the application’s functionality, and interact with the translation project and the GUI.