OmegaT 6.0.1 - User Manual

# How To...

## Troubleshoot issues

### Warning

OmegaT is a robust and trustworthy application, but even so, it is smart to take precautions to guard against data loss when using it, just as with any other application.

### Automatic backups

OmegaT creates backups of your project settings to ensure it can retrieve them in case of problem. See the omegat.project section for details.

OmegaT regularly and automatically stores all your progress in the project_save.tmx file located in the project’s omegat folder. OmegaT also creates regular backups of that file.

1. When you open a project, OmegaT backs up the `project_save.tmx` file to a timestamped backup file.

   OmegaT keeps up to ten of those files.

   ### Note

   The backup filename follows the pattern `project_save.tmx.YYYYMMDDhhmm.bak` where `YYYY` represents the 4-digit year, `MM` the month, `DD` the day of the month, and `hh` and `mm` indicate the hours and minutes.

2. Every time the `project_save.tmx` file is modified:

   - either after saving the project data (use Project Save C + S ),

   - or when making a regular backup (every 3 minutes by default),

   OmegaT creates a backup file named `project_save.tmx.bak`.

   That file is a copy of `project_save.tmx` before it was modified.

3. Every time you save the project data (use Project Save C + S ), or when making a regular backup, OmegaT saves the current state of the translation into `project_save.tmx`.

The `project_save.tmx` file always contains the most recent data.

### Note

You can set the frequency of the regular backups in the Saving and Output preference.

### You lost your translation?

Even if you fear you might have lost translation data, it is probably safely stored in your most recent backup memory, which is usually less than a few minutes old or so.

Proceed as follows:

1. Close the project to prevent any changes to the current status of the backup files.

2. Rename the current `project_save.tmx` file (to `project_save.tmx.tmp`, for example).

3. Select the backup translation memory most likely to contain the data you are looking for.

4. Rename it `project_save.tmx`.

5. Reopen the project.

This action will restore your translation to its state at the point the selected backup was created. You may repeat this operation as needed to find older states. Consider safely storing all the different files you are renaming for eventual reuse. Also remember not to modify the project configuration or add TMX files in the meantime, as doing so may affect the results.

### Note

Exercise caution with changes made to files in the source folder, the segmentation rules, or the file filters, partway through a project. Modifying any of those after you have started your translation could result in some segments disapparing or new segments appearing unexpectedly.

### Your project is locked?

In the rare case where your computer freezes and OmegaT does not have time to close properly, the `omegat.project` file can be locked by the operating system and keep you from reopening after you reboot your system.

Proceed as follows:

1. Identify the project folder that OmegaT refuses to open and open it in your file manager. The folder contents should be similar to a standard project folder.

2. In the folder, you should find a `omegat.project` file as well as a `omegat.project.bak` file. Make sure that the files are identical.

3. Rename the `omegat.project` file (to `omegat.project.locked` for example).

4. Rename the `omegat.project.bak` file to `omegat.project`.

5. Open the project.

This action will open the project with the automatically created backup `omegat.project` file.

### Your project won’t open?

In the rare case where your computer freezes and OmegaT does not have time to close properly, some important files can be corrupted and keep your project from reopening after you reboot your system.

Proceed as follows:

1. Create a new project with the same settings.

2. Copy the contents of the various user folders to the equivalent location in the new project (source files, reference translation memory files, glossary files).

3. In the old project, select the translation memory file (main or backup) most likely to contain the data you are looking for.

4. Rename it `project_save.tmx` if necessary.

5. Copy it to the `omegat/` folder of your new project.

6. Open the new project.

This action will set the new project the state of your translation at the point the selected project translation memory was created in the old project.

### Your translated file won’t open?

Very often, office suite files contain tags that must be copied into the translation to ensure that the translated file can be opened in the original application. In some cases, missing tags will keep the file from opening.

Proceed as follows:

1. Open the project in OmegaT.

2. Use Tools Check Issues... C + S + V and focus on Tag issues.

3. Fix all tag issues found in your documents.

4. Use Project Create Translated Files C + D to recreate the documents.

5. Open the documents again in the original application.

This action will fix any internal tag consistency issues due to not inserting tags properly while entering the translation in OmegaT.

### OmegaT won’t behave?

Something has happened and OmegaT won’t behave anymore. Whatever you try, you can’t seem to be able to fix it. You want to try one last thing before calling for help: restart OmegaT with its default settings.

Proceed as follows:

1. Use Options Access Configuration Folder to access the configuration folder.

   ### Note

   If you can’t use OmegaT’s menus, see the Configuration Folder chapter to find the configuration folder location.

2. Close OmegaT.

3. Make a backup of the contents and delete the original folder.

4. Restart OmegaT.

   ### Note

   If OmegaT does not work as expected at this point, feel free to reach out for support.

5. Close OmegaT.

6. Copy one of the old files into the new configuration folder.

7. Restart OmegaT.

   ### Note

   If OmegaT does not work as expected at this point, you have identified the faulty file. Remove it from the configuration folder and, restart OmegaT, and proceed with your work.

8. Go back to Step 5. above and continue until you are satisfied.

### Summary

- To avoid losing important data, make regular copies of the `/omegat/project_save.tmx` file to a backup medium such as a USB key, an external hard drive, or a cloud service.

- Regularly practice “emergency measures” such as restoring translations from a project to make sure you won’t lose too much time the day you need to use those skills.

## Use translation memories

