Chapter 3. Installing and running OmegaT

1. Windows Users
1.1. Downloading the package
1.2. Installing OmegaT
1.3. Adding OmegaT to the start menu or desktop
1.4. Running OmegaT
1.5. Upgrading OmegaT
2. Linux (Intel) Users
2.1. Downloading the right package
2.2. Installing OmegaT
2.3. Adding OmegaT to your menus (KDE) or panels (Gnome)
2.4. Running OmegaT
3. Mac OS X Users
3.1. Downloading the package
3.2. Installing OmegaT
3.3. Adding OmegaT to the Dock
3.4. Running OmegaT
3.5. Mac OS X goodies
4. Other Systems
4.1. Downloading the right package
4.2. Installing OmegaT
4.3. Installing convenient shortcuts
4.4. Running OmegaT
5. Using Java Web Start
6. Starting OmegaT from the command line
6.1. Opening a command line window
6.2. Launch command arguments
6.3. OmegaT in the command line mode
7. Building OmegaT From Source

1. Windows Users

1.1. Downloading the package

Do you have a Java implementation compatible with Oracle's Java 1.5 JRE?

  • Yes: download OmegaT_2.3.x_Windows_without_JRE.exe.

  • No / I don't know: download OmegaT_2.3.x_Windows.exe.

    This package is bundled with Oracle's Java Runtime Environment. This JRE will not interfere with other Java implementations that may already be installed on your system.

1.2. Installing OmegaT

To install OmegaT, double-click on the program you have downloaded, and follow the instructions

1.3. Adding OmegaT to the start menu or desktop

During the installation, the setup program asks you whether you wish to create a folder in the start menu, and whether you wish to create a shortcut on the desktop and in the quick launch bar.

You can still create a shortcut later by dragging OmegaT.exe to the desktop or start menu to link it from there.

1.4. Running OmegaT

Once OmegaT is installed, you can click on OmegaT.jar to launch it directly or you can launch it directly from the command line.

The simplest way to launch OmegaT, however, is to execute the OmegaT.exe program. The options for the program start-up in this case will be read from the OmegaT.l4J.ini file, which resides in the same folder as the exe file and which you can edit to reflect your setup. The following example for the INI file reserves 1GB of memory, requests French as the user language and Canada as the country:

# OmegaT.exe runtime configuration
# To use a parameter, remove the '#' before the '-'
# Memory 
-Xmx1024M 
# Language 
-Duser.language=FR
# Country 
-Duser.country=CA 

1.5. Upgrading OmegaT

This information applies only to the "Traditional" Windows versions of OmegaT. It does not apply to the Web Start versions, which are upgraded automatically, nor to cross-platform versions installed on Windows.

If you already have a version of OmegaT installed on your PC and wish to upgrade to a more recent version, you have two options:

  • Install over the existing installation. To do this, simply select the same installation folder as the existing installation when installing the new version. The "old" version of OmegaT will be overwritten, but any settings from it will be retained. This includes preferences set from within OmegaT, any changes you have made to your OmegaT.l4J.ini file, and also your launch script (.bat file), if you are using one.

With this method, you may also download the "Windows without JRE" version, since the new installation will use your existing JRE.

  • Install to a new folder. This will enable you to keep both versions side-by-side, which you may wish to do until you feel comfortable with the new version. This method will also use preferences and settings you have made from within OmegaT. In this case, however:

    • If you have made changes to your OmegaT.l4J.ini file and/or are using a .bat file, you must copy these over.

    • If your existing OmegaT installation is a "Windows with JRE" version, the new version must also be a "Windows with JRE" version.

2. Linux (Intel) Users

2.1. Downloading the right package

Do you have a Java implementation compatible with Oracle's Java 1.5 JRE?

  • Yes: download OmegaT_2.3.x_Without_JRE.zip.

  • No / I don't know: download OmegaT_2.3.x_Linux.tar.bz2.

    This package is bundled with Oracle's Java Runtime Environment. This JRE will not interfere with other Java implementations that may already be installed on your system.

2.2. Installing OmegaT

Unpack/untar the downloaded file. This will create an omegat/ folder in the working folder in which you will find all the files needed to run OmegaT. To untar the .tar.gz file:

$ tar xf downloaded_file.tar.gz

2.3. Adding OmegaT to your menus (KDE) or panels (Gnome)

2.3.1. KDE 4 Users

You can add OmegaT to your menus as follows:

  • Press Alt+F2 to show KRunner. Type kmenuedit+enter to run the command. The KMenuEditor appears. In KMenuEditor select File -> New Item.

  • Then, after selecting a suitable menu, add a submenu/item with File - New Submenu and File - New Item. Enter OmegaT as the name of the new item.

  • In the "Command" field, use the navigation button to find your OmegaT launch script (the file named OmegaT in the unpacked folder), and select it.

  • Click on the icon button (to the right of the Name/Description/Comment fields)

  • Other Icons - Browse, and navigate to the /images subfolder in the OmegaT application folder. Select the OmegaT.png icon.

  • Finally, save the changes with File - Save.

