OmegaT+ Localization Guide

What Localization is

Localization, for translation purposes, is the process of translating textual resources and related from one locale into another. This includes the localization of documents, software, and so forth. For the purposes of this document we are only concerned with the software localization of the OmegaT+ user interface.

What a Locale is

In general, a locale is any place with its specific languages and cultural customs. In regard to software localization, a Locale (captalized in this document to emphasize its difference from the general definition) is a type of indicator that the program uses to know what localization resources to use and how to present them to users for a particular locale. A Locale is typically defined with regard to the language and country for which it is to be used. Thus, a software application uses a specific code in various ways as an indicator to help it determine what the language and other specifics are. Resources for a particular locale are then used in the presentation of the program's user interface.

How Localization works in OmegaT+

Localization resources for OmegaT+ are contained in plain text documents of key/value pairs, known as a Java resource bundles (.properties files). These documents are contained in a specific OmegaT+ installation location that is easily accessible to users (an exception being when there is a system-wide installation that requires administrator access to alter files). A user merely copies documents in or out of the location in the process of adding new localizations or performing localization, respectively.

The fact that OmegaT+ uses documents with key/value pairs is a detail that will not usually be of concern when localizing a .properties file in OmegaT+ itself. During translation of the resource bundle's segments, superfluous information pertaining to key/value pairs will not be presented in OmegaT+. Translation will proceed as with other supported document formats.

Once localization of the resource bundle is completed the corresponding translated .properties file is copied back into the OmegaT+ installation and OmegaT+ is restarted under the proper locale to enable its use. To present a particular locale to a user of the application the Locale for the resources must either be the computer's system default or be forced to use a Locale other than the default--forcing the Locale to a different one is usually done for testing or in those cases where the user's default Locale differs from that which they want to use.

In summary, to localize OmegaT+ all that is necessary is to create a project, obtain the appropriate resource bundle, open it in the project, translate, generate the translated resource bundle, put the translated document back into the OmegaT+ installation, and then restart OmegaT+ under the proper locale.

Basic Requirements

Java

OmegaT+ is a Java application. You must have it installed before proceeding. See the OmegaT+ user documentation for details.

OmegaT+

OmegaT+ should be installed and you should already know how to use it before you attempt to localize its user interface. Read the OmegaT+ user documentation first.

OmegaT+ Resource Bundles

To localize OmegaT+ requires that you have the Java resource bundle (.properties file) to put in a project. OmegaT+ comes with a default English localization and a few others are either in progress or just starting to be added at this time. There is no requirement that you must translate from English only.

If there is a different localization resource bundle available to start from it can be used. The only precaution at this time is that English is the only one to be guaranteed near completion. To translate from another language, given a resource bundle for it, might result in wasted effort if the particular Locale ends up having significant changes propagated to it due to the base English changes. Please ask about particular Locales for localization before you start, so that you don't end up doing extra work for nothing.

In any event, this situation is being addressed and in the future the different localizations will be reconciled against one another so that translators can use whatever is available without significant problems.

Localization License and Copyrights

All the localizations in OmegaT+ are released under the GPL version 3+ license (which means GPL 3 or any later version of GPL). If you plan on including your localization into OmegaT+ for distribution then all the translations made for the localization must also be under the same license or a compatible one. Submitters of localizations to OmegaT+ retain their copyrights as well as licensing the work under GPL v3+. Contact the project if more details are needed.

OmegaT+ Localization

Localization of OmegaT+ is a fairly straightforward process and steps have been taken in this recent version to make it easier for localizers to translate the user interface text and test the results for themselves without needing to do any computer programming related activities, mess around with file activities other than copy/paste, or waiting for project developers to test it for them. You can see your localizations in the user interface soon after you have created them.

Terminology

OmegaT+ uses terminology that translators may not be used to from using other CAT tools. This is intentional in most cases. There still may be places where these can be made clearer, as this is a work in progress.

Please do not localize those CAT related terms into something that is not exactly like what is in the original resource bundle (e.g., to a term that seems more like what another tool would have, or that you are more used to). There are reasons for not using the de-facto terms that you may not understand at first.

Discuss the differences in terminology with us before drastical changing them in the localization. OmegaT+ needs to present a consistent user interface across all localizations. This will not happen if one langauge uses one set of terms compared to another one. It would not be very professional to have such differences.

One of OmegaT+'s goals is to be simple to use, to do that things must be clear and logical. Another goal is to do things in a unique and better way. The use of some of its own terminology is one way towards those ends.

Create Project

Add Resource Bundle from OmegaT+

Here we will use the default English as an example to show this step. The same process can be followed when other localizations are available to use as the original in the localization process.

Copy the OmegaTPlus-rb.properties (English localization default) file from the localizations directory(folder) of the OmegaT+ installation. Put it into your OmegaT+ project (i.e., into the originals directory).

Note: Ensure you have just copied it over and not moved it or deleted it entirely from the OmegaT+ installation location.

Do not alter the default files in the localizations directory at this point. Later when you understand properly how localization works you can make some changes to customize the setup, if you so desire. For now only copy files out and copy your own localizations files back in without disturbing the other ones. If you do disturb them you may end up without any localizations and the program may end up not having any strings to display properly. If they are broken or deleted then you have to replace them with files from the installation package. Not such a big problem, but try to avoid problems that you might not know how to fix initially. Making a backup of the localization files would not be a bad idea either.

As explained in the overview section, localization of the OmegaT+ user interface and program text uses Java .properties files (resource bundles). This is a java based application so this follows. OmegaT+ itself is used to translate these .properties files. Thus, it translates its own user interface resources.

Open Project

