== How to translate !MapGuide Maestro ==
On this page you can find instructions on how to translate [wiki:maestro 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 [wiki:maestro/Downloads Download]
* Microsoft .Net Framework 3.5 [http://www.microsoft.com/downloads/details.aspx?familyid=AB99342F-5D1A-413D-8319-81DA479AB0D7]
* Microsoft .Net 2.0 SDK [http://www.microsoft.com/downloads/details.aspx?FamilyID=fe6f2099-b7b4-4f47-a244-c96d69c35dec Download] (Included in Visual Studio 2005 or newer)
* A Subversion client, TortoiseSVN is fine for Windows [http://tortoisesvn.net/downloads 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. [[BR]]
With TortoiseSVN, simply right click on any folder, then choose "TortoiseSVN checkout...".[[BR]]
The repository URL is:
{{{
http://svn.osgeo.org/mapguide/trunk/Tools/Maestro
}}}
You can choose any destination folder you like.[[BR]]
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:
{{{
..\Maestro\bin\debug\Maestro.exe
..
compiled
Maestro
}}}
Everything should be fine, except the `` 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.
=== 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.[[BR]]
This screenshot shows the GUI editor in action:[[BR]]
[[Image(LocalizationGUIScreenshot.png)]]
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 [http://mapguide.osgeo.org/user.html 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:
{{{
OK
...
}}}
'''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 [http://mapguide.osgeo.org/developer.html 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!