2.3.2. GNOME Users

You can add OmegaT to your menus as follows:

  • Right-click on the panel - Add New Launcher.

  • Enter "OmegaT" in the "Name" field; in the "Command" field, use the navigation button to find your OmegaT launch script (the file named OmegaT in the unpacked folder). Select it and confirm with OK.

  • Click on the icon button, then hit Browse... and navigate to the /images subfolder in the OmegaT application folder. Select the OmegaT.png icon. GNOME may fail to display the icon files in the available formats and initially appear to expect an SVG file, but if the folder is selected, the files should appear and OmegaT.png can be selected.

2.4. Running OmegaT

You can launch OmegaT from the command line with a script that includes start-up options or you can click on OmegaT.jar to launch it directly. Methods differ depending on the distribution. Make sure that your PATH settings are correct and that .jar files are properly associated with a Java launcher. Check "Command line launching" below for more information.

3. Mac OS X Users

3.1. Downloading the package

OmegaT 2.3 requires Java 1.5 to run. Use "Software Update..." from the Apple menu to update your Java version.

Download OmegaT_2.3.x_Mac.zip.

3.2. Installing OmegaT

Double click on OmegaT_2.3.x_Mac.zip to unpack it. This creates a folder called OmegaT . The folder contains 2 files: index.html and OmegaT.app. Copy the folder to a suitable folder (e.g. Applications). Once you have done this, you can delete the OmegaT_2.3.x_Mac.zip file, it is no longer needed.

3.3. Adding OmegaT to the Dock

Drag and drop OmegaT.app onto the Dock.

3.4. Running OmegaT

Double-click on OmegaT.app or click on its location in the Dock.

To access Info.plist, right-click on OmegaT.app and select "Show Package Contents", then open the file by right-clicking on it and selecting your text editor of choice. You can also "cd" there directly from the command line and open Info.plist in a command line editor like emacs or vi.

You can modify the Properties as well as the VMOptions part.

If you wish to add values to VMOptions, put a space between them. For example, -Xmx1024M -Duser.language=ja will launch OmegaT with 1024MB of memory and with the user interface in Japanese.

To launch multiple instances of OmegaT.app, double-click the file JavaApplicationStub located in OmegaT.app/ Contents/MacOS/.

Use OmegaT.jar file located in OmegaT.app/Contents/Resources/Java/ to launch OmegaT from the command line. Check "Command line launching" below for more information.

3.5. Mac OS X goodies

OmegaT.app can be accessed from the Mac OS X Services. You can thus select a word anywhere in OmegaT and use Services to check this word, for instance in Spotlight or in Google. You can also use AppleScript or Automator to create Services or scripts that will automate frequent actions

4. Other Systems

This information applies to systems such as Solaris SPARC/x86/x64, Linux x64/PowerPC, Windows x64

4.1. Downloading the right package

OmegaT is available bundled with a Oracle Java JRE for Linux (Intel x86) and Windows platforms. Users of other platforms (Linux PowerPC, Linux x64, Solaris SPARC/x86/x64, Windows x64 etc) must have a running compatible Java JRE on their system to be able to use OmegaT.

Do you have a Java implementation compatible with Oracle's Java 1.5 JRE?

  • Yes: download OmegaT_2.3.x_Windows_without_JRE.zip. This package can be used on any platform where a Java 1.5 JRE compatible JRE is installed.

  • I don't know: open a terminal and type "java -version". If a "command not found" or similar message is returned, it is likely that Java is not installed on your system

  • No: obtain a Java JRE for your system (see below) and download OmegaT_2.3.x_Without_JRE.zip.

    Oracle provides JREs for Solaris SPARC/x86 (Java 1.5) and for Linux x64, Solaris x64, Windows x64 (Java 1.5) at http://www.oracle.com/technetwork/java/archive-139210.html

    IBM provides JREs for Linux PowerPC at http://www.ibm.com/developerworks/java/jdk/linux/download.htm

    Follow the installation instructions of the package you need.

4.2. Installing OmegaT

To install OmegaT, simply unpack the OmegaT_2.3.x_Without_JRE.zip file. This creates an ./OmegaT_2.3.x_Without_JRE/ directory in the working folder with all the files necessary to run OmegaT.

4.3. Installing convenient shortcuts

Follow your system's instructions to install OmegaT shortcuts in convenient places of your choosing.

4.4. Running OmegaT

