Translating Archi

Pre-requisites

In order to make Archi Language Packs you need to install Eclipse and the Archi code. Please read the following sections before proceeding:

Background

Archi's default language is British English. It is possible to run Archi in non-English languages by producing language packs. A language pack is a collection of plug-ins that contain translated *.properties files. Every string that is used in Archi has been externalised into a number of *.properties files. The aim is to produce a mirror set of all of the *.properties files with translated values and bundle these together for redistribution.

As well as translating Archi's language strings remember that Archi is built upon the Eclipse platform which itself consists of a number of plug-ins. These plug-ins also need translating. Luckily this work has been done for some languages in the Eclipse Babel Project.

Translating Properties Files, Packages and Unicode Characters

The following is an example of part of a messages.properties file taken from the uk.ac.bolton.archimate.editor plug-in in the uk.ac.bolton.archimate.editor.actions package:

 ArchimateEditorActionFactory_0=&Delete
 ArchimateEditorActionFactory_1=Delete
 ArchimateEditorActionFactory_2=Rena&me
 ArchimateEditorActionFactory_3=Rename
 ArchimateEditorActionFactory_4=Open &View
 ArchimateEditorActionFactory_5=Close Model
 ArchimateEditorActionFactory_6=Duplicate

If you look at the Archi code in Eclipse you will see that each plug-in contains a "plugin.properties" file and most Java packages within the plug-in contain one "messages.properties" file. Each of these properties files need to be copied to a new language plug-in, renamed to "plugin_xx.properties" and "messages_xx.properties" where "xx" is the target language code, and the values translated into the target language.

Each line in a properties file consists of a key, an equals sign (=), and a value. The key and equals sign (=) must not be changed. It is only the value that must be translated.

Unicode characters

Some characters cannot be saved "as is" to the properties file. Consider the French phrase "Son père est allé à l'hôtel". This contains four accented characters that are not part of the Latin-1 codepage. These characters have to be written as Unicode characters:

Son p\u00e8re est all\u00e9 \u00e0 h\u00f4tel

This is the case for all the characters in languages such as Russian and Bulgarian. For example, the following is an example taken from the Russian Eclipse Babel language pack:

 NewEditorAction_text=\u0421\u043e\u0437\u0434\u0430\u0442\u044c &\u0440\u0435\u0434\u0430
 \u043a\u0442\u043e\u0440
 NewEditorAction_tooltip=\u0421\u043e\u0437\u0434\u0430\u0442\u044c \u0440\u0435\u0434\u0430
 \u043a\u0442\u043e\u0440
 SaveAction_text=\u0421\u043e\u0445\u0440\u0430\u043d\u0438\u0442\u044c@Ctrl+S
 SaveAction_toolTip=\u0421\u043e\u0445\u0440\u0430\u043d\u0438\u0442\u044c
 SaveAs_text=\u0421\u043e\u0445\u0440\u0430\u043d\u0438\u0442\u044c &\u043a\u0430\u043a...
 SaveAs_toolTip=\u0421\u043e\u0445\u0440\u0430\u043d\u0438\u0442\u044c \u043a\u0430\u043a
 SaveAll_text=\u0421\u043e&\u0445\u0440\u0430\u043d\u0438\u0442\u044c \u0432\u0441\u0435
 SaveAll_toolTip=\u0421\u043e\u0445\u0440\u0430\u043d\u0438\u0442\u044c \u0432\u0441\u0435

Fortunately, the Russian translator does not have to worry about this, as there are tools that allow the user to type the string values in the native language and the tool will save the values as Unicode characters.

Translation Tool

We have written such a tool that can be used within Eclipse itself. It is an editor plug-in that allows you to edit the properties files in the user's native language.

The tool can be downloaded here:

com.dadabeatnik.properties.editor_1.0.0.201202091951.jar

Place this jar file in the "dropins" folder of your Eclipse installation and restart Eclipse. We will use this tool later.

Steps for Translation

The necessary steps for translation are:

  1. Create target plug-in projects for the Archi plug-ins
  2. Translate the strings in the properties files
  3. Export the plug-in projects
  4. Download the Eclipse language packs for the target language from the Eclipse Babel Project
  5. Package everything as a target language pack and install

