Changes between Version 1 and Version 2 of maestro/Translation


Ignore:
Timestamp:
Dec 8, 2009, 2:37:38 PM (14 years ago)
Author:
ksgeograf
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • maestro/Translation

    v1 v2  
    55This document describes how to use the translation system.
    66
    7 == Details ==
     7== Prerequisites ==
     8  * !MapGuide Maestro 1.0.9 r4387 or later [wiki:maestro/Downloads Download]
     9  * Microsoft .Net Framework 2.0 [http://www.microsoft.com/downloads/details.aspx?FamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5 Download] (Should be installed)
     10  * 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)
     11  * A Subversion client, TortoiseSVN is fine for Windows [/http://tortoisesvn.net/downloads Download]
    812
    9 In the folder where you installed !MapGuide Maestro, there exists a folder called "Localization".
    10 Inside this folder are a number of files, all with the extension ResX.
    11 These files are Xml files.
     13All the mentioned files should install and run just fine under Wine, except TortoiseSVN.
    1214
    13 The name of the file refers to the window (form) it is used in.
    14 The filename contains the following structure:
    15 Namespace.Classname.languagecode.resx
     15== Things to replace in this guide ==
     16This 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.
    1617
    17 Some of the files have no language code. These files are the default language (english in this case).
     18The 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.
    1819
    19 To create a new language, simply copy all the files with no language code, and insert the desired language code. If you do not know what language code to use, you can look in the "About" section of the application, where it will list your language code.
     20== Getting the files ==
    2021
    21 The application will detect the added languages on startup. If you wish to submit your translation, I will include it in the next release.
     22To translate files for Maestro, you need to perform a Subversion checkout. [[BR]]
     23With TortoiseSVN, simply right click on any folder, then choose "TortoiseSVN checkout...".[[BR]]
     24The repository URL is:
     25{{{
     26http://svn.osgeo.org/mapguide/trunk/Tools/Maestro
     27}}}
     28You can choose any destination folder you like.[[BR]]
     29When you click OK, the Maestro source code is downloaded, which may take a few minutes.
     30
     31If you have a commandline subversion client, the following command should get the source:
     32{{{
     33svn checkout http://svn.osgeo.org/mapguide/trunk/Tools/Maestro Maestro
     34}}}
     35
     36Whenever there is a change in Maestro, you can update your copy with this command:
     37{{{
     38svn update Maestro
     39}}}
     40
     41With TortoiseSVN, simply right click the folder, and select "TortoiseSVN update".
     42
     43== Update the configuration file ==
     44Inside 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:
     45{{{
     46                <versionassembly>..\Maestro\bin\debug\Maestro.exe</versionassembly>
     47                <sourcefolder>..</sourcefolder>
     48                <outputfolder>compiled</outputfolder>
     49                <productname>Maestro</productname>
     50}}}
     51
     52Everything should be fine, except the `<versionassembly>` path. Since you have not compiled Maestro, this
     53file does not exist. You must update this path to point to the Maestro.exe file that you whish to translate.
     54With a standard Maestro install on an english machine, you can enter:
     55{{{
     56C:\Program Files\OSGeo\MapGuideMaestro\Maestro.exe
     57}}}
     58
     59Remember that localization only works with Maestro 1.0.9 r4387 or newer.
     60
     61You can also install Visual Studio 2009 (Express is fine), and build the solution, which will create the file.
     62
     63== Upgrading from a previous version ==
     64If you have previously created a set of translation files, they need to be converted.
     65If you have no such set, skip this section.
     66
     67Prior to r4387 all files for a language was placed in a folder, and loaded at runtime.
     68Before you attempt this, make sure that the folder you wish to upgrade only contains a single language,
     69also make sure you have a backup of the files.
     70
     71Open a command prompt and run the tool ConvertResX.exe with a single argument, the name of the folder containing the files to use:
     72{{{
     73C:\Documents\Maestro\Localization\ConvertResX.exe C:\Documents\MyTranslationFiles
     74}}}
     75
     76(Note that the ConvertResX tool requires .Net 3.5 or newer).
     77
     78If 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.
     79
     80You can now skip the next section, as the lanuage folder is already created.
     81
     82== Creating a language ==
     83
     84To create a new language, you need to be in a command prompt.
     85To get there, click "Start", then "Run".
     86In the window, type "cmd" and press enter.
     87
     88You now need to go to the folder where you checked out Maestro, eg: C:\Documents\Maestro.
     89{{{
     90cd "\Documents\Maestro\Localization"
     91}}}
     92
     93Run the LocalizationTool.exe to create the language, eg en-US:
     94{{{
     95LocalizationTool.exe create en-US
     96}}}
     97
     98Wait a little, and there should now be a folder called "en-US".
     99Inside this folder, you can now translate the .resx files and .txt files.
     100
     101== Word of warning ==
     102
     103It can be a tedious task to translate large amounts of text.
     104
     105I recommend that you do not attempt to translate everything in one stretch.
     106
     107Try to allocate an hour or two each other day, and stop after that time, and
     108rest until the next turn.
     109
     110
     111=== Localizing windows (forms) ===
     112
     113Many resx files will exist twice:
     114{{{
     115ApplicationSetup.resx
     116ApplicationSetup.en-US.resx
     117}}}
     118
     119You can open the localized version with the "winres.exe" tool avalible in the .Net SDK, which you have installed.
     120
     121If 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.
     122
     123Once done, save the file.
     124
     125=== Localizing strings ===
     126Maestro contains a number of messages that are not directly displayed in a window, primarily as error messages.
     127
     128Unfortunately the "winres.exe" does not support editing these files, so you have to use a text editor, such as the free [http://notepad-plus.sourceforge.net/uk/download.php Notepad++].
     129
     130All the files that are missing a "neutral" resx file (those with only a `*`.en-US.resx file) must be edited with a text editor. They all start with a lot of boilerplate system code, and then multiple entries of the form:
     131{{{
     132  <data name="TimeParseError" xml:space="preserve">
     133    <value>Unable to parse "{0}" into a time offset: {1}</value>
     134  </data>
     135}}}
     136
     137The "name" attribute is a system key, and may not be changed.
     138The text between the {{{<value>}}} and {{{</value>}}} is the one that needs translating.
     139The special items {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].
     140
     141== Building and testing the dll's ==
     142
     143When you are ready to test your work, run the following command:
     144{{{
     145LocalizationTool.exe build en-US
     146}}}
     147
     148This will build the resource assemblies, and place them in the folder called "compiled".
     149Inside the "compiled" folder you will now see a folder called "en-US".
     150Copy this folder to your Maestro installation, so you get a folder structure like:
     151{{{
     152C:\Program Files\Maestro\Maestro.exe
     153C:\Program Files\Maestro\en-US\Maestro.resources.dll
     154}}}
     155
     156In the logon dialog, you can now select the new language. After selecting the new language, you must restart Maestro.
     157
     158== Contributing a translation ==
     159Once you translate all the files, you can contribute them to the Maestro project,
     160so others may benefit from your hard work.
     161
     162Before 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.
     163
     164== Getting credit ==
     165All credits are placed in the "About" box in !MapGuide Maestro.
     166In the ticket please specify what text you would like placed in the credits section.
     167
     168Happy translating!