Include any other resources you want in the project (e.g., external translation memories[TMs]) into the appropriate locations. If you do use other TMs, ensure that any TM segments you use in the project are under your copyright or are under a GPL compatible license before you start using them. Open the project when ready.

Translate

Proceed to translate as usual, but pay attention to specific formatting or seemingly unusual characters in the segments. Do not alter these, e.g., by removing them, moving them into different orders compared to the text, and so forth. They are necessary for the proper layout and display of the text in the user interface. Of course, there will be places where it does need alteration due to differing lengths of text in the original and translation. The best approach is probably to make small variations in those places where you are unsure and test it in the interface yourself (details follow). Then again, you may not know where in the interface to look for the text.

A few things to look out for:

The use of '&' with certain words. These are used to indicate the letter of a word that is used with a keyboard for faster access to menu items, buttons, and other user interface elements. Careful choice is going to have to be made when translating these so that conflicts do not arise when someone tries to use the keyboard to access a user interface element with them. Usually the first letter of the word or phrase is used, but sometimes there may be multiple elements in a specific window, dialog, menu and so on that begin with the same letter. The usual procedure in this case is to use the next letter in the word. This can be a little tricky in some cases.

Braces containing a number; something like '{0}'. This is a placeholder that the program uses to insert text dynamically into a string. Leave these alone!

Ellipsis. Trailing ellipsis (i.e., '...') is the standard way in a user interface to indicate that another window or dialog is going to be opened by clicking or selecting a certain user interface element. Leave these alone!

Spacing. Pay attention to the default spacing in the original segment between certain elements. For instance, there are colons in some places that have one or two spaces between them and other text. This is deliberate. It is not really the correct way to affect the proper layout (layout and content should be separate), but that is how it is right now. Respect the spacing, even if it does not agree with what your particular language might use in standard writing practice!

There are likely other things I have missed. More to add at a later date.

For any problems just contact us and ask for help.

Generate Translation

Generate the translation as you normally would.

Copy Resource Bundle to OmegaT+

Copy the translation of OmegaTPlus-rb.properties from the translations directory back into the localizations directory of the OmegaT+ installation.

It must not be named exactly the same as the original used for translation. It must have the Locale code in the name. This is set by the program via the Locale codes setting configured when creating the project and through the documents filters configuration (Settings menu). Thus, it should already be named differently, but make sure it corresponds to the proper Locale.

The Java resource bundles that OmegaT+ uses have file names that follow the scheme "OmegaTPlus-rb_xx_YY.properties", where "xx_YY" is the Locale code (language code plus country code).

For example, to use a localization in French requires that the file be named OmegaTPlus-rb_fr.properties. In this case, the country (YY) part of the Locale code has been left out. This is permissible and means that this file serves as the default for French localization when no specific .properties file can be found with a country code for French in its name. If we are to be more specific, with Canada or France as the countries, then the corresponding localization files will be OmegaTPlus-rb_fr_CA.properties and OmegaTPlus-rb_fr_FR.properties, respectively (i.e., Canada = CA, France = FR).

Test Localization

After copying the resource bundle back into OmegaT+, and ensuring that it has the correct Locale naming, you are ready to test out the localization for yourself.

Determine System Locale

You may need to know what Locale your system is using as its default so you can understand exactly what is happening when you try to make OmegaT+ use a localization. When you start OmegaT+ from the shell as you will soon, it will print out there what it thinks the Locale is along with other information. Take note of this. Other ways to find out the Locale include opening a console and typing echo $LOCALE or set, if using a Bash or compatible shell on Linux/OS X/UNIX. On Windows check your system settings.

Here is an example of what I see when starting OmegaT+ from the command line (on Linux using Bash shell in Konsole):

[raymond@localhost OmegaT+1.0.M3.1-src]$ ./OmegaT+

14150: ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
14150: ;;  OmegaT+ 1.0.M3.1 (build:100212), Locale: en_CA, Thu Feb 18 11:45:15 EST 2010
14150:
    

OmegaT+ thinks my Locale is en_CA, which corresponds to Canadian English. This is correct, I am in Canada, but there is no specific Canadian English localization. Does not make any difference though, I still get the default English localization as long as there is no OmegaTPlus-rb_en_CA.properties available. It falls back to using OmegaTPlus-rb.properties in any case where there is no matching localization file.

Once you know what the default Locale is then you can figure out whether OmegaT+ should automatically use your localization (they are the same) or if you need to force it to use the localization (when they differ at all).

Set Locale

If you need to set the localization to be used (the most probable case) then OmegaT+ must be started with certain command line options.

For the example of French you need to enter something like:

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

Where "-Duser.language=" is the option to force a language to be used and "fr" is the language code for French.

For the example of French with Canada and France you would need to enter:

java -Duser.language=fr -Duser.country=CA -jar omegatplus.jar

or

java -Duser.language=fr -Duser.country=FR -jar omegatplus.jar

Where "-Duser.country=" is the option to force a country to be used, with "CA" and "FR" corresponding to the country codes for Canada and France, respectively.

Set Font

Depending upon your Locale you may need to set the font to be used. Not all fonts support all character sets. You must have a compliant font in use for the Locale. The default font may or may not support it. Use the Font Selection dialog (Settings menu) to change it if you see garbage, like little boxes or question marks where characters should be. This means the font in use does not support the Locale. After changing the font its setting will be saved for later use when using the program again.

Include Localization in OmegaT+

If you have got this far, things look good with your localization, and you would like it included into OmegaT+ so others can benefit from your work, then great!

Just get in contact and send us the Java resource bundle for the localization. It will be further tested to verify its functionality. We will contact you about any problems and help out with any problems we find.

Hope what I wrote wasn't too confusing. It is really quite simple once you get used to it and become familiar with how a Java application is localized.

Lastly, thanks for all your hard work!