Translating Archi - archimatetool/archi GitHub Wiki

Please note that these instructions may now be out of date or incorrect. Please feel free to update any errors.

14 February 2018 - Konstantin Borisov has created a Git repository that contains the English language pack that you may find easier to work with. For more information see https://github.com/smeagol74/archi-nls

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:

• Setting up the Eclipse Environment
• Importing the Code
• Running and Debugging Archi

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 com.archimatetool.editor.actions package in the com.archimatetool.editor plug-in:

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 "com.archimatetool.nls" project in the Package Explorer and find the "create-nls.xml" file and open it.
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:

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 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:

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 "com.archimatetool.help.xx" plug-in 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":

2. The file will open so you can edit the values:

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.

Note - 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 (two ' characters). 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 and Debugging Archi for instructions. Remember to add the translated target plug-ins to the list of selected plug-ins on the "Plug-ins" tab of the Run/Debug Configuration dialog.

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

Export the plug-in projects

Once the translations are 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):

3. Ensure the options on the "Options" tab are set as follows:

4. Press Finish

The plug-ins will be exported as folders to the destination directory in a "plugins" folder:

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 Eclipse release. You will need one for the Eclipse workbench.

Unzip this somewhere. The "eclipse" folder contains two sub-folders, "features" and "plugins".

Package everything as a target language pack and install

Combine the target language "plugins" folder that we exported earlier with the "plugins" folder from the Babel language pack. You should end up with a "features" folder and a "plugins" folder

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 of the bundle and copy or move the folders to the "features" and "plugins" folders of their Archi installation. If the target computer is set to run in the target language then Archi will launch using the target language.