When a project is initially created, it comes with its own empty project translation memory, the project_save.tmx file, located in the omegat folder. This memory is gradually filled as your translation progresses.

Existing translations are used to speed up the translation process.

- If a given sentence has already been translated once, there is no need to retranslate it. See the `Auto-propagation of translations` project property.

- If an old translation is similar to the contents of the segment you are translating, you can recycle it in your translation. See the Fuzzy Matches pane for details.

- You can also make use of reference translation memories by putting them in the tm folder of your project.

### Create your own TMs

When you use Project Create Translated Files C + D to create the target documents for a project, OmegaT also outputs three translation memories that reflect the current state of the translation for the files in the source folder. See the `Exported translation memories folder` project property for details.

Each of the three files constitutes a bilingual export of the current content of your translation. Their content comes from the global project memory (the project_save.tmx file) but is strictly limited to what you have translated so far.

You can also use the Tools Align Files... tool to create a TMX from two files in a format that OmegaT supports.

### Reuse TMs

To reuse translation memories from a previous project you have two options:

- Open the old project and put the new source files in its source folder.

  ### Note

  That’s the easiest way to work on the new version of an already translated document.

  After reloading the old project, its translation memory will be applied to the new source files. Identical segments will be automatically translated. Similar segments will be provided with matches from the project translated memory as you enter them.

- Alternatively, put the reference memories from the old project in the tm folder of the new one.

  ### Note

  That’s the preferred method if you want to start your translation from scratch.

  Depending on how reliable the memory is, you can prefer to put it in one of the following subfolders:

  - tm/enforce,

  - tm/auto,

  - tm/penalty-xxx,

  Exact matches coming from the tm/enforce and the tm/auto subfolders will be automatically inserted into the translation, without the prefix that is inserted by OmegaT when it inserts matches above a set threshold. See the `Insert the best fuzzy match` preference for details.

  Enable the `Save auto-populated status` option to have OmegaT remember that the inserted matches came from those folders.

  Use the navigation menus found in Go To Auto-Populated Segments to navigate to an automatically inserted segment.

- As reference translations, OmegaT also supports bilingual documents that are not TMX files. The file formats that OmegaT supports are all the bilingual formats that OmegaT accepts as source files:

  - PO files

  - TXML files

  - XLIFF files

  - SDLXLIFF files

  You can add such files to your project's tm folder or one of its subfolders and the translated data will be immediately be available for matching purposes.

#### Reading TMs from other tools

OmegaT can read TMX-standard compliant memories produced by other tools.

Some tools produce invalid TMX files under certain conditions. You will have to fix them if you want to use them as reference memories, otherwise OmegaT will report an error and fail to load them. Fixes are generally simple, and the error message provided by OmegaT will help you pinpoint the error. You can also ask the user group for advice if you have problems.

#### Managing your TMs

You may want to store translation memories in separate folders, by client or area of specialty so you can reuse them quickly when the need arises. Any writable folder can be used instead of the project tm folder. See the File locations section of the project property dialog.

#### Creating a TM specific to selected documents

In situations where you need to share a TMX that contain only the text from certain specific files and excludes other content, follow the procedure below:

- Copy only the documents whose content you want to include into the `source` folder of your project.

- Open the project.

- Use Go To Next Untranslated Segment C + U to find any untranslated segments (and translate them, if need be).

- Use Tools Check Issues... C + S + V to check for possible issues.

- Use Project Create Translated Files C + D to create the TMX files that correspond to the current contents.

The TMX files located in the exported translation memory folder now contain only the original and translated text from the files you copied into the source folder, in the selected language pair. See the `Exported translation memories folder` project property for details.

### Share TMs

For large jobs involving a team of translators, it is easier for everyone involved in sharing common translation memories rather than pass local versions back and forth.

There are two ways to share translation memories:

The good enough way

  See the Create your own TMs section above.

  If you write the TMX file to a folder on a shared disk, you can ask your partner to assign that folder as the tm folder for the current translation.

  Conversely, you can ask your partner to write the project TMX files to a folder on a shared disk that you will assign as your tm folder for the current translation.

  OmegaT instantaneously recognizes modifications to TMX files. Therefore, any time one side creates or modifies such a TMX using Project Create Translated Files C + D , the other side does not need to do anything to have that TMX recognized locally.

  This approach also works just as well for sharing glossaries where the project writable glossary (with a non-default name to avoid overwriting the file) is located in a shared glossary folder. See the Glossaries appendix for details.

  ### Note

  This approach to sharing works well when the lag between TMX updates is not important: a translator sending data to a reviewer a few times a day, for example.

The technical approach

  OmegaT uses collaborative version control systems to share data.

  Such systems are free to use, install and manage and are widely used in the computer development world, making them extremely robust.

  See the Set up a team project how-to for details.

### Warning

Be cautious when you put a whole project in a file-sharing system like DropBox, OneCloud and the likes.

Such systems are not designed to keep track of the internal modifications of a given file.

An OmegaT project is a complex set of files. Such systems will not always be able to provide you with the most recent version of your data, may even lock some files for no obvious reasons and can even corrupt team project related files.

Make sure that you have properly tested your project layout and set up a separate data backup before sharing data in such a system.

### Bridge two languages

OmegaT displays fuzzy matches in the Fuzzy Matches pane. By default, those matches are limited to the source and target languages defined in the Project Properties dialog.

You can add matches in languages that are not the target language. See the `Include matches from other languages` preference for details.

