How to translate MapGuide Maestro

On this page you can find instructions on how to translate MapGuide Maestro to your native language.

The current version of MapGuide Maestro is fully localizeable. This document describes how to use the translation system.

Prerequisites

• MapGuide Maestro 1.0.9 r4431 or later Download
• Microsoft .Net Framework 3.5 ​http://www.microsoft.com/downloads/details.aspx?familyid=AB99342F-5D1A-413D-8319-81DA479AB0D7
• Microsoft .Net 2.0 SDK ​Download (Included in Visual Studio 2005 or newer)
• A Subversion client, TortoiseSVN is fine for Windows ​Download

All the mentioned files should install and run just fine under Wine, except TortoiseSVN.

Things to replace in this guide

This guide uses C:\Documents\Maestro to indicate the folder where Maestro is checked out, you must replace that folder name with the name of the folder where you have the Maestro source code.

The language chosen for this guide is "en-US" which is american-english. You must replace this with your contry code. Your operating systems country code can be seen in the "About" box inside Maestro, otherwise you have to search the web a little.

Getting the files

To translate files for Maestro, you need to perform a Subversion checkout.
With TortoiseSVN, simply right click on any folder, then choose "TortoiseSVN checkout...".
The repository URL is:

http://svn.osgeo.org/mapguide/trunk/Tools/Maestro

You can choose any destination folder you like.
When you click OK, the Maestro source code is downloaded, which may take a few minutes.

If you have a commandline subversion client, the following command should get the source:

svn checkout http://svn.osgeo.org/mapguide/trunk/Tools/Maestro Maestro

Whenever there is a change in Maestro, you can update your copy with this command:

svn update Maestro

With TortoiseSVN, simply right click the folder, and select "TortoiseSVN update".

Update the configuration file

Inside the folder you just created by downloading the source, there should exist a folder called "Localization". In this folder, you must edit the file "configuration.xml". Near the bottom of the document you will find:

		<versionassembly>..\Maestro\bin\debug\Maestro.exe</versionassembly>
		<sourcefolder>..</sourcefolder>
		<outputfolder>compiled</outputfolder>
		<productname>Maestro</productname>

Everything should be fine, except the <versionassembly> path. Since you have not compiled Maestro, this file does not exist. You must update this path to point to the Maestro.exe file that you whish to translate. With a standard Maestro install on an english machine, you can enter:

C:\Program Files\OSGeo\MapGuideMaestro\Maestro.exe

Remember that localization only works with Maestro 1.0.9 r4431 or newer.

You can also install Visual Studio 2009 (Express is fine), and build the solution, which will create the file.

Upgrading from a previous version

If you have previously created a set of translation files, they need to be converted. If you have no such set, skip this section.

Prior to r4431 all files for a language was placed in a folder, and loaded at runtime. Before you attempt this, make sure that the folder you wish to upgrade only contains a single language, also make sure you have a backup of the files.

Open a command prompt and run the tool ConvertResX.exe with a single argument, the name of the folder containing the files to use:

C:\Documents\Maestro\Localization\ConvertResX.exe C:\Documents\MyTranslationFiles

(Note that the ConvertResX tool requires .Net 3.5 or newer).

If the folder you are converting contains .en-US.resx files, there will now be a folder called "en-US" under the Localization folder, and a file called missing.en-US.txt. The folder contains the converted set of resx files, and the missing.en-US.txt file contains a report of strings that failed to translate automatically.

You can now skip the next section, as the lanuage folder is already created.

Creating a language

To create a new language, you need to be in a command prompt. To get there, click "Start", then "Run". In the window, type "cmd" and press enter.

You now need to go to the folder where you checked out Maestro, eg: C:\Documents\Maestro.

cd "\Documents\Maestro\Localization"

Run the LocalizationTool.exe to create the language, eg en-US:

LocalizationTool.exe create en-US

Wait a little, and there should now be a folder called "en-US". Inside this folder, you can now translate the .resx files and .txt files.

Word of warning

It can be a tedious task to translate large amounts of text.

I recommend that you do not attempt to translate everything in one stretch.

Try to allocate an hour or two each other day, and stop after that time, and rest until the next turn.

This is especially true if you are translating Maestro 3.0 as it has about 2-3 times the amount of localizable text

Localizing strings

Inside the newly created folder, there exists a file called "gui update.bat".

Simply doubleclick this file, and a GUI editor will show you all the strings that needs to be updated.
This screenshot shows the GUI editor in action:

There is a counter in the top which shows the number of items remaining.

Special items, such as {0} and {1} are placeholders for some text that Maestro will insert. It should be fairly obvious what the fields will be substituted with, but if in doubt, ask on the MapGuide-Users mail list.

For most languages, there are some texts that are the same, such as "OK" or "...". To prevent these from showing in the editor, place a file called "ignore.en-US.xml" in the same folder as the LocalizationTool.exe, and insert strings to ignore in this format:

<root>
  <ignore>OK</ignore>
  <ignore>...</ignore>
</root>

Please Note For Maestro 3.0, for each assembly, all resources have been bundled into a single resx file. As a result, you may find entries for images and icons in the Localization Tool. These resources do not require any localization and can be ignored

Localizing windows (forms)

Many resx files will exist twice:

ApplicationSetup.resx
ApplicationSetup.en-US.resx

You can open the localized version with the "winres.exe" tool avalible in the .Net SDK, which you have installed.

If you open the file ApplicationSetup.en-US.resx with "Windows Resource Localization Editor" (the shortcut for winres.exe), you can visually see the window, and modify it interactively. You can move things around to correctly display text, but please try to keep the layout as close to the original as possible.

It is recommended that you use the "update gui.bat" method to update strings, but using the winres.exe program it may be easier to determine the context for the item being translated.

Once done, save the file.

Building and testing the dll's

When you are ready to test your work, run the following command:

LocalizationTool.exe build en-US

This will build the resource assemblies, and place them in the folder called "compiled". Inside the "compiled" folder you will now see a folder called "en-US". Copy this folder to your Maestro installation, so you get a folder structure like:

C:\Program Files\Maestro\Maestro.exe
C:\Program Files\Maestro\en-US\Maestro.resources.dll

In the logon dialog, you can now select the new language. After selecting the new language, you must restart Maestro.

Contributing a translation

Once you translate all the files, you can contribute them to the Maestro project, so others may benefit from your hard work.

Before you can submit the translation files, you must sign and submit a Contributor License Agreement. Once the CLA is signed and recieved, either submit the files as a ticket on Trac, or announce it on the mapguide-users or mapguide-internals list.

Getting credit

All credits are placed in the "About" box in MapGuide Maestro. In the ticket please specify what text you would like placed in the credits section.

Happy translating!