Once OmegaT is installed, you can launch it directly from the command line, you can create a script that includes launch parameters for the command line or you can click on OmegaT.jar to launch it directly. Methods differ depending on the distribution. Make sure that your PATH settings are correct and that .jar files are properly associated with a Java launcher. Check "Command line launching" below for more information.

5. Using Java Web Start

Java Web Start technology (part of Java 1.5 and above) can be used to deploy standalone Java software applications with a single click over the network. Java Web Start ensures that the latest version of the application will be deployed, as well as the correct version of the Java Runtime Environment (JRE) used. To start OmegaT for the first time with Java Web Start, load the following URL in your browser:

http://omegat.sourceforge.net/webstart/OmegaT.jnlp

Download the file OmegaT.jnlp and then click on it. During the installation, depending on your operating system, you may receive several security warnings. The permissions you give to this version (which may appear as "unrestricted access to the computer") are identical to the permissions you give to the local version, i.e., they allow access to the hard drive of the computer. Subsequent clicks on OmegaT.jnlp will check for any upgrades, install them, if there are any, and then start OmegaT. After the initial installation you can, of course, also use OmegaT.jnlp also when you are offline.

Privacy: OmegaT Java Web Start does not save any of your information beyond the computer on which you are running it. The application runs on your machine only. Your documents and translation memories remain on your computer, and the OmegaT project will have no access to your work or information.

Note that if you need or wish to use any of the launch command arguments (see above), you must use the normal installation.

6. Starting OmegaT from the command line

Normally, it is not necessary to start OmegaT from the command line. However, the command-line alternative allows the user to control and modify the program's behavior. There are two ways of launching OmegaT using the command line.

6.1. Opening a command line window

A command line window is also referred to as a "terminal window". On Windows it is called an "MS-DOS window" and is available from the Start Menu, inside Programs, through the "MS-DOS" item. The Mac OS X equivalent is the application Terminal located in Applications → Utilities.

To launch OmegaT, you must normally type two commands. The first of these is:

cd {folder}

where {folder} is the name of the folder, with complete path, in which your OmegaT program - specifically, the file OmegaT.jar - is located. In practice, this command will therefore be something like this:

On Windows

cd C:\Program Files\OmegaT

On Mac OS X

cd <OmegaT.app location>/OmegaT.app/Contents/Resources/Java/

On Linux

cd /usr/local/omegat

This command changes the folder to the folder containing the executable OmegaT file. The second command is the command which actually launches OmegaT. In its most basic form, this command is:

java -jar OmegaT.jar

Pay attention to the capitalization - the program will not start, if you enter omegat instead of OmegaT !

This method has a particular benefit of being suitable for finding causes of problems: if an error occurs during use of the program, an error message is output in the terminal window which may contain useful information on the cause of the error.

The above method somewhat impractical way of launching a program routinely. For this reason, the two commands described above are contained in a file (a "script", also called a ".bat file" on Windows systems).

When this file is executed, the commands within it are automatically carried out. Consequently, to make changes to the launch command, it is sufficient to modify the file.

6.2. Launch command arguments

The basic command has already been mentioned above. Changes to this command involve the addition of "arguments" to it. Arguments are added after the initial "java", and before the "-jar OmegaT.jar". Note that in Windows you can change the OmegaT.l4J.ini file to reflect your preferences. On Mac OS X, you can change the Info.plist located in OmegaT.app/Contents/ to do the same.

A list of possible arguments is given below. Advanced users can obtain more information on the arguments by typing man java in the terminal window.

  • User interface language

    -Duser.language=XX Normally, i.e. when OmegaT is launched without any arguments, the program first detects the language of the user's operating system. If a user interface in this language is available, OmegaT uses it. So, if the user's operating system is Russian and OmegaT has been localized in Russian, OmegaT is displayed with a Russian user interface, Russian menus, etc. If the language of the user's system is not available, OmegaT defaults to English. This is the standard behavior.

    The "-Duser.language=XX" argument causes OmegaT to use the language specified rather than the language of the user's operating system. "XX" in the command stands for the two-digit code of the desired language. To launch OmegaT with a French interface (for example on a Russian operating system), the command would therefore be:

    java -Duser.language=fr -jar OmegaT.jar

  • User country setup

    -Duser.country=XX Besides the language, you can also specify the country, for example CN or TW in case of the Chinese language. To display the instant start guide in the desired language, you need to specify both the language and the country. This is necessary even if there's only one combination available, like pt_BR in case of Portuguese / Brazil.

  • Font antialiasing - (Java 1.5 only)

    -Dswing.aatext=true This argument effects anti-aliasing of the fonts, thereby improving their appearance.

  • Memory assignment

    -XmxZZM This command assigns more memory to OmegaT. By default, 256 MB are assigned, so there is no advantage in assigning less than this figure. "ZZ" stands for the amount of memory assigned, in megabytes. The command to launch OmegaT with assignment of 1024 MB (1 gigabyte) of memory is therefore:

    java -Xmx1024M -jar OmegaT.jar

  • Proxy host IP address

    -Dhttp.proxyHost=nnn.nnn.nnn.nnn The IP address of your proxy server, if your system uses a proxy.

  • Proxy Server Port Number

    Dhttp.proxyPort=NNNN The port number your system uses to access the proxy server.