If you have a TMX that corresponds to your source document and contains its translation to a different language, you can also display that language right below the source segment for use as an additional reference language.

To achieve this:

1. Copy the translation memory containing the additional reference language into `tmx2source` in the tm folder.

2. Rename the memory file to:

   - `LL_CC.tmx`,

   - `LL-CC.tmx`, or

   - `LL.tmx`,

   where LL is the internal language code of the langage that you want to display as reference, and CC is an arbitrary 2-letter code.

   ### Warning

   - All the letters must be capital letters.

   - Only segments that match the source exactly are displayed.

Example 6. Using a Japanese reference under the English source

If you have a TMX that contains the Japanese translation of an English document you are translating to French, you can use the Japanese translation as an alternative exact reference by displaying it under the English text to translate.

Just put the English-Japanese file in `tm/tmx2source` under the name `JA-JP.tmx`. OmegaT will now show you the Japanese text corresponding to the English source segment:

    — ¶ —————————————————————
    A whitespace character: [ \t\n\x0B\f\r]
    ja-JP: 空白文字：[ \t\n\x0B\f\r]
    Un caractère d'espacement : [ \t\n\r\f\x0B]<segment 3075 ¶>
    — ¶ —————————————————————

The first line is the original English, the second line is the bridge language you expect to find useful when you create your translation, and the third line is the current translation to French.

### Note

You can use any number of TMX files containing as many different bridge language pairs as you want.

## Support other formats

OmegaT's file filters provide a wide range of support for common and less common file formats. If you need to support formats that are not covered by OmegaT, there are four ways to do so:

- Associate the format to an already supported format.

- Convert the format to an already supported format.

- Extend OmegaT with third-party plugins that support the format.

- Develop a filter for the format.

### Association

File filters have a list of file extensions that are associated to them. If the format you want to translate is structurally close to an already supported format, just add its file extension to the supported format extension list, or change the file extension to one that is accepted by the file filter that you want to use. See the File Filters chapter for details.

You can also use OmegaT's custom tag function to register format specific strings and have OmegaT handle them as if they were normal tags. See the `Custom tags` preferences for details.

### Conversion

To ensure that all the properties of a format are properly taken into account, it is sometimes preferable to convert the file to a supported format and then convert the translated file back to the original format.

A number of free software third party utilities provide such “round-trip” conversion, including:

- Rainbow, from the Okapi Framework

  License: Apache License Version 2.0

  The Okapi Framework comes with a number of file filters, including some not supported natively by OmegaT. See List of file filters for details.

  Rainbow can create XLIFF 1.2 compliant files or OmegaT projects from all the files set as “input” files. Rainbow-supported files are converted into XLIFF and inserted as source files into a full fledged OmegaT project that you can open with OmegaT right away. See Rainbow TKit - OmegaT Project for details.

- po4a

  License: GNU General Public License v2

  po4a supports a number of free software documentation formats, listed on the site front page, and offers conversion tools to and from the po format. See the PO files section for details.

- The converters from the Translate Toolkit

  License: GNU General Public License v2

  The Translate Toolkit offers a number of convertion tools to and from the po format. See Converters for details.

- OpenXLIFF from Maxprograms

  License: Eclipse Public License v1.0

  OpenXLIFF supports a number of file filters, including some not supported natively by OmegaT. See OpenXLIFF Filters for details. Maxprograms also distributes XLIFF Manager, a graphical user interface for the OpenXLIFF Filters.

  OpenXLIFF produces XLIFF 1.2 compliant files.

Some formats, like PDF, cannot be properly handled through “round trip” conversions. They require an intermediate conversion to a supported format that serves as a base to manually create a proper target language document.

You can find a number of online or offline utilities that convert PDF to common office formats, but the conversion will always require extensive manual adjustments to the target document before a proper PDF document can be produced. Make sure you understand the format requirements when you start working on a PDF or similar file.

### Third-party plugins

- The Okapi Filters Plugin for OmegaT, from the Okapi Framework

  License: Apache License Version 2.0

  Not all of the Okapi Framework file filters are included into the file filter plugin. See Filters Included for details.

  When installed, the plugin offers direct access to the added formats and also allows you to associate a custom filter parameters file created in Rainbow. See above.

Other plugins for less common formats are listed on the OmegaT wiki. See Plugins.

### Development

OmegaT provides developers with thorough documentation to create file filter plugins. See How to create a file filter plugin for OmegaT for details.

## Set up a team project

Managing a team project calls for some knowledge of either the SVN or Git version control system ( VCS in the rest of this section).

As information on those topics is readily available, this manual limits itself to describing their use in the context of an OmegaT team project.

### Note

An OmegaT team projects synchronizes the project translation memory project_save.tmx and the project writable glossary glossary.txt between the hosting server and all the participating team members, and manages all possible conflicts between them.

### Preparations

Here are the steps to set up a team project:

1. Create an empty repository on your VCS hosting server

   This can normally be done through a web interface, a graphical application, or the command line. Consult the documentation for your server or hosting service for details.

2. Use the local VCS to make a local copy (clone)

   ### Note

   This local version contains your project manager copy of the OmegaT project. Use it to make modifications that affect the entire team.

   The local repository is used to add the initial project to the server, and can also be used for maintenance tasks, such as deleting files, that cannot be performed directly within OmegaT.

   We recommend that you avoid using that folder for translation tasks. If you need to perform translation or review tasks on that project, use OmegaT to download a separate copy of the team project and work from there. See the Use a team project how-to for details.

