Translating Archi
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
In order to make Archi Language Packs you need to install Eclipse and the Archi code. Please read the following sections before proceeding:
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.
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.
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.
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.
The necessary steps for translation are:
- Create target plug-in projects for the Archi plug-ins
- Translate the strings in the properties files
- Export the plug-in projects
- Download the Eclipse language packs for the target language from the Eclipse Babel Project
- Package everything as a target language pack and install
- Launch Eclipse
- Open the "com.archimatetool.nls" project in the Package Explorer and find the "create-nls.xml" file and open it.
- 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.
- Save the file "create-nls.xml"
- 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.
- From the main Eclipse menu select "File -> Import...". In the Import wizard select "General -> Existing Projects into Workspace".
- In the wizard select the "nls" folder that has now been created in your Archi source folder:
- Press "Finish" in the wizard
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.
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.
- Select the properties file to be translated and right-click on it and select the menu item "Open With -> Language Properties Editor":
- 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.
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.
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).
Once the translations are completed you need to export the projects as plug-ins.
- From the menu select "File -> Export..." In the wizard select "Deployable plug-ins and fragments".
- Select all the target plug-ins that end in "xx", where "xx" is the target language code (ru, fr, de, nl, etc):
- Ensure the options on the "Options" tab are set as follows:
- Press Finish
The plug-ins will be exported as folders to the destination directory in a "plugins" folder:
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".
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.