Arguments can be combined: to launch OmegaT with all the examples described above, the command would be:

java -Dswing.aatext=true -Duser.language=pt -Duser.country=BR -Xmx1024M -DDhttp.proxyHost=192.168.1.1 -Dhttp.proxyport=3128 -jar -OmegaT.jar

6.3. OmegaT in the command line mode

The purpose of the console mode is to use OmegaT as a translation tool in a scripting environment. When started in console mode, no GUI is loaded (so it will work on any console) and the given project is automatically processed as requested.

6.3.1. Prerequisites

To run OmegaT in the command line mode, a valid OmegaT project must be present. The location does not matter, since you have to add it to the command line at the start-up anyway.

If you need altered settings, the configuration files must be available. This can be achieved in two ways:

  • Run OmegaT normally (with the GUI) and specify the settings. If you start OmegaT in console mode, it will use the same settings.

  • If you can't run OmegaT normally (no graphical environment available): copy the settings files from some other OmegaT installation on another machine to a specific directory. The location does not matter, since you can add it to the command line at startup. The relevant files are filters.conf and segmentation.conf and can be found in the user home directory (e.g. C:\Documents and Settings\%User%\OmegaT under Windows, %user%/.omegat/ under Linux)

6.3.2. Starting in console mode

To start OmegaT in console mode, some extra parameters have to be passed to it on startup. The most important is <project-dir>, and optionally --config-dir=<config-dir>. Example:

java -jar OmegaT.jar /path/to/project \

--config-dir=/path/to/config-files/ \

--mode=console-translate|console-createpseudotranslatetmx|console-align

--source-pattern={regexp}

Note that all parameters start with a double - character.

Explanation:

  • <project-dir> tells OmegaT where to find the project to translate. If given, OmegaT starts in console mode and will translate the given project.

  • --config-dir=<config-dir> tells OmegaT in which directory the configuration files are stored. If not given, OmegaT reverts to default values (OmegaT dir under user home, or if not available, the current working directory). Note double - character

  • --mode=...- OmegaT starts in console mode to perform one of the following services automatically

    • --mode=console-translate

      In this mode, OmegaT will attempt to translate the files in /source/ with the available translation memories. This is useful to run OmegaT on a server with TMX files automatically fed to a project.

    • --mode=console-createpseudotranslatetmx

      In this mode OmegaT will create a TMX for the whole project, based on the source files only. You specify the TMX file to be created with

      --pseudotranslatetmx=allsegments.tmx --pseudotranslatetype=[equal|empty]

      The argument pseudotranslatetype specifies, whether the target segments are to be equal to the source, or left empty.

    • --mode=console-align

      In this mode, OmegaT will align the Java properties files found in the /source/ folder of the project to the contents found at the specified location. The resulting TMX is stored in the /omegat/ folder under the name align.tmx.

      Additional parameter is required in this case, specifying the location of the target data:

      --alignDir={location of translated files}

      alignDir must contain a translation in the target language of the project. For instance, if the project is EN->FR, alignDir must contain a bundle ending with _fr. The resulting tmx is stored in the omegat folder under the name align.tmx.

  • --source-pattern={regexp}

    When mode has been used, this option will specify the files to be processed automatically.. If the parameter is not specified, all files will be processed. Here's few typical examples to limit your choice:

    • .*\.html

      All HTML files will be translated - note that the period in the usual *.html has to be escaped (\.) as specified by the rules for regular expressions

    • test\.html

      Only the file test.html at the root of the source directory will be translated. If there are other files named test.html in other directories, they will be ignored.

    • dir-10\\test\.html

      Only the file test.html in the directory dir-10 will be processed. Again note that the backslash is escaped as well.

6.3.3. Quiet option

There is one extra command line parameter specific to console mode: --quiet. In the quiet mode, less info is logged to the screen. The messages you would usually find in the status bar are not displayed.

Usage: java -jar OmegaT.jar /path/to/project --quiet

7. Building OmegaT From Source

Note that you will need the ant program (http://ant.apache.org/bindownload.cgi) to build your own version of OmegaT. Unpack the OmegaT_2.3.x_Source.zip file and enter the OmegaT_2.3.x_Source directory or enter the ./omegat/ directory of the SVN checked out code. Please make sure that a build.xml file is present in that folder. Then, on the command line, type:

$ ant jar release

This will create a full distribution of OmegaT in the ./dist/ folder, where you will find all the files necessary to run OmegaT.