3. Fill the empty local copy with a real OmegaT project

   - Create the project structure

     If you are creating a new empty project, you can follow the GUI procedure, or create it directly from the command line: java -jar OmegaT.jar team init <source language> <target language>

     This command also automatically registers the project in the version control system.

   - Choose the appropriate settings

     Make the necessary changes to the project properties at this stage, including local file filters or segmentation settings. See the Project Properties dialog for details.

   - Add the necessary files

     Similarly add any relevant lists of spellchecker files you want to make available to everyone working on the project. See spellchecker files for details.

     If you are converting an existing project, make sure you delete any files in the project that you do not need or want to upload to the server before proceeding to the next step.

     Copy the files to translate to the source/ folder, and use your SVN or Git client, or the command line, to add and publish them to the repository. Use Project Commit Source Files to add files from OmegaT.

     You must use your SVN or Git client, or the command line, to add and publish any dictionaries, glossaries, translation memories or other files you want to include in the project.

     This step can be performed before the registering and publishing the project for the first time, and can also be used to add new files, or update existing ones after the project has been created.

   ### Note

   In team projects that use a simple mapping between the local repository and the remote repository (the default), and only in such projects , the source and target files can be modified locally and uploaded to the server using Project Commit Source Files and Project Commit Target Files .

   The team project administrator must use the local VCS to modify or delete those files. Some plugins can make this task easier. See the Plugins preference for details.

4. Register the project files into the local VCS

   If you created the project from the GUI, you then have to explicitly add it to the version control system ( add in both SVN and Git).

5. Put the registered files on the hosting server

   Finally, publish your project to the remote server ( commit in SVN, commit and push in Git).

6. Give access rights to your team

   ### Note

   If you use multiple projects on the same server, credentials will only be asked once for that server.

   After the project is ready and has been uploaded to the server, the team project administrator has to set up access for the translators. Accessing a team project requires the following information:

   1. Projects on a hosting service

      The translators will have to create an account for the service, and send their user name to the team project administrator.

      The administrator will then grant write access to the repository to those accounts.

   2. Projects on a self-hosted server

      If the server is self-hosted and does not have a provision for translators to register an account themselves, the team project administrator must create accounts with write access for the translators.

      After creating the accounts, the administrator must send the translators their individual credentials.

7. Have everybody download the project from OmegaT

   Administrators have two options for sending the location of the project to the translators:

   1. Send a URL and ask the translators to use Project Download Team Project... to create a local copy of the project on their own system.

   2. Send an `omegat.project` file containing the project URL, and then have the translators copy it to an empty folder and open it in OmegaT. This can be useful if the project is set up to use different mappings for each translator.

   After the team project administrator confirms that a translator has been able to open the team project, it is a good idea to make sure that the project statistics are the same for both the administrator (on the server) and the translator (locally).

   If they do not match, make sure the `filters.xml` and `segmentation.conf` files are properly shared.

8. If you need to work on the project too, download the project yourself to a local location different from the local team project location

9. You can now also work on the project with the team

### Repository mappings

It is possible to map various remote locations to local files via the OmegaT user interface using Repository Mapping... in the Project Properties dialog, or by editing the omegat.project file. Although the mapping feature is primarily intended for gathering source files from disparate locations, it can also be used for other types of files.

A list of mapping parameters is presented below, and examples of their use are provided in the next section.

repository type

  This can be either http (which includes https), svn , git , or file .

repository url

  Remote location or folder of the files to translate.

mapping local

  Name of the local folder or file, relative to the root of the OmegaT project.

mapping repository

  Name of the remote folder or file, relative to the repository url.

excludes

  Use wildcards (following the Apache Ant style: *, ?, **) to add patterns for files that should not be part of the mapping. Use a semicolon to separate different patterns.

  Example: `**/excludedfolder/**;*.txt` excludes files that have /excludedfolder/ in the path, as well as files with the `.txt` extension.

includes

  As above, but for files that should be part of the mapping. Since files are included by default unless specifically excluded, this option is only necessary to specify exceptions to an exclusion pattern.

  Example: `**/*.docx` to add all .docx files in the project, even if they are located in an excluded folder.

### Example mappings

Default project mapping:

    <repository type="svn" url="https://repo_for_OmegaT_team_project">
    	<mapping local="" repository=""/>
    </repository>

All the contents of `https://repo_for_OmegaT_team_project` are mapped to the local OmegaT project

Mapping for projects in a subfolder of the repository:

    <repository type="svn" url="https://repo_for_All_OmegaT_team_projects">
    	<mapping local="" repository="En-US_DE_project"/>
    </repository>

All the contents of `https://repo_for_All_OmegaT_team_projects/En-US_DE_project` are mapped to the local OmegaT project.