Create target plug-in projects for the Archi plug-ins

  1. Launch Eclipse
  2. Open the "uk.ac.bolton.archimate.build" project in the Package Explorer and find the "create-nls.xml" file in the "nls" folder and open it:
    screenshot
  3. This file is an Ant script that will create the language pack projects from source projects. You will need to edit some values before you run it:
    screenshot
    Change the first value from "en" to the language code of the target language (for example, "ru" for Russian, "de" for German).
    Change the second value to the target version of Archi that you are translating against.
    Change the third value to the version of the language pack you are creating.
  4. Save the file "create-nls.xml"
  5. Right-click on the file "create-nls.xml" in the Package Explorer in Eclipse and select "Run As -> Ant Build". The language plug-ins will be created but you won't see them yet in the Package Explorer until you import them.
  6. From the main Eclipse menu select "File -> Import...". In the Import wizard select "General -> Existing Projects into Workspace".
  7. In the wizard select the "nls" folder that has now been created in your Archi source folder:
    screenshot
  8. Press "Finish" in the wizard

Outputs

You will now see the plug-in projects that were generated by the Ant script in the Package Explorer. Each project will have the target language code appended to its name (for example, "ru" for Russian). Each properties file that needs translating will also have the language code appended (for example, "plugin_ru.properties", "messages_ru.properties" for Russian).

There is also a "nl" folder. This may be empty for some projects. Don't worry if it is empty. If there are files and folders in the "nl" folder, these are assets that will also need to be translated. For example in the "uk.ac.bolton.archimate.help.xx" project there are help files and hints files that will need to be translated.

Translate the strings in the properties files

Now that you have created the target projects you need to translate all the values (the strings to the right of the equals sign ("=") in the target properties files. If you are translating to a language that uses basic ASCII characters (like English) you can edit the properties files directly. If not then you have to edit the files using a tool that saves Unicode characters. Install the translation tool as described above.

  1. Select the properties file to be translated and right-click on it and select the menu item "Open With -> Language Properties Editor":
    screenshot
  2. The file will open so you can edit the values:
    screenshot

Do this for all properties files in the target projects. Remember that in order to enter non-English characters you have to using a computer that is set to the target language.

You do not have to translate a string value if you wish to retain the default (English) value. In fact you can even delete the line in the target properties file. Archi will default to use the in-built English version.

Special Characters in the properties file

Some characters should not be translated. The "&" character denotes a key shortcut for the letter that follows it. For example:

&Empty Model

This means that the "E" key will be used as the short-cut for this command in the application. The translator will have to position the "&" to where it makes sense.

{0} and {1} are placeholders for values that will be inserted at runtime. For example:

File ''{0}'' is already open. Its name is ''{1}''.

At run-time this will become:

File 'c:\somefile.archimate' is already open. Its name is 'My Model'.

The translator will have to move the {0} and {1} placeholders to where they make sense in the translated sentence. Note the double apostrophe (''). Apostrophes that surround place-holders have to be doubled in order to show up.

Testing the translations

At any time you can test your translations by Running Archi from Eclipse. See [[Running Archi]] for instructions. Remember to add the target plug-ins to the list of selected plug-ins on the "Plug-ins" tab of the Configuration dialog.

If you are not using a computer that has been set up to the target language you can add the switch -nl xx to the Program Arguments on the "Arguments" tab of the Configuration dialog. "xx" should be replaced with the target language code (ru, fr, de, nl, etc).

Export the plug-in projects

Once the translations have been completed you need to export the projects as plug-ins.

  1. From the menu select "File -> Export..." In the wizard select "Deployable plug-ins and fragments".
  2. Select all the target plug-ins that end in "xx", where "xx" is the target language code (ru, fr, de, nl, etc):
    screenshot
  3. Ensure the options on the "Options" tab are set as follows:
    screenshot
  4. Press Finish

The plug-ins will be exported as folders to the destination directory:
screenshot

Download the Eclipse language packs for the target language

By this stage you have translated the language strings that are specific to Archi. However, remember that Archi is built upon the Eclipse platform which itself consists of a number of plug-ins. These plug-ins also need translating. Luckily this work has been done for some languages in the Eclipse Babel Project.

Pick the language packs necessary for the "Indigo" release here. You will need one for the Eclipse workbench and one for GEF. For example for the Russian language you will need the following two language packs:

Unzip these somewhere. We won't be needing all of the jar files in the zips. For the Russian language we will need only the following jar files from the eclipse zip plugins folder:

and the following jar file from the gef plugins folder:

Package everything as a target language pack and install

Now the artefacts that we have assembled include the Archi target language plug-in folders that we output earlier and the jar files we collected from the Babel site in the last stage. You will need to zip them up altogether into one bundle if you wish to re-distribute them.

Finally the end user must unzip the contents and copy or move the folders and jar files to the "plugins" folder of their Archi installation. If the target computer is set to run in the target language then Archi will be run in the target language.