Mapping for additional sources from a remote repository, with filters:

    <repository type="svn" url="https://repo_for_All_OmegaT_team_project_sources">
    	<mapping local="source/subdir" repository="">
    	    <excludes>**/*.bak</excludes>
        	<includes>readme.bak</includes>
    	</mapping>
    </repository>

Everything in `https://repo_for_All_OmegaT_team_project_sources` is mapped to the local OmegaT project source folder, except files with a `.bak` extension. However, the `readme.bak` is also included.

Mapping for extra source files from the web:

    <repository type="http" url="https://github.com/omegat-org/omegat/raw/master/">
    	<mapping local="source/Bundle.properties" repository="src/org/omegat/Bundle.properties"/>
    </repository>

The remote file `https://github.com/omegat-org/omegat/raw/master/src/org/omegat/Bundle.properties` is mapped to the local file `source/Bundle.properties`.

Mapping with renaming:

    <repository type="http" url="https://github.com/omegat-org/omegat/raw/master/">
    	<mapping local="source/readme_tr.txt" repository="release/readme.txt"/>
    </repository>

The remote file `https://github.com/omegat-org/omegat/raw/master/release/readme.txt` is mapped to the local file `source/readme_tr.txt`.

This makes it possible to rename the file to translate.

Local file mapping:

    <repository type="file" url="/home/me/myfiles">
    	<mapping local="source/file.txt" repository="my/file.txt"/>
    	<mapping local="source/file2.txt" repository="some/file.txt"/>
    </repository>

The local file `/home/me/myfiles/my/file.txt` is mapped to the local file `source/file.txt` and `/home/me/myfiles/some/file.txt` is mapped to the local file `source/file2.txt`.

### Warning

The project will not load if a file specified in a mapping does not exist.

You can add as many mappings as you want, but one of the mappings must include the `omegat.project` file.

### Selective sharing

The above process describes the most common scenario, in which the team project administrator has full control of the project and all files (and statistics) are identical in all instances of the project, both on the server and the local systems of the translators.

It is also possible to use a team project configuration where several translators share the `project_save.tmx` file, and only a subset of the other files.

The basic procedure is essentially the same, except that the team project administrator does not add every file to the version-controlled project on the server. The remaining files are either copied by the translators themselves, or mappings that synchronize files from other locations are defined.

## Use a team project

Team projects use synchronization mechanisms between project members.

Once a OmegaT team project is installed on a server, the administrator sends members the information they need to access it: a URL indicating the location of the project, or an `omegat.project` file.

After the project is downloaded, it is installed locally and only needs to be opened locally to synchronize with the server.

Repository credentials are stored in the repositories.properties file and can be deleted from the `Repository Credentials` preferences.

Since synchronization takes place by default every three minutes, project members will sometime translate or modify a segment that has already been translated by another member but not synchronized yet. When that happens, members have to select the appropriate translation.

Members can take turns translating and reviewing the files. The Search function allows them to filter the Editor pane on contents translated by a given person, or on contents translated after or before a given time, for example.

Downloading the project

  1. From a URL

     Use Project Download Team Project... to bring up the Download Team Project dialog.

     Enter the URL provided by the team project administrator in the Repository URL: field at the top of the dialog, and specify a folder for the project in the New Local Project Folder: field. Leave the Default branch option checked unless the project administrator has provided instructions for using a custom branch.

  2. From an `omegat.project` file

     Put the `omegat.project` file in an empty folder, and open it in OmegaT. The project will automatically be downloaded to the folder containing that file.

  ### Note

  Servers generally use two main types of authentication: entering a username/password , or SSH .

  If the server relies on username/password authentication, OmegaT will present you with an Authentication dialog to enter your username and password either when you first download the project or later on in the process. OmegaT will then remember your credentials for that specific project unless you explicitly delete them. See the `Repository Credentials` preferences for details.

  If the server uses SSH authentication, make sure you update your SSH configuration to include that server before attempting to download the project, otherwise you will get an authentication error and the project will fail to load.

  If you use multiple projects on the same server, credentials will only be asked once for that server.

Synchronization

  Synchronizing the project adds translations made by all team members to local copies of the project. Only the contents of the two following files are synchronized:

  - `project.save`

  - `glossary.txt`

  During synchronization, all other local files are overwritten with the versions on the remote server, exept for `omegat.project` (see below).

  OmegaT synchronizes a team project when it is opened, reloaded, closed or saved. This means the automatic save function also regularly synchronizes local versions with the version on the server at the interval specified in the `Project data saving interval` preference.

Team project configuration

  As in regular local projects, the configuration of the team project is defined by the contents of the `omegat.project` file and the optional use of special files for project-specific filters or segmentation rules.

  The first time the project is downloaded, OmegaT retrieves the `omegat.project` file from the server. This file defines the following parameters:

  - Basic project configuration: Source and languages, tokenizers, and the project folder hierarchy.

    In a team project, the basic configuration parameters of the local project are always overridden by the configuration on the server originally set by the project administrator.

  - Repository mappings

    See the Repository mappings how-to for details.

    - If no custom mappings have been defined for the remote project, but local mappings have been customized, the local settings are preserved without affecting the settings on the server.

    - If the remote project contains custom mappings, but the local project does not, the mappings from the server are applied to the local project.

    - If the remote project specifies a URL protocol and you download it using a different protocol, your local configuration will be preserved.

      For example, many hosting services support access to the same repository using either the SSH +Git or https protocol. OmegaT will respect the local protocol selection.

    - If you first download the remote project using an `omegat.project` file provided by the project administrator, OmegaT will use the mappings in that file, if any.

    - If there is a conflict between the remote and local versions of the `omegat.project` file and the local version is overwritten, OmegaT creates a backup file called `omegat.project.YYYYMMDDhhmm.bak`. OmegaT creates up to ten backup files, and older backups are automatically deleted in turn.

  ### Warning

  Remember that any modifications to the local project configuration files will be overwritten by the versions on the server when the project is synchronized.

Source files

  ### Warning

  Only the project administrator should use Project Commit Source Files .

Target files

  After you generate the target files use Project Commit Target Files to add them to the server, if the project administrator has requested you to do so.

Deleting files

  Files in a team project cannot be deleted from OmegaT or the local file system. They will be restored the next time the project is synchronized. This task is normally performed by the project administrator.

Working offline

  You can open a team project and work on it offline. All changes will be synchronized the next time a connection is available.

  There are two ways to work offline:

  - Disconnect from the network before opening the project.

  - Open the project from the command line with the `--no-team` option. See the Command line launch section for details.

## Install OmegaT

OmegaT comes in two editions:

Standard: OmegaT 6.0.1

  This edition is recommended for everyday use.

Developer: OmegaT Nightly

  This edition is automatically generated every time new code is added to OmegaT. It is used for testing purposes.

The files are downloadable directly from https://omegat.org.

### Note

OmegaT 6.0.1 requires a Java 11 Runtime Environment (JRE) to run.

OmegaT packages are available both in versions bundled with Java, and versions without it. Packages without Java rely on a Java 11 Runtime Environment installed systemwide.

OmegaT 5.8.0 and later can also run with Java 11 Runtime Environment on any platform.

Due to licensing considerations, the OmegaT team recommends the Eclipse Temurin Java runtime provided by the Eclipse Foundation's Adoptium Project, but any Java 8 compatible runtime environment should work. See The Eclipse Temurin™ project.

IBM provides JREs for Linux PowerPC at https://developer.ibm.com/languages/java/semeru-runtimes/downloads/.

### On Windows

Double-click on the package you downloaded.

You can choose the language used during the installation and the language used by OmegaT. You can also change this later by editing the `OmegaT.l4J.ini` file.

### On Linux

Some Linux distributions offer OmegaT in their package manager. The instructions given here apply to people who download the package from the https://omegat.org site and install it manually.

Unpack/untar the file you downloaded. This creates a new folder named after the package you downloaded. That folder contains all the files needed to run OmegaT.

### Note

Although you can run OmegaT directly from the available files, you can also run the `linux-install.sh` script found there to have OmegaT installed in more appropriate locations.

Running the script will require you to enter your `sudo` password.

The script checks for an existing installation of the same OmegaT version in `/opt/omegat/`. If there isn’t one, it installs the program in `/opt/omegat/OmegaT_6.0.1` and sets it as the default version (in `/opt/omegat/OmegaT-default`).

After the unpacking or installation is complete, you can delete the downloaded file as it is no longer needed.

### On macOS

Double click on the package you downloaded to unpack it. This creates a folder called `OmegaT`. The folder contains two files: `index.html` (the user manual entry file) and `OmegaT.app` (the application). Copy the folder to a suitable location (e.g. `Applications`).

If so desired, drag and drop `OmegaT.app` onto the Dock for easier access.

Once you have done this, you can delete the downloaded package as it is no longer needed.

### On other platforms

This information applies to any system for a Java version compatible with Java 11 Runtime Environment is available. That includes the platforms described above, as well as platforms for which no specific OmegaT package is provided.

Download the Cross-platform without JRE version.

Unpack the file that you downloaded. This creates a folder with all the files necessary to run OmegaT.

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

### Upgrade

OmegaT can tell you when a new version is available. See the Updates preference for details.

The changes between your version and the current version are documented in the development site’s changes.txt file.

### Note

If you decide to install a new version, keep the following in mind:

- OmegaT’s preferences are stored in the configuration folder and will not be modified by the new version. See the Configuration Folder chapter for details.

- Projects that you have created in the past or are currently using will not be modified or deleted. OmegaT projects are not stored inside OmegaT. They are separate objects that have no physical connection to the OmegaT application itself.

- Parameter files that are included in the downloaded OmegaT package (especially the `OmegaT.l4J.ini` for Windows and the `Configuration.properties` and `Info.plist` files for macOS packages) might be overwritten or deleted, so you may want to create a backup before upgrading, if you have been using these files to modify OmegaT’s launch parameters.

- The `plugins` and `scripts` folders might be overwritten, so you may want to create a backup before upgrading.

Over an existing version

  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 settings made from the OmegaT interface will be retained in the various configurations folders (see above).

Alongside an existing version

  This will enable you to keep any number of versions side-by-side, which you may wish to do until you feel comfortable with the new version.

  All the parameters located in the OmegaT configuration folder will be shared unless you specify a different configuration folder with the `--config-dir=<path>` option on the command line. See the OmegaT options section.

  All the parameters located in a project folder will apply to that project regardless of which version of OmegaT opens it.

### Delete OmegaT

Use your operating system’s standard procedure to remove OmegaT. If you want to remove OmegaT completely, you will also have to delete the configuration folder.

If you performed a manual installation on Linux, you will have to manually delete the OmegaT folders in `opt/`, as well as the symlinks placed in `/usr/local/bin/` by the installation script.

### Build OmegaT

The source code for the current version can either be downloaded directly from the OmegaT download page, or cloned from the Sourceforge or GitHub repositories.

Once the code is downloaded, open a terminal in the source folder (`omegat-code/` if you cloned from Sourceforge, or `/omegat` if you cloned from GitHub) and type:

    ./gradlew installDist

This will create a full, ready to launch distribution of OmegaT in the `build/install/OmegaT` folder.

You can also run the application directly with the following command:

    ./gradlew run

You can get a list of all available tasks by typing:

    ./gradlew tasks

Detailed instructions on building OmegaT can be found in the README.txt file located in the `docs_devel` subfolder.

## Run OmegaT

### On Windows

The simplest way to launch OmegaT is to execute the `OmegaT.exe` program. The options for the program start-up 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 1 GB 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

Advice: if OmegaT works slowly in Remote Desktop sessions under Windows, you may use this option:

    -Dsun.java2d.noddraw=false

### On Linux

You can launch OmegaT from the command line with a script that includes start-up options. See the Command line launch section for details.

You can also double-click on `OmegaT.jar` to launch it directly if the `.jar` extension is associated with the system Java launcher.

The package also provides the `omegat.kaptn` Kaptain script, which KDE users might find useful, as well as an `OmegaT` bash script that automatically launches the appropriate java command to run OmegaT.

### On macOS

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

`OmegaT.app` comes with an `OmegaT` executable located in `OmegaT.app/Contents/MacOS/` that you can also use to launch multiple instances of `OmegaT.app`.

And it also comes with the generic `OmegaT.jar` file located in `OmegaT.app/Contents/MacOS/Java/` that you can use to launch OmegaT from the command line. See the Command line launch section for details.

You can modify the behaviour of OmegaT.app by editing the `Configuration.properties` (OmegaT configuration) as well as the `Info.plist` (Java configuration) files located inside the OmegaT.app package.

The `Configuration.properties` file is located in the `Contents/Resources/` folder.

The `Info.plist` file is located in the `Contents/` folder.

### Note

To access the files inside the `OmegaT.app` package, right-click on `OmegaT.app` and select “Show Package Contents”.

It is also possible to use `OmegaT.app` itself to launch OmegaT from the terminal. See the Command syntax section below for details.

Use your text editor of choice to modify the files.

Configuration.properties

  For predefined options, remove the `#` symbol before a parameter to enable it. For example, `user.language=ja` (without the `#`) will launch OmegaT with the user interface in Japanese.

Info.plist

  For example, to change the amount of memory available uncomment the line

  `<!-- <string>-Xmx6g</string> -->`

  by removing the `<!--` and `-->` markers.

  This will launch OmegaT with 6 GB of memory; change the `6g` to the desired amount.

### Note

`OmegaT.app` can make use of macOS Services. You can also use AppleScript, Automator or Shortcuts to create Services or scripts that will automate frequent actions.

### On other platforms

Methods vary from one system to another, but in general, once OmegaT is installed, you can launch it directly from the command line. See the Command line launch section for details.

You can create a script that includes the desired command line launch parameters. If `.jar` files are properly associated with the Java 11 Runtime Environment and your PATH settings are correct, you can also simply click (or double-click) on `OmegaT.jar` to launch it directly.

Consult the documentation for your system for more information.

### Command line launch

Using the command line allows you to set various options that control or modify the behaviour of the application. You can also define and save sets of options in scripts that you can then use to launch OmegaT for a particular purpose.

Launching OmegaT from the command line also creates a new OmegaT instance for each launch. You can thus use multiple projects simultaneously, each with its own parameters.

#### Simplified Overview

Before graphical interfaces became common, users interacted with computers via a command-line interface (CLI), which requires typing commands to give instructions to the computer. On modern systems, the CLI is accessed through an application generally called a "terminal" or "console". For the sake of simplicity, this manual refers to it as the terminal.

On Windows, you can use either the Command Prompt or Powershell as a terminal. Both are available from the System Tools folder of the Start Menu.

The macOS equivalent is the Terminal application located in the `Utilities` folder of the `Applications` main folder.

On Linux, the default terminal application for your distribution should be available from the application menu or one of its submenus.

In the terminal, you type commands and their associated parameters to perform tasks. This makes it easy to perform certain tasks that would be difficult to perform using a graphical interface.

### Note

The syntax used to specify the location of an application or folder depends on the platform. On Windows, the `\` character is used to separate folder and file names, while macOS and Linux use the `/` to do so.

Here are the default OmegaT.jar locations for each major platform:

Windows

  `C:\Program Files\OmegaT\OmegaT.jar`

Macos

  `/Applications/OmegaT.app/Contents/Java/OmegaT.jar`

Linux

  `/opt/omegat/OmegaT.jar`

  (This can vary depending on your distribution.)

That location is presented as `path/to/OmegaT.jar` in this chapter. Replace it with the actual location of the file on your system.

#### Command syntax

The syntax to launch OmegaT from the terminal is:

    java -jar <java parameters> path/to/OmegaT.jar <OmegaT options>

### Note

On macOS, it is also possible to use `OmegaT.app` directly in the terminal, in which case java parameters cannot be added:

    open path/to/OmegaT.app
    		-n --args <OmegaT options>

where `-n` is used to create a new instance of OmegaT.

`java -jar`

  This command tells the Java Virtual Machine to run a Jar package.

`<java parameters>`

  Optional parameters accepted by the java command. The parameters relevant to running OmegaT are described below.

`path/to/OmegaT.jar`

  The location of the OmegaT java executable.

`<OmegaT options>`

  The options specific to OmegaT are described later in this section

#### Java parameters

The list below presents parameters for the java command that can be useful when working with OmegaT.

User interface language

  `-Duser.language=LL`

  Replace `LL` with the desired two-letter language code from the ISO 639.1 list.

  Using this parameter launches OmegaT with the user interface in the specified language, if available (even partially). If the language is not available, OmegaT defaults to English even if the system uses a different default language.

User country

  `-Duser.country=CC`

  Replace `CC` with the desired two-letter country code from the ISO 3166-1 alpha-2 list.

  This parameter combines with the previous user interface language parameter to specify a regional variant. If that variant is not available, the user interface follows the same priority as above.

Maximum memory assignment

  `-XmxSIZE`

  Replace `SIZE` with a number consisting of a multiple of 1024 followed by `k` for kilobytes, `m` for megabytes, or `g` for gigabytes. The number must correspond to at least 2 MB.

Proxy host ip address

  `-Dhttp.proxyHost=<proxy IP>`

  Replace `<proxy IP>` with the IP address of your proxy server, if your system uses one.

Proxy host port number

  `-Dhttp.proxyPort=<port number>`

  Replace `<port number>` with the port number your system uses to access the proxy server.

#### OmegaT options

You can also get a list of these options in the terminal with the java -jar OmegaT.jar --help command. The OmegaT GUI is launched if no option is specified.

General options:
  `-h`, `--help`

    Show usage information.

  path to an omegat project

    Launch the GUI and load the specified project

  `--remote-project` <path-to-omegat-project-file>

    Download the OmegaT project from the URL specified in <path-to-omegat-project-file> , and load it.

  `--no-team`

    Disable team project functionality. Use this option if you want to prevent OmegaT from synchronizing the project contents.

  `team init SL TL`

    Initialize a team project using SL and TL as the source and target two-letter language codes, respectively.

  `--disable-project-locking`

    Do not lock the omegat.project file.

    On some platforms, the omegat.project file is locked by default and attempting to open an already open project in another instance of OmegaT results in an error. This option prevents that error.

  `--disable-location-save`

    Do not remember the last folder opened in the file picker.

  `--ITokenizer=<classname>`, `--ITokenizerTarget=<classname>`

    Specify a source- or target-language tokenizer (using this option overrides project settings). See OmegaT.jar/META-INF/MANIFEST.MF for valid values.

  `--config-dir= <path>`

    The folder used to read and write OmegaT configuration files. See the Configuration Folder chapter for details.

  `--config-file= <path>`

    A file written in the Java .properties format used to specify a batch of command line options.

    The options are presented as a list of `key=value` pairs. Both Java parameters and OmegaT options can be used.

    ### Note

    Remove the initial `-D` or `-X` to use Java parameters:

        user.language=fr
        config-dir="path/to/new/configdir"

    Almost all parameters presented in this section can be used in a config file. The notable exception is `remote-project`.

    It is possible to combine `--config-file` with other command line options compatible with launching the GUI. In such cases, options defined in the config file take precedence over any option with duplicate functionality also passed on the command line.

  `--resource-bundle= <path>`

    A Java .properties file to use for interface text.

  `--mode=[console mode name]`

    Specify a mode other than the GUI default. The following options are available:

    `--mode=console-translate`

      In this mode, OmegaT attempts to translate the files in the source folder with the available translation memories.

      This is useful if OmegaT is run on a server with TMX files automatically fed to a project.

      `--source-pattern=<pattern>`

        An allowlist of regular expressions defining the source files to process. Remember that in regular expressions, the period and backslash character must be escaped: `\.` and `\\`.

        Here are some typical examples:

        `.*\.html`

          Translate all HTML files.

        `test\.html`

          Only translate `test.html` file in the source folder itself. Any files also named test.html in other subfolders will be ignored.

        `dir-10\\test\.html`

          Only translate the `test.html` file in the `dir-10` folder.

        See the Regular expressions appendix for details.

    `--mode=console-createpseudotranslatetmx`

      In this mode OmegaT will create a TMX for the whole project using only the source files.

      Specify the TMX file to be created with:

      `--pseudotranslatetmx= <path>`

        The output pseudotranslated TMX file.

      `--pseudotranslatetype=[equal|empty]`

        What to fill the pseudotranslated TMX with.

    `--mode=console-align --alignDir=<path>`

      In this mode, OmegaT will align the files in the /source folder of the project with those at the location specified by the --alignDir parameter.

      The resulting TMX file is saved in the /omegat folder as align.tmx. The file types that can be aligned depend on whether the alignment is supported by the file filter. Supported filters include: ILIAS Language File, Java(TM) Resource Bundles, Key=Value Text, Magento CE Locale CSV, MoodlePHP, Mozilla DTD, Mozilla FTL, PO, RC, SubRip Subtitles, and Windows Resources.

      The --alignDir parameter is used to specify the location of the data in the target language, which must be a folder containing the translated files.

      That folder must contain a translation in the target language of the project. For instance, if the project is EN-to-FR, the folder must contain a bundle ending with _fr. The resulting TMX file is saved in the /omegat folder as align.tmx.

    `--mode=console-stats <path>`
      `--output-file=[stats-output-file]`

        Prints to that file, or to standard output if absent. Without --stats-type , detects format from file extension. The output defaults to xml.

      `--stats-type=[xml|text][txt][json]]]`

        Requires --output-file . Specifies the output format.

      The data is the same as when using Tools Statistics .

Non-gui mode options:
  `--quiet`

    Minimize the output shown on the command line.

  `--script= <path>`

    A script file to run when a project event is triggered.

  `--tag-validation=[abort|warn]`

    Check tag issues.

    - Abort: Exit with an error if there are tag issues.

    - Warn: Show warnings without exiting if there are tag issues.

    ### Note

    Reports about tag issues are output to the terminal window.